@kontext-dev/js-sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,4029 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { isInitializeRequest, UrlElicitationRequiredError, ElicitRequestSchema, ElicitationCompleteNotificationSchema } from '@modelcontextprotocol/sdk/types.js';
+import { createHash, randomBytes } from 'crypto';
+import { createRequire } from 'module';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { mcpAuthMetadataRouter, getOAuthProtectedResourceMetadataUrl } from '@modelcontextprotocol/sdk/server/auth/router.js';
+import { requireBearerAuth } from '@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js';
+import { InvalidTokenError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
+import { jwtVerify, errors, decodeProtectedHeader, createRemoteJWKSet } from 'jose';
+
+// src/mcp/client.ts
+
+// src/storage/memory.ts
+var MemoryStorage = class {
+  store = /* @__PURE__ */ new Map();
+  async getJson(key) {
+    const value = this.store.get(key);
+    if (value === void 0) {
+      return void 0;
+    }
+    return JSON.parse(JSON.stringify(value));
+  }
+  async setJson(key, value) {
+    if (value === void 0) {
+      this.store.delete(key);
+    } else {
+      this.store.set(key, JSON.parse(JSON.stringify(value)));
+    }
+  }
+  /**
+   * Clear all stored data
+   */
+  clear() {
+    this.store.clear();
+  }
+  /**
+   * Get the number of stored items
+   */
+  get size() {
+    return this.store.size;
+  }
+  /**
+   * Check if a key exists
+   */
+  has(key) {
+    return this.store.has(key);
+  }
+  /**
+   * Get all keys (useful for debugging)
+   */
+  keys() {
+    return Array.from(this.store.keys());
+  }
+};
+
+// src/storage/types.ts
+function createStorageKey(applicationClientId, sessionKey, ...parts) {
+  const namespace = sessionKey ? `kontext:${applicationClientId}:${sessionKey}` : `kontext:${applicationClientId}`;
+  return [namespace, ...parts].join(":");
+}
+var StorageKeys = {
+  // Existing keys
+  TOKENS: "tokens",
+  CODE_VERIFIER: "code_verifier",
+  STATE: "state",
+  // Pattern B (RFC 8693 Token Exchange) keys
+  /** Identity tokens (no audience) */
+  IDENTITY_TOKENS: "identity_tokens",
+  /** Prefix for resource-scoped tokens */
+  RESOURCE_TOKENS: "resource_tokens"
+};
+function resourceTokenKey(resource) {
+  return `${StorageKeys.RESOURCE_TOKENS}:${resource}`;
+}
+
+// src/errors.ts
+var KontextError = class extends Error {
+  /** Brand field for type narrowing without instanceof */
+  kontextError = true;
+  /** Machine-readable error code, always prefixed with `kontext_` */
+  code;
+  /** HTTP status code when applicable */
+  statusCode;
+  /** Auto-generated link to error documentation */
+  docsUrl;
+  /** Server request ID for debugging / support escalation */
+  requestId;
+  /** Contextual metadata bag (integration IDs, param names, etc.) */
+  meta;
+  constructor(message, code, options) {
+    super(message, { cause: options?.cause });
+    this.name = "KontextError";
+    this.code = code;
+    this.statusCode = options?.statusCode;
+    this.requestId = options?.requestId;
+    this.meta = options?.meta ?? {};
+    this.docsUrl = `https://docs.kontext.dev/errors/${code}`;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      statusCode: this.statusCode,
+      docsUrl: this.docsUrl,
+      requestId: this.requestId,
+      meta: Object.keys(this.meta).length > 0 ? this.meta : void 0
+    };
+  }
+  toString() {
+    const parts = [`[${this.code}] ${this.message}`];
+    if (this.docsUrl) parts.push(`Docs: ${this.docsUrl}`);
+    if (this.requestId) parts.push(`Request ID: ${this.requestId}`);
+    return parts.join("\n");
+  }
+};
+function isKontextError(err) {
+  return typeof err === "object" && err !== null && err.kontextError === true;
+}
+var AuthorizationRequiredError = class extends KontextError {
+  authorizationUrl;
+  constructor(message = "Authorization required. Complete the OAuth flow to continue.", options) {
+    super(message, "kontext_authorization_required", {
+      statusCode: 401,
+      ...options
+    });
+    this.name = "AuthorizationRequiredError";
+    this.authorizationUrl = options?.authorizationUrl;
+  }
+};
+var OAuthError = class extends KontextError {
+  errorCode;
+  errorDescription;
+  constructor(message, code, options) {
+    super(message, code, {
+      statusCode: options?.statusCode ?? 400,
+      ...options
+    });
+    this.name = "OAuthError";
+    this.errorCode = options?.errorCode;
+    this.errorDescription = options?.errorDescription;
+  }
+};
+var IntegrationConnectionRequiredError = class extends KontextError {
+  integrationId;
+  integrationName;
+  connectUrl;
+  constructor(integrationId, options) {
+    super(
+      options?.message ?? `Connection to integration "${integrationId}" is required. Visit the connect URL to authorize.`,
+      "kontext_integration_connection_required",
+      { statusCode: 403, ...options }
+    );
+    this.name = "IntegrationConnectionRequiredError";
+    this.integrationId = integrationId;
+    this.integrationName = options?.integrationName;
+    this.connectUrl = options?.connectUrl;
+  }
+};
+var ConfigError = class extends KontextError {
+  constructor(message, code, options) {
+    super(message, code, options);
+    this.name = "ConfigError";
+  }
+};
+var NetworkError = class extends KontextError {
+  constructor(message = "Network error. Check your internet connection and that the server is reachable.", options) {
+    super(message, "kontext_network_error", options);
+    this.name = "NetworkError";
+  }
+};
+var HttpError = class extends KontextError {
+  retryAfter;
+  validationErrors;
+  constructor(message, code, options) {
+    super(message, code, {
+      statusCode: options?.statusCode,
+      ...options
+    });
+    this.name = "HttpError";
+    this.retryAfter = options?.retryAfter;
+    this.validationErrors = options?.validationErrors;
+  }
+};
+function errorProps(err) {
+  return err;
+}
+var NETWORK_ERROR_CODES = /* @__PURE__ */ new Set([
+  "ECONNREFUSED",
+  "ENOTFOUND",
+  "ETIMEDOUT",
+  "ECONNRESET",
+  "ECONNABORTED",
+  "EPIPE",
+  "UND_ERR_CONNECT_TIMEOUT"
+]);
+function isNetworkError(err) {
+  if (err.name === "AbortError") return true;
+  const props = errorProps(err);
+  const sysCode = props.code;
+  if (typeof sysCode === "string" && NETWORK_ERROR_CODES.has(sysCode))
+    return true;
+  if (err.name === "TypeError" && err.cause instanceof Error) {
+    const causeCode = errorProps(err.cause).code;
+    if (typeof causeCode === "string" && NETWORK_ERROR_CODES.has(causeCode))
+      return true;
+  }
+  return false;
+}
+function isUnauthorizedError(err) {
+  const props = errorProps(err);
+  if (props.statusCode === 401 || props.status === 401) return true;
+  if (err.name === "UnauthorizedError") return true;
+  if (err.message === "Unauthorized") return true;
+  return false;
+}
+function parseHttpError(statusCode, body) {
+  const message = typeof body === "object" && body !== null && "message" in body ? String(body.message) : `HTTP ${statusCode}`;
+  const errorCode = typeof body === "object" && body !== null && "code" in body ? String(body.code) : void 0;
+  switch (statusCode) {
+    case 400:
+      if (typeof body === "object" && body !== null && "errors" in body && Array.isArray(body.errors)) {
+        return new HttpError(message, "kontext_validation_error", {
+          statusCode: 400,
+          validationErrors: body.errors
+        });
+      }
+      return new KontextError(message, errorCode ?? "kontext_bad_request", {
+        statusCode: 400
+      });
+    case 401:
+      return new AuthorizationRequiredError(message);
+    case 403:
+      if (errorCode === "INTEGRATION_CONNECTION_REQUIRED") {
+        const details = body;
+        return new IntegrationConnectionRequiredError(
+          details.integrationId ?? "unknown",
+          {
+            integrationName: details.integrationName,
+            connectUrl: details.connectUrl,
+            message
+          }
+        );
+      }
+      return new HttpError(message, "kontext_policy_denied", {
+        statusCode: 403,
+        meta: { policy: body?.policy }
+      });
+    case 404:
+      return new HttpError(message, "kontext_not_found", { statusCode: 404 });
+    case 429: {
+      const retryAfter = typeof body === "object" && body !== null && "retryAfter" in body ? Number(body.retryAfter) : void 0;
+      return new HttpError(
+        retryAfter ? `Rate limit exceeded. Retry after ${retryAfter} seconds.` : "Rate limit exceeded. Wait and retry.",
+        "kontext_rate_limited",
+        { statusCode: 429, retryAfter }
+      );
+    }
+    default:
+      if (statusCode >= 500) {
+        return new HttpError(
+          `Server error (HTTP ${statusCode}): ${message}`,
+          "kontext_server_error",
+          { statusCode }
+        );
+      }
+      return new KontextError(message, errorCode ?? "kontext_unknown_error", {
+        statusCode
+      });
+  }
+}
+
+// src/oauth/provider.ts
+var KontextOAuthProvider = class {
+  config;
+  storagePrefix;
+  pendingState = null;
+  expiryBufferMs = 60 * 1e3;
+  constructor(config) {
+    this.config = config;
+    this.storagePrefix = createStorageKey(config.clientId, config.sessionKey);
+  }
+  /**
+   * The redirect URL for OAuth callbacks
+   */
+  get redirectUrl() {
+    return this.config.redirectUri;
+  }
+  /**
+   * OAuth client metadata
+   */
+  get clientMetadata() {
+    return {
+      redirect_uris: [this.config.redirectUri],
+      client_name: this.config.clientName,
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      token_endpoint_auth_method: "none"
+      // Public client
+    };
+  }
+  /**
+   * Generate a random state parameter for OAuth CSRF protection
+   */
+  state() {
+    const array = new Uint8Array(32);
+    if (globalThis.crypto?.getRandomValues) {
+      globalThis.crypto.getRandomValues(array);
+    } else {
+      array.set(randomBytes(32));
+    }
+    const state = Array.from(
+      array,
+      (byte) => byte.toString(16).padStart(2, "0")
+    ).join("");
+    this.pendingState = state;
+    void this.config.storage.setJson(
+      this.getStorageKey(StorageKeys.STATE),
+      state
+    );
+    return state;
+  }
+  /**
+   * Returns the client information (client_id)
+   * Since we're a public client with pre-registered credentials,
+   * we don't use dynamic client registration.
+   */
+  async clientInformation() {
+    return {
+      client_id: this.config.clientId
+    };
+  }
+  /**
+   * Load stored OAuth tokens
+   */
+  async tokens() {
+    const key = this.getStorageKey(StorageKeys.TOKENS);
+    return this.config.storage.getJson(key);
+  }
+  /**
+   * Save OAuth tokens after successful authorization
+   */
+  async saveTokens(tokens) {
+    const key = this.getStorageKey(StorageKeys.TOKENS);
+    await this.config.storage.setJson(key, this.withIssuedAt(tokens));
+  }
+  /**
+   * Redirect the user agent to the authorization URL
+   */
+  async redirectToAuthorization(authorizationUrl) {
+    await this.config.onRedirectToAuthorization(authorizationUrl);
+  }
+  /**
+   * Save the PKCE code verifier before redirecting to authorization
+   */
+  async saveCodeVerifier(codeVerifier) {
+    const key = this.getStorageKey(StorageKeys.CODE_VERIFIER);
+    await this.config.storage.setJson(key, codeVerifier);
+  }
+  /**
+   * Load the PKCE code verifier for token exchange
+   */
+  async codeVerifier() {
+    const key = this.getStorageKey(StorageKeys.CODE_VERIFIER);
+    const verifier = await this.config.storage.getJson(key);
+    if (!verifier) {
+      throw new OAuthError(
+        "No PKCE code verifier found in storage. The OAuth flow may have expired or storage was cleared. Restart the auth flow.",
+        "kontext_oauth_code_verifier_missing"
+      );
+    }
+    return verifier;
+  }
+  /**
+   * Invalidate stored credentials
+   */
+  async invalidateCredentials(scope) {
+    if (scope === "all" || scope === "tokens") {
+      const tokensKey = this.getStorageKey(StorageKeys.TOKENS);
+      await this.config.storage.setJson(tokensKey, void 0);
+      const identityKey = this.getStorageKey(StorageKeys.IDENTITY_TOKENS);
+      await this.config.storage.setJson(identityKey, void 0);
+    }
+    if (scope === "all" || scope === "verifier") {
+      const verifierKey = this.getStorageKey(StorageKeys.CODE_VERIFIER);
+      await this.config.storage.setJson(verifierKey, void 0);
+    }
+    if (scope === "all") {
+      this.pendingState = null;
+      const stateKey = this.getStorageKey(StorageKeys.STATE);
+      await this.config.storage.setJson(stateKey, void 0);
+    }
+  }
+  /**
+   * Clear all stored state (tokens, verifier, etc.)
+   * Call this to force re-authentication
+   */
+  async clearAll() {
+    await this.invalidateCredentials("all");
+  }
+  /**
+   * Check if we have valid (non-expired) tokens
+   */
+  async hasValidTokens() {
+    const storedTokens = await this.tokens();
+    return this.isTokenValid(storedTokens);
+  }
+  // ==========================================================================
+  // Pattern B: Identity and Resource Token Management (RFC 8693)
+  // ==========================================================================
+  /**
+   * Save identity tokens (no audience)
+   * These are the tokens obtained from the initial OAuth flow before token exchange.
+   */
+  async saveIdentityTokens(tokens) {
+    const key = this.getStorageKey(StorageKeys.IDENTITY_TOKENS);
+    await this.config.storage.setJson(key, this.withIssuedAt(tokens));
+  }
+  /**
+   * Load identity tokens
+   * Returns the identity tokens obtained from the initial OAuth flow.
+   */
+  async identityTokens() {
+    const key = this.getStorageKey(StorageKeys.IDENTITY_TOKENS);
+    return this.config.storage.getJson(key);
+  }
+  /**
+   * Save resource-scoped tokens for a specific resource
+   *
+   * @param resource The resource identifier (e.g., "mcp-gateway")
+   * @param tokens The resource-scoped tokens
+   */
+  async saveResourceTokens(resource, tokens) {
+    const key = this.getStorageKey(resourceTokenKey(resource));
+    await this.config.storage.setJson(key, this.withIssuedAt(tokens));
+  }
+  /**
+   * Load resource-scoped tokens for a specific resource
+   *
+   * @param resource The resource identifier (e.g., "mcp-gateway")
+   * @returns The resource-scoped tokens, or undefined if not found
+   */
+  async resourceTokens(resource) {
+    const key = this.getStorageKey(resourceTokenKey(resource));
+    return this.config.storage.getJson(key);
+  }
+  /**
+   * Clear resource tokens for a specific resource
+   *
+   * @param resource The resource identifier (e.g., "mcp-gateway")
+   */
+  async clearResourceTokens(resource) {
+    const key = this.getStorageKey(resourceTokenKey(resource));
+    await this.config.storage.setJson(key, void 0);
+  }
+  /**
+   * Check if we have valid identity tokens
+   */
+  async hasValidIdentityTokens() {
+    const tokens = await this.identityTokens();
+    return this.isTokenValid(tokens);
+  }
+  /**
+   * Check if we have valid resource tokens for a specific resource
+   *
+   * @param resource The resource identifier
+   */
+  async hasValidResourceTokens(resource) {
+    const tokens = await this.resourceTokens(resource);
+    return this.isTokenValid(tokens);
+  }
+  async validateState(state) {
+    if (!state) {
+      return false;
+    }
+    const key = this.getStorageKey(StorageKeys.STATE);
+    const storedState = this.pendingState ?? await this.config.storage.getJson(key);
+    const isValid = storedState === state;
+    if (isValid) {
+      this.pendingState = null;
+      await this.config.storage.setJson(key, void 0);
+    }
+    return isValid;
+  }
+  withIssuedAt(tokens) {
+    if (!tokens.expires_in) {
+      return tokens;
+    }
+    return { ...tokens, issued_at: Date.now() };
+  }
+  isTokenValid(tokens) {
+    if (!tokens?.access_token) {
+      return false;
+    }
+    if (!tokens.expires_in) {
+      return true;
+    }
+    const issuedAt = tokens.issued_at;
+    if (!issuedAt) {
+      return true;
+    }
+    const expiresAt = issuedAt + tokens.expires_in * 1e3;
+    return Date.now() < expiresAt - this.expiryBufferMs;
+  }
+  getStorageKey(key) {
+    return `${this.storagePrefix}:${key}`;
+  }
+};
+function parseOAuthCallback(callbackUrl) {
+  const url = typeof callbackUrl === "string" ? new URL(callbackUrl) : callbackUrl;
+  const params = url.searchParams;
+  const error = params.get("error");
+  if (error) {
+    return {
+      error,
+      errorDescription: params.get("error_description") ?? void 0
+    };
+  }
+  return {
+    code: params.get("code") ?? void 0,
+    state: params.get("state") ?? void 0
+  };
+}
+
+// src/mcp/client.ts
+var DEFAULT_SERVER = "https://api.kontext.dev";
+function normalizeKontextServerUrl(server) {
+  let url = server.replace(/\/$/, "");
+  url = url.replace(/\/api\/v1\/?$/, "").replace(/\/mcp\/?$/, "");
+  url = url.replace(/\/$/, "");
+  return url;
+}
+var KontextMcp = class {
+  config;
+  storage;
+  oauthProvider;
+  transport = null;
+  client = null;
+  _isConnected = false;
+  _pendingConnect = null;
+  _pendingAuthFlow = null;
+  _authFlowResolve = null;
+  constructor(config) {
+    this.config = config;
+    this.storage = config.storage ?? new MemoryStorage();
+    this.oauthProvider = new KontextOAuthProvider({
+      clientId: config.clientId,
+      redirectUri: config.redirectUri,
+      storage: this.storage,
+      sessionKey: config.sessionKey ?? "default",
+      clientName: config.clientName,
+      onRedirectToAuthorization: async (url) => {
+        this._pendingAuthFlow = new Promise((resolve) => {
+          this._authFlowResolve = resolve;
+        });
+        const result = await config.onAuthRequired(url);
+        if (result) {
+          await this.handleCallback(result);
+        }
+      }
+    });
+  }
+  /**
+   * Check if we're currently connected
+   */
+  get isConnected() {
+    return this._isConnected;
+  }
+  /**
+   * Get the underlying MCP client for advanced usage
+   */
+  get mcpClient() {
+    return this.client;
+  }
+  /**
+   * Get the session ID from the transport
+   */
+  get sessionId() {
+    return this.transport?.sessionId;
+  }
+  /**
+   * Get the server base URL
+   */
+  get serverUrl() {
+    return normalizeKontextServerUrl(this.config.server ?? DEFAULT_SERVER);
+  }
+  /**
+   * Get the MCP endpoint URL.
+   * When `url` is provided, use it directly. Otherwise derive from server.
+   */
+  get mcpEndpointUrl() {
+    return this.config.url ?? `${this.serverUrl}/mcp`;
+  }
+  /**
+   * List available tools from the server
+   *
+   * This will automatically handle authentication if needed.
+   */
+  async listTools() {
+    await this.ensureConnected();
+    const response = await this.client.listTools();
+    return response.tools;
+  }
+  /**
+   * Call a tool
+   *
+   * This will automatically handle authentication if needed.
+   *
+   * @param name The tool name
+   * @param args The tool arguments
+   */
+  async callTool(name, args) {
+    await this.ensureConnected();
+    try {
+      const result = await this.client.callTool({
+        name,
+        arguments: args
+      });
+      return result;
+    } catch (error) {
+      if (error instanceof UrlElicitationRequiredError && this.config.onElicitationUrl) {
+        for (const elicitation of error.elicitations) {
+          await this.config.onElicitationUrl({
+            url: elicitation.url,
+            message: elicitation.message ?? "Action required",
+            elicitationId: elicitation.elicitationId ?? "",
+            integrationId: elicitation.integrationId,
+            integrationName: elicitation.integrationName
+          });
+        }
+      }
+      throw error;
+    }
+  }
+  /**
+   * Create a connect session for the hosted connect UI.
+   *
+   * Returns a URL that can be opened in a browser to let the user
+   * connect integrations proactively (before hitting -32042 errors).
+   */
+  async createConnectSession() {
+    const tokens = await this.oauthProvider.tokens();
+    if (!tokens?.access_token) {
+      throw new AuthorizationRequiredError(
+        "Authorization required. Complete the OAuth flow first."
+      );
+    }
+    const response = await fetch(`${this.serverUrl}/mcp/connect-session`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${tokens.access_token}`,
+        "Content-Type": "application/json"
+      }
+    });
+    if (response.status === 401) {
+      throw new AuthorizationRequiredError(
+        "Access token expired or invalid. Re-authenticate and retry."
+      );
+    }
+    if (!response.ok) {
+      throw new KontextError(
+        `Failed to create connect session: HTTP ${response.status}`,
+        "kontext_connect_session_failed",
+        { statusCode: response.status }
+      );
+    }
+    return await response.json();
+  }
+  /**
+   * List integrations attached to the current application/runtime identity.
+   *
+   * This is used by higher-level orchestrators to discover mixed integration
+   * topologies (gateway + internal credential integrations).
+   */
+  async listRuntimeIntegrations() {
+    const tokens = await this.oauthProvider.tokens();
+    if (!tokens?.access_token) {
+      throw new AuthorizationRequiredError(
+        "Authorization required. Complete the OAuth flow first."
+      );
+    }
+    const response = await fetch(`${this.serverUrl}/mcp/integrations`, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${tokens.access_token}`
+      }
+    });
+    if (response.status === 401) {
+      throw new AuthorizationRequiredError(
+        "Access token expired or invalid. Re-authenticate and retry."
+      );
+    }
+    if (!response.ok) {
+      throw new KontextError(
+        `Failed to list runtime integrations: HTTP ${response.status}`,
+        "kontext_runtime_integrations_failed",
+        { statusCode: response.status }
+      );
+    }
+    const payload = await response.json();
+    const items = Array.isArray(payload?.items) ? payload.items : [];
+    return items.map((item) => {
+      const id = typeof item.id === "string" ? item.id : "";
+      const name = typeof item.name === "string" ? item.name : id;
+      const url = typeof item.url === "string" ? item.url : "";
+      if (!id || !url) return null;
+      const category = item.category === "internal_mcp_credentials" ? "internal_mcp_credentials" : "gateway_remote_mcp";
+      const connectType = item.connectType === "credentials" || item.connectType === "oauth" || item.connectType === "none" ? item.connectType : category === "internal_mcp_credentials" ? "credentials" : item.authMode === "oauth" ? "oauth" : "none";
+      const rawConnection = item.connection && typeof item.connection === "object" ? item.connection : void 0;
+      const connected = rawConnection && typeof rawConnection.connected === "boolean" ? rawConnection.connected : false;
+      const status = rawConnection?.status === "connected" ? "connected" : "disconnected";
+      return {
+        id,
+        name,
+        url,
+        category,
+        connectType,
+        authMode: item.authMode === "oauth" || item.authMode === "user_token" || item.authMode === "server_token" || item.authMode === "none" ? item.authMode : void 0,
+        credentialSchema: item.credentialSchema,
+        requiresOauth: typeof item.requiresOauth === "boolean" ? item.requiresOauth : void 0,
+        connection: rawConnection ? {
+          connected,
+          status,
+          expiresAt: typeof rawConnection.expiresAt === "string" ? rawConnection.expiresAt : void 0,
+          displayName: typeof rawConnection.displayName === "string" ? rawConnection.displayName : void 0
+        } : void 0
+      };
+    }).filter((item) => item !== null);
+  }
+  /**
+   * Handle an OAuth callback URL
+   *
+   * Call this after the user has been redirected back from authorization.
+   * This is required for web apps where `onAuthRequired` redirects instead of waiting.
+   *
+   * @param callbackUrl The full callback URL with query parameters
+   */
+  async handleCallback(callbackUrl) {
+    const { code, state, error, errorDescription } = parseOAuthCallback(callbackUrl);
+    if (error) {
+      this._authFlowResolve?.();
+      this._authFlowResolve = null;
+      throw new AuthorizationRequiredError(
+        errorDescription ?? `OAuth error: ${error}`
+      );
+    }
+    const isValidState = await this.oauthProvider.validateState(state);
+    if (!isValidState) {
+      this._authFlowResolve?.();
+      this._authFlowResolve = null;
+      throw new OAuthError(
+        "OAuth state validation failed. The state parameter did not match. Retry the authorization flow.",
+        "kontext_oauth_state_invalid"
+      );
+    }
+    if (!code) {
+      this._authFlowResolve?.();
+      this._authFlowResolve = null;
+      throw new AuthorizationRequiredError(
+        "No authorization code in callback URL"
+      );
+    }
+    try {
+      if (!this.transport) {
+        this.transport = new StreamableHTTPClientTransport(
+          new URL(this.mcpEndpointUrl),
+          {
+            authProvider: this.oauthProvider
+          }
+        );
+      }
+      await this.transport.finishAuth(code);
+      const tokens = await this.oauthProvider.tokens();
+      if (!tokens?.access_token) {
+        throw new AuthorizationRequiredError("Failed to obtain tokens");
+      }
+      await this.oauthProvider.saveTokens(tokens);
+    } finally {
+      this._authFlowResolve?.();
+      this._authFlowResolve = null;
+    }
+  }
+  /**
+   * Disconnect from the server
+   */
+  async disconnect() {
+    try {
+      if (this.transport) {
+        try {
+          await this.transport.terminateSession();
+        } catch {
+        }
+        await this.transport.close();
+      }
+    } finally {
+      this.transport = null;
+      this.client = null;
+      this._isConnected = false;
+    }
+  }
+  /**
+   * Clear stored tokens and require re-authentication
+   */
+  async clearAuth() {
+    await this.oauthProvider.clearAll();
+    await this.disconnect();
+  }
+  /**
+   * Check if this URL is an OAuth callback
+   *
+   * Useful for web apps to detect if the current URL is a callback.
+   *
+   * @param url The URL to check
+   */
+  isCallback(url) {
+    const urlObj = typeof url === "string" ? new URL(url) : url;
+    const redirectUri = new URL(this.config.redirectUri);
+    return urlObj.pathname === redirectUri.pathname && (urlObj.searchParams.has("code") || urlObj.searchParams.has("error"));
+  }
+  /**
+   * Ensure we're connected, handling auth if needed
+   */
+  async ensureConnected() {
+    if (this._isConnected && this.client) {
+      return;
+    }
+    if (this._pendingConnect) {
+      await this._pendingConnect;
+      return;
+    }
+    this._pendingConnect = this.doConnect();
+    try {
+      await this._pendingConnect;
+    } finally {
+      this._pendingConnect = null;
+    }
+  }
+  /**
+   * Internal connection logic
+   */
+  async doConnect(authRetryCount = 0) {
+    if (!this.transport) {
+      this.transport = new StreamableHTTPClientTransport(
+        new URL(this.mcpEndpointUrl),
+        {
+          authProvider: this.oauthProvider
+        }
+      );
+    }
+    const capabilities = {
+      tools: {}
+    };
+    if (this.config.onElicitationUrl) {
+      capabilities.elicitation = { url: {} };
+    }
+    this.client = new Client(
+      {
+        name: this.config.clientName ?? "kontext-sdk",
+        version: this.config.clientVersion ?? "0.0.1"
+      },
+      { capabilities }
+    );
+    if (this.config.onElicitationUrl) {
+      const onElicitationUrl = this.config.onElicitationUrl;
+      this.client.setRequestHandler(ElicitRequestSchema, async (request) => {
+        const params = request.params;
+        if (params.mode === "url" && "url" in params) {
+          await onElicitationUrl({
+            url: params.url,
+            message: params.message ?? "Action required",
+            elicitationId: params.elicitationId ?? "",
+            integrationId: params.integrationId,
+            integrationName: params.integrationName
+          });
+        }
+        return { action: "accept" };
+      });
+      this.client.setNotificationHandler(
+        ElicitationCompleteNotificationSchema,
+        () => {
+        }
+      );
+    }
+    try {
+      await this.client.connect(this.transport);
+      this._isConnected = true;
+    } catch (error) {
+      if (error instanceof Error && isUnauthorizedError(error)) {
+        if (this._pendingAuthFlow) {
+          await this._pendingAuthFlow;
+          this._pendingAuthFlow = null;
+          this.transport = null;
+          this.client = null;
+          if (authRetryCount >= 1) {
+            throw new AuthorizationRequiredError(
+              "Authorization completed, but the MCP server still rejected the token. Verify OAuth resource audience and token issuer configuration.",
+              { cause: error }
+            );
+          }
+          return this.doConnect(authRetryCount + 1);
+        }
+        this.transport = null;
+        this.client = null;
+        throw new AuthorizationRequiredError(
+          "Authorization required. Complete the OAuth flow and retry."
+        );
+      }
+      this.transport = null;
+      this.client = null;
+      if (error instanceof KontextError) throw error;
+      throw new KontextError(
+        `Failed to connect to MCP server at ${this.mcpEndpointUrl}. ${error instanceof Error ? error.message : String(error)}`,
+        "kontext_mcp_connection_failed",
+        { cause: error }
+      );
+    }
+  }
+};
+
+// src/client/tool-utils.ts
+function parseIntegrationStatus(tools, errors, elicitations) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const t of tools) {
+    const sid = t.server?.id;
+    if (sid && !seen.has(sid)) {
+      seen.add(sid);
+      result.push({
+        id: sid,
+        name: t.server?.name ?? sid,
+        connected: true
+      });
+    }
+  }
+  for (const e of errors) {
+    if (!seen.has(e.serverId)) {
+      seen.add(e.serverId);
+      const elicitation = elicitations?.find(
+        (el) => el.integrationId === e.serverId
+      );
+      result.push({
+        id: e.serverId,
+        name: e.serverName ?? e.serverId,
+        connected: false,
+        connectUrl: elicitation?.url
+      });
+    }
+  }
+  return result;
+}
+
+// src/client/orchestrator/internal/backends.ts
+function gatewayBackendId() {
+  return "gateway";
+}
+function internalBackendId(integrationId) {
+  return `internal:${integrationId}`;
+}
+function isInternalIntegration(integration) {
+  return integration.category === "internal_mcp_credentials";
+}
+function sortInternalIntegrations(integrations) {
+  return integrations.filter(isInternalIntegration).sort((a, b) => a.id.localeCompare(b.id));
+}
+function createGatewayBackend(client) {
+  return {
+    backendId: gatewayBackendId(),
+    source: "gateway",
+    client
+  };
+}
+function createInternalBackend(input) {
+  return {
+    backendId: internalBackendId(input.integration.id),
+    source: "internal",
+    client: input.client,
+    integrationId: input.integration.id,
+    integrationName: input.integration.name
+  };
+}
+
+// src/client/orchestrator/internal/routes.ts
+function emptyRouteInventorySnapshot() {
+  return {
+    version: 0,
+    tools: [],
+    routes: /* @__PURE__ */ new Map(),
+    conflicts: []
+  };
+}
+function buildRouteInventory(version, candidates, options) {
+  const tools = [];
+  const routes = /* @__PURE__ */ new Map();
+  const conflicts = [];
+  for (const candidate of candidates) {
+    const toolId = candidate.route.toolId;
+    if (!routes.has(toolId)) {
+      routes.set(toolId, candidate.route);
+      tools.push(candidate.tool);
+      continue;
+    }
+    const existing = routes.get(toolId);
+    const decision = options?.onConflict?.(existing, candidate.route) ?? "keep_existing";
+    let kept = existing;
+    let dropped = candidate.route;
+    if (decision === "replace_existing") {
+      const existingIdx = tools.findIndex((tool) => tool.id === toolId);
+      if (existingIdx >= 0) {
+        tools.splice(existingIdx, 1, candidate.tool);
+      } else {
+        tools.push(candidate.tool);
+      }
+      routes.set(toolId, candidate.route);
+      kept = candidate.route;
+      dropped = existing;
+    }
+    conflicts.push({
+      toolId,
+      kept,
+      dropped
+    });
+  }
+  return {
+    version,
+    tools,
+    routes,
+    conflicts
+  };
+}
+
+// src/client/orchestrator/internal/inventory.ts
+var RouteInventoryStore = class {
+  versionCounter = 0;
+  resetGeneration = 0;
+  buildRunCounter = 0;
+  latestCommittedBuildRun = 0;
+  snapshotState = emptyRouteInventorySnapshot();
+  pendingBuilds = /* @__PURE__ */ new Map();
+  get version() {
+    return this.snapshotState.version;
+  }
+  get snapshot() {
+    return this.snapshotState;
+  }
+  routeFor(toolId) {
+    return this.snapshotState.routes.get(toolId);
+  }
+  async build(buildCandidates, options) {
+    const key = options?.key ?? "__default__";
+    const existingBuild = this.pendingBuilds.get(key);
+    if (existingBuild) {
+      return await existingBuild;
+    }
+    const buildGeneration = this.resetGeneration;
+    const buildRun = ++this.buildRunCounter;
+    const pendingPromise = (async () => {
+      const candidates = await buildCandidates();
+      if (this.resetGeneration !== buildGeneration) {
+        return this.snapshotState;
+      }
+      if (buildRun >= this.latestCommittedBuildRun) {
+        this.latestCommittedBuildRun = buildRun;
+        this.versionCounter += 1;
+        const snapshot = buildRouteInventory(this.versionCounter, candidates, {
+          onConflict: options?.onConflict
+        });
+        this.snapshotState = snapshot;
+        return snapshot;
+      }
+      return buildRouteInventory(this.snapshotState.version, candidates, {
+        onConflict: options?.onConflict
+      });
+    })();
+    this.pendingBuilds.set(key, pendingPromise);
+    try {
+      return await pendingPromise;
+    } finally {
+      if (this.pendingBuilds.get(key) === pendingPromise) {
+        this.pendingBuilds.delete(key);
+      }
+    }
+  }
+  reset() {
+    this.resetGeneration += 1;
+    this.versionCounter = 0;
+    this.latestCommittedBuildRun = this.buildRunCounter;
+    this.snapshotState = emptyRouteInventorySnapshot();
+    this.pendingBuilds.clear();
+  }
+};
+
+// src/client/orchestrator/internal/policy.ts
+var defaultRoutingPolicy = {
+  onRouteConflict() {
+    return "keep_existing";
+  }
+};
+function toRouteConflictError(input) {
+  return new KontextError(
+    `Route conflict for tool "${input.toolId}". Keeping backend "${input.kept.backendId}" and dropping "${input.dropped.backendId}".`,
+    "kontext_tool_route_conflict",
+    {
+      meta: {
+        toolId: input.toolId,
+        keptBackendId: input.kept.backendId,
+        keptSource: input.kept.source,
+        keptIntegrationId: input.kept.integrationId,
+        droppedBackendId: input.dropped.backendId,
+        droppedSource: input.dropped.source,
+        droppedIntegrationId: input.dropped.integrationId
+      }
+    }
+  );
+}
+
+// src/client/orchestrator/internal/state.ts
+function createOrchestratorStateController(input) {
+  let state = input.initialState ?? "idle";
+  const listeners = /* @__PURE__ */ new Map();
+  function setState(next) {
+    if (state === next) return;
+    state = next;
+    try {
+      input.onStateChange?.(next);
+    } catch {
+    }
+    const handlers = listeners.get("stateChange");
+    if (!handlers) return;
+    for (const handler of handlers) {
+      try {
+        handler(next);
+      } catch {
+      }
+    }
+  }
+  function emitError(error) {
+    const handlers = listeners.get("error");
+    if (!handlers) return;
+    for (const handler of handlers) {
+      try {
+        handler(error);
+      } catch {
+      }
+    }
+  }
+  function on(event, handler) {
+    if (!listeners.has(event)) {
+      listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    listeners.get(event).add(handler);
+    return () => {
+      listeners.get(event)?.delete(handler);
+    };
+  }
+  return {
+    get state() {
+      return state;
+    },
+    setState,
+    emitError,
+    on
+  };
+}
+
+// src/client/orchestrator/token-manager.ts
+function hasFreshStoredToken(tokens, skewMs = 3e4) {
+  if (!tokens?.access_token) return false;
+  const expiresIn = typeof tokens.expires_in === "number" ? tokens.expires_in : Number(tokens.expires_in);
+  const issuedAt = typeof tokens.issued_at === "number" ? tokens.issued_at : Number(tokens.issued_at);
+  if (!Number.isFinite(expiresIn) || !Number.isFinite(issuedAt)) {
+    return false;
+  }
+  const expiresAt = issuedAt + expiresIn * 1e3;
+  return Date.now() + skewMs < expiresAt;
+}
+function createTokenManager(input) {
+  const pendingInternalTokenExchange = /* @__PURE__ */ new Map();
+  function tokenStorageKey(sessionKey) {
+    return createStorageKey(input.clientId, sessionKey, StorageKeys.TOKENS);
+  }
+  async function readGatewayTokens() {
+    const identityTokens = await input.storage.getJson(
+      createStorageKey(
+        input.clientId,
+        input.gatewaySessionKey,
+        StorageKeys.IDENTITY_TOKENS
+      )
+    );
+    const gatewayTokens = await input.storage.getJson(tokenStorageKey(input.gatewaySessionKey));
+    return {
+      subjectToken: identityTokens?.access_token ?? gatewayTokens?.access_token ?? null
+    };
+  }
+  async function ensureInternalResourceToken(integration, options) {
+    const internalSessionKey = `${input.baseSessionKey}:internal:${integration.id}`;
+    if (!options?.forceExchange) {
+      const existingToken = await input.storage.getJson(
+        tokenStorageKey(internalSessionKey)
+      );
+      if (hasFreshStoredToken(existingToken)) {
+        return;
+      }
+    }
+    const pending = pendingInternalTokenExchange.get(integration.id);
+    if (pending) {
+      return await pending;
+    }
+    const exchangePromise = (async () => {
+      const { subjectToken: gatewaySubjectToken } = await readGatewayTokens();
+      if (!gatewaySubjectToken) {
+        return;
+      }
+      const body = new URLSearchParams({
+        grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
+        subject_token_type: "urn:ietf:params:oauth:token-type:access_token",
+        subject_token: gatewaySubjectToken,
+        resource: integration.url,
+        client_id: input.clientId
+      });
+      const response = await fetch(`${input.serverUrl}/oauth2/token`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded"
+        },
+        body: body.toString()
+      });
+      if (response.status === 401) {
+        throw new AuthorizationRequiredError(
+          "Access token expired or invalid. Re-authenticate and retry."
+        );
+      }
+      if (!response.ok) {
+        throw new KontextError(
+          `Failed to exchange gateway token for internal resource "${integration.id}": HTTP ${response.status}`,
+          "kontext_token_exchange_failed",
+          {
+            statusCode: response.status,
+            meta: {
+              integrationId: integration.id,
+              resource: integration.url
+            }
+          }
+        );
+      }
+      const exchanged = await response.json();
+      if (!exchanged.access_token || !exchanged.token_type) {
+        throw new KontextError(
+          `Token exchange returned an invalid payload for integration "${integration.id}".`,
+          "kontext_token_exchange_failed",
+          {
+            meta: {
+              integrationId: integration.id,
+              resource: integration.url
+            }
+          }
+        );
+      }
+      await input.storage.setJson(tokenStorageKey(internalSessionKey), {
+        ...exchanged,
+        issued_at: Date.now()
+      });
+    })();
+    pendingInternalTokenExchange.set(integration.id, exchangePromise);
+    try {
+      await exchangePromise;
+    } finally {
+      pendingInternalTokenExchange.delete(integration.id);
+    }
+  }
+  return {
+    tokenStorageKey,
+    ensureInternalResourceToken
+  };
+}
+
+// src/client/orchestrator/internal-client-registry.ts
+function createInternalClientRegistry(input) {
+  const internalClients = /* @__PURE__ */ new Map();
+  async function remove(integrationId) {
+    const existing = internalClients.get(integrationId);
+    if (!existing) return;
+    existing.unsubscribeState();
+    existing.unsubscribeError();
+    internalClients.delete(integrationId);
+    input.backends.delete(existing.backendId);
+    try {
+      await existing.client.disconnect();
+    } catch {
+    }
+  }
+  async function sync(discovered) {
+    const sortedInternal = sortInternalIntegrations(discovered);
+    const desiredById = new Map(sortedInternal.map((item) => [item.id, item]));
+    for (const [integrationId, existing] of internalClients) {
+      const next = desiredById.get(integrationId);
+      if (!next) {
+        await remove(integrationId);
+        continue;
+      }
+      if (existing.integration.url !== next.url) {
+        await remove(integrationId);
+      }
+    }
+    for (const integration of sortedInternal) {
+      const existing = internalClients.get(integration.id);
+      if (existing) {
+        existing.integration = integration;
+        const backend = input.backends.get(existing.backendId);
+        if (backend) {
+          backend.integrationName = integration.name;
+        }
+        continue;
+      }
+      const created = input.createClient(integration);
+      input.backends.set(created.backend.backendId, created.backend);
+      internalClients.set(integration.id, {
+        integration,
+        backendId: created.backend.backendId,
+        client: created.client,
+        unsubscribeState: created.unsubscribeState,
+        unsubscribeError: created.unsubscribeError
+      });
+    }
+  }
+  function missingResolved(resolvedIntegrations) {
+    const missing = [];
+    for (const integrationId of internalClients.keys()) {
+      if (!resolvedIntegrations.has(integrationId)) {
+        missing.push(integrationId);
+      }
+    }
+    return missing;
+  }
+  async function dispose(mode) {
+    const entries = [...internalClients.values()];
+    internalClients.clear();
+    for (const backend of [...input.backends.values()]) {
+      if (backend.source === "internal") {
+        input.backends.delete(backend.backendId);
+      }
+    }
+    await Promise.all(
+      entries.map(async (entry) => {
+        entry.unsubscribeState();
+        entry.unsubscribeError();
+        try {
+          if (mode === "signOut") {
+            await entry.client.auth.signOut();
+          } else {
+            await entry.client.disconnect();
+          }
+        } catch {
+        }
+      })
+    );
+  }
+  return {
+    get size() {
+      return internalClients.size;
+    },
+    entries() {
+      return internalClients.entries();
+    },
+    values() {
+      return internalClients.values();
+    },
+    keys() {
+      return internalClients.keys();
+    },
+    get(integrationId) {
+      return internalClients.get(integrationId);
+    },
+    sync,
+    missingResolved,
+    dispose
+  };
+}
+
+// src/client/orchestrator/index.ts
+function isTransientError(err) {
+  if (err instanceof Error && isNetworkError(err)) {
+    return true;
+  }
+  if (isKontextError(err)) {
+    if (err.code === "kontext_network_error") return true;
+    if (err.statusCode === 429) return true;
+    if (typeof err.statusCode === "number" && err.statusCode >= 500) {
+      return true;
+    }
+    return false;
+  }
+  if (typeof err === "object" && err !== null) {
+    const errObj = err;
+    const maybeStatus = errObj.statusCode ?? errObj.status;
+    const status = typeof maybeStatus === "number" ? maybeStatus : void 0;
+    if (status === 429 || typeof status === "number" && status >= 500) {
+      return true;
+    }
+  }
+  return false;
+}
+async function withTransientRetry(operation, maxRetries = 1) {
+  const retryDelayMs = 250;
+  for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
+    try {
+      return await operation();
+    } catch (err) {
+      if (attempt >= maxRetries || !isTransientError(err)) {
+        throw err;
+      }
+      await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+    }
+  }
+  throw new Error("Transient retry loop exhausted unexpectedly.");
+}
+function toKontextError(err, context) {
+  const contextMeta = context ? { ...context } : void 0;
+  const mergeMeta = (base) => contextMeta ? { ...base ?? {}, ...contextMeta } : base ?? {};
+  if (isKontextError(err)) {
+    if (!contextMeta) {
+      return err;
+    }
+    const cloned = Object.create(Object.getPrototypeOf(err));
+    Object.defineProperties(cloned, Object.getOwnPropertyDescriptors(err));
+    Object.defineProperty(cloned, "meta", {
+      value: mergeMeta(err.meta),
+      enumerable: true,
+      writable: true,
+      configurable: true
+    });
+    return cloned;
+  }
+  if (err instanceof Error) {
+    if (isUnauthorizedError(err)) {
+      return new AuthorizationRequiredError(err.message, {
+        meta: mergeMeta(),
+        cause: err
+      });
+    }
+    return new KontextError(err.message, "kontext_unknown_error", {
+      meta: mergeMeta(),
+      cause: err
+    });
+  }
+  return new KontextError(String(err), "kontext_unknown_error", {
+    meta: mergeMeta()
+  });
+}
+function isAuthorizationRequired(err) {
+  if (err instanceof AuthorizationRequiredError) return true;
+  if (isKontextError(err)) {
+    return err.code === "kontext_authorization_required";
+  }
+  if (typeof err === "object" && err !== null) {
+    return err.code === "kontext_authorization_required";
+  }
+  return false;
+}
+function isTokenExchangeFailure(err) {
+  if (isKontextError(err)) {
+    return err.code === "kontext_token_exchange_failed";
+  }
+  if (typeof err === "object" && err !== null) {
+    return err.code === "kontext_token_exchange_failed";
+  }
+  return false;
+}
+function isAuthRecoveryRequired(err) {
+  return isAuthorizationRequired(err) || isTokenExchangeFailure(err);
+}
+function createKontextOrchestrator(config) {
+  if (!config.clientId) {
+    throw new ConfigError(
+      "clientId is required. Pass it in KontextOrchestratorConfig.",
+      "kontext_config_missing_client_id"
+    );
+  }
+  if (!config.redirectUri) {
+    throw new ConfigError(
+      "redirectUri is required. Set it to the URL where OAuth should redirect after authorization.",
+      "kontext_config_missing_redirect_uri"
+    );
+  }
+  if (!config.onAuthRequired) {
+    throw new ConfigError(
+      "onAuthRequired callback is required. Provide a function that opens the OAuth URL.",
+      "kontext_config_missing_auth_handler"
+    );
+  }
+  const baseSessionKey = config.sessionKey ?? "default";
+  const serverUrl = normalizeKontextServerUrl(
+    config.serverUrl ?? "https://api.kontext.dev"
+  );
+  const sharedStorage = config.storage ?? new MemoryStorage();
+  const gatewaySessionKey = `${baseSessionKey}:gateway`;
+  const authSourceQueue = [];
+  const stateController = createOrchestratorStateController({
+    initialState: "idle",
+    onStateChange: config.onStateChange
+  });
+  const routeInventory = new RouteInventoryStore();
+  const routingPolicy = defaultRoutingPolicy;
+  const runtimeIntegrations = /* @__PURE__ */ new Map();
+  const backends = /* @__PURE__ */ new Map();
+  const managedInternalOps = /* @__PURE__ */ new Map();
+  const resolvedInternalListings = /* @__PURE__ */ new Set();
+  const tokenManager = createTokenManager({
+    clientId: config.clientId,
+    baseSessionKey,
+    gatewaySessionKey,
+    serverUrl,
+    storage: sharedStorage
+  });
+  let pendingIntegrationRefresh = null;
+  const gatewayClient = createSingleEndpointKontextClient({
+    clientId: config.clientId,
+    redirectUri: config.redirectUri,
+    serverUrl: config.serverUrl,
+    storage: sharedStorage,
+    sessionKey: gatewaySessionKey,
+    onAuthRequired: async (url) => {
+      authSourceQueue.push("gateway");
+      return await config.onAuthRequired(url);
+    },
+    onIntegrationRequired: config.onIntegrationRequired
+  });
+  const gatewayBackend = createGatewayBackend(gatewayClient);
+  backends.set(gatewayBackendId(), gatewayBackend);
+  gatewayClient.on("stateChange", (state) => {
+    if (state === "needs_auth") {
+      stateController.setState("needs_auth");
+    }
+  });
+  gatewayClient.on("error", (error) => {
+    const translated = toKontextError(error, {
+      backendId: gatewayBackendId(),
+      source: "gateway",
+      operation: "client_error_event"
+    });
+    stateController.emitError(translated);
+    if (isAuthRecoveryRequired(translated)) {
+      stateController.setState("needs_auth");
+    }
+  });
+  const ensureInternalResourceToken = tokenManager.ensureInternalResourceToken;
+  function isInternalOpManaged(integrationId) {
+    return (managedInternalOps.get(integrationId) ?? 0) > 0;
+  }
+  async function runManagedInternalOp(integrationId, operation) {
+    managedInternalOps.set(
+      integrationId,
+      (managedInternalOps.get(integrationId) ?? 0) + 1
+    );
+    try {
+      return await operation();
+    } finally {
+      const next = (managedInternalOps.get(integrationId) ?? 1) - 1;
+      if (next <= 0) {
+        managedInternalOps.delete(integrationId);
+      } else {
+        managedInternalOps.set(integrationId, next);
+      }
+    }
+  }
+  function createInternalClient(integration) {
+    const client = createSingleEndpointKontextClient({
+      clientId: config.clientId,
+      redirectUri: config.redirectUri,
+      url: integration.url,
+      serverUrl: config.serverUrl,
+      storage: sharedStorage,
+      sessionKey: `${baseSessionKey}:internal:${integration.id}`,
+      onAuthRequired: async (url) => {
+        authSourceQueue.push(integration.id);
+        return await config.onAuthRequired(url);
+      },
+      onIntegrationRequired: config.onIntegrationRequired
+    });
+    const unsubscribeState = client.on("stateChange", (state) => {
+      if (state === "needs_auth") {
+        stateController.setState("needs_auth");
+      }
+    });
+    const unsubscribeError = client.on("error", (error) => {
+      const translated = toKontextError(error, {
+        backendId: internalBackendId(integration.id),
+        source: "internal",
+        integrationId: integration.id,
+        operation: "client_error_event"
+      });
+      if (isInternalOpManaged(integration.id) && isAuthorizationRequired(translated)) {
+        return;
+      }
+      if (isAuthRecoveryRequired(translated)) {
+        stateController.setState("needs_auth");
+        return;
+      }
+      stateController.emitError(translated);
+    });
+    const backend = createInternalBackend({ integration, client });
+    return { backend, client, unsubscribeState, unsubscribeError };
+  }
+  const internalClientRegistry = createInternalClientRegistry({
+    backends,
+    createClient: createInternalClient
+  });
+  async function refreshIntegrationInventory(force = false) {
+    if (pendingIntegrationRefresh) {
+      if (!force) {
+        return await pendingIntegrationRefresh;
+      }
+      await pendingIntegrationRefresh;
+    }
+    const refreshPromise = (async () => {
+      const items = await withTransientRetry(
+        async () => await gatewayClient.mcp.listRuntimeIntegrations()
+      );
+      await applyRuntimeIntegrations(items);
+      return items;
+    })();
+    pendingIntegrationRefresh = refreshPromise;
+    try {
+      return await refreshPromise;
+    } finally {
+      if (pendingIntegrationRefresh === refreshPromise) {
+        pendingIntegrationRefresh = null;
+      }
+    }
+  }
+  async function applyRuntimeIntegrations(integrations) {
+    runtimeIntegrations.clear();
+    for (const item of integrations) {
+      runtimeIntegrations.set(item.id, item);
+    }
+    await internalClientRegistry.sync(integrations);
+  }
+  async function buildInventoryCandidates(options) {
+    const candidates = [];
+    resolvedInternalListings.clear();
+    const pendingInternalAuthRetries = /* @__PURE__ */ new Set();
+    const gatewayTools = await gatewayClient.tools.list(options);
+    for (const tool of gatewayTools) {
+      candidates.push({
+        tool,
+        route: {
+          toolId: tool.id,
+          backendId: gatewayBackendId(),
+          source: "gateway",
+          backendToolId: tool.id
+        }
+      });
+    }
+    if (options?.runtimeIntegrations) {
+      await applyRuntimeIntegrations(options.runtimeIntegrations);
+    } else {
+      await refreshIntegrationInventory();
+    }
+    const sortedInternalEntries = [...internalClientRegistry.values()].sort(
+      (a, b) => a.integration.id.localeCompare(b.integration.id)
+    );
+    const addInternalToolsForEntry = async (entry) => {
+      const internalTools = await withTransientRetry(
+        async () => await runManagedInternalOp(
+          entry.integration.id,
+          () => entry.client.tools.list()
+        )
+      );
+      resolvedInternalListings.add(entry.integration.id);
+      for (const tool of internalTools) {
+        const backendToolId = tool.id || tool.name;
+        const unifiedId = `${entry.integration.id}:${tool.name}`;
+        candidates.push({
+          tool: {
+            id: unifiedId,
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            server: {
+              id: entry.integration.id,
+              name: entry.integration.name
+            }
+          },
+          route: {
+            toolId: unifiedId,
+            backendId: entry.backendId,
+            source: "internal",
+            backendToolId,
+            integrationId: entry.integration.id
+          }
+        });
+      }
+    };
+    for (const entry of sortedInternalEntries) {
+      try {
+        await ensureInternalResourceToken(entry.integration);
+        await addInternalToolsForEntry(entry);
+      } catch (err) {
+        const translated = toKontextError(err, {
+          backendId: entry.backendId,
+          source: "internal",
+          integrationId: entry.integration.id,
+          operation: "tools.list"
+        });
+        if (isAuthorizationRequired(translated)) {
+          pendingInternalAuthRetries.add(entry.integration.id);
+          continue;
+        }
+        if (isTokenExchangeFailure(translated)) {
+          stateController.setState("needs_auth");
+        }
+        stateController.emitError(translated);
+      }
+    }
+    if (pendingInternalAuthRetries.size > 0) {
+      let hasUnresolvedAuth = false;
+      for (const integrationId of pendingInternalAuthRetries) {
+        const entry = internalClientRegistry.get(integrationId);
+        if (!entry) continue;
+        try {
+          await ensureInternalResourceToken(entry.integration, {
+            forceExchange: true
+          });
+          await runManagedInternalOp(integrationId, async () => {
+            await entry.client.disconnect();
+            await entry.client.connect();
+          });
+          await addInternalToolsForEntry(entry);
+        } catch (err) {
+          const translated = toKontextError(err);
+          if (isAuthRecoveryRequired(translated)) {
+            hasUnresolvedAuth = true;
+            if (isTokenExchangeFailure(translated)) {
+              stateController.emitError(translated);
+            }
+            continue;
+          }
+          stateController.emitError(translated);
+        }
+      }
+      if (hasUnresolvedAuth) {
+        stateController.setState("needs_auth");
+      } else if (stateController.state === "needs_auth" && gatewayClient.state === "ready") {
+        stateController.setState("ready");
+      }
+    }
+    return candidates;
+  }
+  async function buildToolInventory(options) {
+    const inventoryKey = JSON.stringify({
+      limit: options?.limit ?? null,
+      runtimeIntegrations: options?.runtimeIntegrations?.map((integration) => integration.id).sort() ?? null
+    });
+    const snapshot = await routeInventory.build(
+      async () => await buildInventoryCandidates(options),
+      {
+        key: inventoryKey,
+        onConflict: (existing, incoming) => routingPolicy.onRouteConflict({
+          toolId: existing.toolId,
+          existing,
+          incoming
+        })
+      }
+    );
+    return {
+      tools: snapshot.tools,
+      conflicts: snapshot.conflicts
+    };
+  }
+  function emitRouteConflicts(conflicts) {
+    for (const conflict of conflicts) {
+      stateController.emitError(
+        toRouteConflictError({
+          toolId: conflict.toolId,
+          kept: conflict.kept,
+          dropped: conflict.dropped
+        })
+      );
+    }
+  }
+  function getInternalIntegrationsMissingTools() {
+    return internalClientRegistry.missingResolved(resolvedInternalListings);
+  }
+  async function disposeInternalClients(mode) {
+    await internalClientRegistry.dispose(mode);
+  }
+  async function ensureConnected() {
+    if (stateController.state === "ready") return;
+    if (stateController.state === "needs_auth" && gatewayClient.state === "ready") {
+      return;
+    }
+    stateController.setState("connecting");
+    try {
+      await gatewayClient.connect();
+      await refreshIntegrationInventory(true);
+      stateController.setState("ready");
+    } catch (err) {
+      const translated = toKontextError(err, {
+        backendId: gatewayBackendId(),
+        source: "gateway",
+        operation: "connect"
+      });
+      if (isAuthRecoveryRequired(translated)) {
+        stateController.setState("needs_auth");
+      } else {
+        stateController.setState("failed");
+      }
+      stateController.emitError(translated);
+      throw translated;
+    }
+  }
+  async function routeForExecution(toolId) {
+    let route = routeInventory.routeFor(toolId);
+    if (route) return route;
+    const inventory = await buildToolInventory();
+    emitRouteConflicts(inventory.conflicts);
+    route = routeInventory.routeFor(toolId);
+    if (route) return route;
+    throw new KontextError(
+      `Unknown tool "${toolId}". Call tools.list() to refresh available tools.`,
+      "kontext_tool_not_found",
+      { meta: { toolId } }
+    );
+  }
+  const orchestrator = {
+    get state() {
+      return stateController.state;
+    },
+    async connect() {
+      await ensureConnected();
+    },
+    async disconnect() {
+      await disposeInternalClients("disconnect");
+      runtimeIntegrations.clear();
+      routeInventory.reset();
+      authSourceQueue.length = 0;
+      await gatewayClient.disconnect();
+      stateController.setState("idle");
+    },
+    async getConnectPageUrl() {
+      await ensureConnected();
+      return await gatewayClient.getConnectPageUrl();
+    },
+    auth: {
+      async signIn() {
+        if (stateController.state === "needs_auth" && gatewayClient.state === "ready") {
+          await refreshIntegrationInventory(true);
+          let unresolvedInternalAuth = false;
+          for (const [
+            integrationId,
+            entry
+          ] of internalClientRegistry.entries()) {
+            try {
+              await runManagedInternalOp(
+                integrationId,
+                () => entry.client.auth.signIn()
+              );
+            } catch (err) {
+              const translated = toKontextError(err);
+              if (isAuthorizationRequired(translated)) {
+                unresolvedInternalAuth = true;
+                continue;
+              }
+              stateController.emitError(translated);
+            }
+          }
+          const inventory = await buildToolInventory();
+          emitRouteConflicts(inventory.conflicts);
+          const missingInternal = getInternalIntegrationsMissingTools();
+          if (!unresolvedInternalAuth && missingInternal.length === 0) {
+            stateController.setState("ready");
+          }
+          return;
+        }
+        await ensureConnected();
+      },
+      async signOut() {
+        await disposeInternalClients("signOut");
+        runtimeIntegrations.clear();
+        routeInventory.reset();
+        authSourceQueue.length = 0;
+        await gatewayClient.auth.signOut();
+        stateController.setState("idle");
+      },
+      async handleCallback(url) {
+        if (internalClientRegistry.size === 0) {
+          try {
+            await refreshIntegrationInventory(true);
+          } catch (err) {
+            stateController.emitError(
+              toKontextError(err, {
+                backendId: gatewayBackendId(),
+                source: "gateway",
+                operation: "auth.handleCallback.preload"
+              })
+            );
+          }
+        }
+        const ordered = [];
+        for (const sourceId of authSourceQueue) {
+          if (sourceId === "gateway") {
+            ordered.push({ client: gatewayClient, sourceId });
+            continue;
+          }
+          const active = internalClientRegistry.get(sourceId);
+          if (active) {
+            ordered.push({ client: active.client, sourceId });
+          }
+        }
+        if (gatewayClient.auth.isCallback(url)) {
+          ordered.push({ client: gatewayClient });
+        }
+        for (const entry of internalClientRegistry.values()) {
+          if (entry.client.auth.isCallback(url)) {
+            ordered.push({ client: entry.client });
+          }
+        }
+        ordered.push({ client: gatewayClient });
+        ordered.push(
+          ...[...internalClientRegistry.values()].sort((a, b) => a.integration.id.localeCompare(b.integration.id)).map((entry) => ({ client: entry.client }))
+        );
+        const unique = [];
+        const seen = /* @__PURE__ */ new Set();
+        for (const entry of ordered) {
+          if (seen.has(entry.client)) continue;
+          seen.add(entry.client);
+          unique.push(entry);
+        }
+        let handledBy;
+        let lastError = void 0;
+        for (const entry of unique) {
+          try {
+            await entry.client.auth.handleCallback(url);
+            handledBy = entry;
+            break;
+          } catch (err) {
+            lastError = err;
+          }
+        }
+        if (handledBy) {
+          for (let idx = authSourceQueue.length - 1; idx >= 0; idx -= 1) {
+            const sourceId = authSourceQueue[idx];
+            const sourceClient = sourceId === "gateway" ? gatewayClient : internalClientRegistry.get(sourceId)?.client;
+            if (sourceClient === handledBy.client) {
+              authSourceQueue.splice(idx, 1);
+            }
+          }
+        }
+        if (!handledBy && lastError) {
+          throw toKontextError(lastError, {
+            backendId: gatewayBackendId(),
+            source: "gateway",
+            operation: "auth.handleCallback"
+          });
+        }
+        try {
+          await ensureConnected();
+        } catch (err) {
+          stateController.emitError(
+            toKontextError(err, {
+              backendId: gatewayBackendId(),
+              source: "gateway",
+              operation: "post_callback_connect"
+            })
+          );
+        }
+      },
+      isCallback(url) {
+        if (gatewayClient.auth.isCallback(url)) return true;
+        for (const entry of internalClientRegistry.values()) {
+          if (entry.client.auth.isCallback(url)) return true;
+        }
+        return false;
+      },
+      get isAuthenticated() {
+        return stateController.state === "ready" || gatewayClient.auth.isAuthenticated;
+      }
+    },
+    integrations: {
+      async list() {
+        await ensureConnected();
+        const discovered = await refreshIntegrationInventory(true);
+        let gatewayStatuses = [];
+        try {
+          gatewayStatuses = await gatewayClient.integrations.list();
+        } catch (err) {
+          stateController.emitError(
+            toKontextError(err, {
+              backendId: gatewayBackendId(),
+              source: "gateway",
+              operation: "integrations.list"
+            })
+          );
+        }
+        const gatewayById = new Map(gatewayStatuses.map((i) => [i.id, i]));
+        const needsInternalConnectLink = discovered.some(
+          (i) => i.category === "internal_mcp_credentials" && !i.connection?.connected
+        );
+        let sharedConnectUrl;
+        if (needsInternalConnectLink) {
+          try {
+            sharedConnectUrl = (await gatewayClient.getConnectPageUrl()).connectUrl;
+          } catch {
+            sharedConnectUrl = void 0;
+          }
+        }
+        return discovered.map((integration) => {
+          const gatewayStatus = gatewayById.get(integration.id);
+          const connected = gatewayStatus?.connected ?? integration.connection?.connected ?? false;
+          const connectUrl = gatewayStatus?.connectUrl ?? (!connected && integration.category === "internal_mcp_credentials" ? sharedConnectUrl : void 0);
+          const reason = gatewayStatus?.reason ?? (!connected && integration.category === "internal_mcp_credentials" ? "credentials_required" : void 0);
+          return {
+            id: integration.id,
+            name: integration.name,
+            connected,
+            connectUrl,
+            reason
+          };
+        });
+      }
+    },
+    tools: {
+      async list(options) {
+        await ensureConnected();
+        let inventory = await buildToolInventory(options);
+        const missingInternal = getInternalIntegrationsMissingTools();
+        if (missingInternal.length > 0) {
+          const refreshed = await refreshIntegrationInventory(true);
+          inventory = await buildToolInventory({
+            ...options,
+            runtimeIntegrations: refreshed
+          });
+        }
+        emitRouteConflicts(inventory.conflicts);
+        const unresolvedInternal = getInternalIntegrationsMissingTools();
+        if (stateController.state === "needs_auth" && gatewayClient.state === "ready" && unresolvedInternal.length === 0) {
+          stateController.setState("ready");
+        }
+        return inventory.tools;
+      },
+      async execute(toolId, args) {
+        await ensureConnected();
+        const route = await routeForExecution(toolId);
+        try {
+          if (route.source === "gateway") {
+            return await gatewayClient.tools.execute(route.backendToolId, args);
+          }
+          const integrationId = route.integrationId;
+          if (!integrationId) {
+            throw new KontextError(
+              `Route for tool "${toolId}" is missing integration metadata.`,
+              "kontext_tool_not_found",
+              { meta: { toolId, route } }
+            );
+          }
+          let entry = internalClientRegistry.get(integrationId);
+          if (!entry) {
+            await refreshIntegrationInventory(true);
+            entry = internalClientRegistry.get(integrationId);
+          }
+          if (!entry) {
+            throw new KontextError(
+              `Internal integration "${integrationId}" is no longer attached.`,
+              "kontext_tool_not_found",
+              { meta: { integrationId } }
+            );
+          }
+          await ensureInternalResourceToken(entry.integration);
+          try {
+            const executeInternal = async () => await withTransientRetry(
+              async () => await runManagedInternalOp(
+                integrationId,
+                () => entry.client.tools.execute(route.backendToolId, args)
+              )
+            );
+            return await executeInternal();
+          } catch (innerErr) {
+            const innerTranslated = toKontextError(innerErr, {
+              backendId: route.backendId,
+              source: route.source,
+              integrationId: route.integrationId,
+              operation: "tools.execute",
+              toolId
+            });
+            throw innerTranslated;
+          }
+        } catch (err) {
+          const translated = toKontextError(err, {
+            backendId: route.backendId,
+            source: route.source,
+            integrationId: route.integrationId,
+            operation: "tools.execute",
+            toolId
+          });
+          if (isAuthRecoveryRequired(translated)) {
+            stateController.setState("needs_auth");
+          }
+          stateController.emitError(translated);
+          throw translated;
+        }
+      }
+    },
+    on(event, handler) {
+      if (event === "stateChange") {
+        return stateController.on("stateChange", handler);
+      }
+      return stateController.on("error", handler);
+    },
+    get mcp() {
+      return gatewayClient.mcp;
+    }
+  };
+  return orchestrator;
+}
+
+// src/client/index.ts
+var META_TOOL_NAMES = /* @__PURE__ */ new Set(["SEARCH_TOOLS", "EXECUTE_TOOL"]);
+function hasMetaTools(tools) {
+  let hasSearch = false;
+  let hasExecute = false;
+  for (const tool of tools) {
+    if (tool.name === "SEARCH_TOOLS") hasSearch = true;
+    if (tool.name === "EXECUTE_TOOL") hasExecute = true;
+  }
+  return hasSearch && hasExecute;
+}
+function extractJsonResourceText(result) {
+  if (!result || typeof result !== "object") return null;
+  const content = result.content;
+  if (!Array.isArray(content)) return null;
+  for (const item of content) {
+    if (item.type === "resource" && item.resource?.mimeType === "application/json" && item.resource.text) {
+      return item.resource.text;
+    }
+  }
+  return null;
+}
+function extractTextContent(result) {
+  if (!result || typeof result !== "object") return String(result ?? "");
+  const r = result;
+  if (r.content && Array.isArray(r.content)) {
+    const texts = r.content.filter((c) => c.type === "text" && c.text).map((c) => c.text);
+    if (texts.length > 0) return texts.join("\n");
+    const resourceTexts = r.content.filter((c) => c.type === "resource" && c.resource?.text).map((c) => c.resource.text);
+    if (resourceTexts.length > 0) {
+      return resourceTexts.map((text) => {
+        try {
+          return extractTextContent(JSON.parse(text));
+        } catch {
+          return text;
+        }
+      }).join("\n");
+    }
+    return JSON.stringify(r.content);
+  }
+  return JSON.stringify(result);
+}
+function translateError(err) {
+  if (isKontextError(err)) return err;
+  if (!(err instanceof Error)) {
+    return new KontextError(String(err), "kontext_unknown_error");
+  }
+  const props = err;
+  if (props.code === -32042) {
+    const elicitations = props.elicitations ?? props.data?.elicitations;
+    const elicitation = elicitations?.[0];
+    return new IntegrationConnectionRequiredError(
+      elicitation?.integrationId ?? "unknown",
+      {
+        integrationName: elicitation?.integrationName,
+        connectUrl: elicitation?.url,
+        message: elicitation?.message,
+        cause: err
+      }
+    );
+  }
+  const statusCode = props.statusCode ?? props.status;
+  if (typeof statusCode === "number" && statusCode >= 400) {
+    if (statusCode === 401) {
+      return new AuthorizationRequiredError(err.message, { cause: err });
+    }
+    return new KontextError(err.message, "kontext_server_error", {
+      statusCode,
+      cause: err
+    });
+  }
+  if (isUnauthorizedError(err)) {
+    return new AuthorizationRequiredError(err.message, { cause: err });
+  }
+  if (isNetworkError(err)) {
+    return new NetworkError(err.message, { cause: err });
+  }
+  return new KontextError(err.message, "kontext_unknown_error", {
+    cause: err
+  });
+}
+function createSingleEndpointKontextClient(config) {
+  if (!config.clientId) {
+    throw new ConfigError(
+      "clientId is required. Pass it in KontextClientConfig or set KONTEXT_CLIENT_ID.",
+      "kontext_config_missing_client_id"
+    );
+  }
+  if (!config.redirectUri) {
+    throw new ConfigError(
+      "redirectUri is required. Set it to the URL where OAuth should redirect after authorization.",
+      "kontext_config_missing_redirect_uri"
+    );
+  }
+  if (!config.onAuthRequired) {
+    throw new ConfigError(
+      "onAuthRequired callback is required. Provide a function that opens the OAuth URL.",
+      "kontext_config_missing_auth_handler"
+    );
+  }
+  let _state = "idle";
+  const _listeners = /* @__PURE__ */ new Map();
+  let _metaToolMode = null;
+  const mcp = new KontextMcp({
+    clientId: config.clientId,
+    url: config.url,
+    server: config.serverUrl,
+    redirectUri: config.redirectUri,
+    storage: config.storage,
+    sessionKey: config.sessionKey,
+    onAuthRequired: config.onAuthRequired,
+    // Route MCP elicitation to the high-level callback.
+    // KontextMcp calls this then re-throws; client.tools.execute() catches
+    // the re-thrown error and handles translation.
+    onElicitationUrl: config.onIntegrationRequired ? (entry) => {
+      config.onIntegrationRequired(entry.url, {
+        id: entry.integrationId ?? "unknown",
+        name: entry.integrationName ?? entry.message
+      });
+    } : void 0
+  });
+  function setState(newState) {
+    if (_state === newState) return;
+    _state = newState;
+    try {
+      config.onStateChange?.(newState);
+    } catch {
+    }
+    const handlers = _listeners.get("stateChange");
+    if (handlers) {
+      for (const handler of handlers) {
+        try {
+          handler(newState);
+        } catch {
+        }
+      }
+    }
+  }
+  function emitError(error) {
+    const handlers = _listeners.get("error");
+    if (handlers) {
+      for (const handler of handlers) {
+        try {
+          handler(error);
+        } catch {
+        }
+      }
+    }
+  }
+  async function fetchGatewayTools(limit = 100) {
+    const result = await mcp.callTool("SEARCH_TOOLS", { limit });
+    const jsonText = extractJsonResourceText(result);
+    if (!jsonText) {
+      throw new KontextError(
+        "SEARCH_TOOLS did not return JSON resource content. The server may not support the gateway protocol.",
+        "kontext_tool_response_empty"
+      );
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(jsonText);
+    } catch (e) {
+      throw new KontextError(
+        `SEARCH_TOOLS returned invalid JSON: ${e instanceof Error ? e.message : String(e)}`,
+        "kontext_tool_response_invalid_json"
+      );
+    }
+    if (Array.isArray(parsed)) {
+      return { tools: parsed, errors: [] };
+    }
+    if (parsed && typeof parsed === "object") {
+      const obj = parsed;
+      return {
+        tools: Array.isArray(obj.items) ? obj.items : [],
+        errors: Array.isArray(obj.errors) ? obj.errors : [],
+        elicitations: Array.isArray(obj.elicitations) ? obj.elicitations : void 0
+      };
+    }
+    throw new KontextError(
+      "SEARCH_TOOLS response was not a JSON array or object. Check the server version.",
+      "kontext_tool_response_unexpected"
+    );
+  }
+  function toKontextTool(tool) {
+    return {
+      id: tool.id,
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      server: tool.server ? { id: tool.server.id ?? "", name: tool.server.name } : void 0
+    };
+  }
+  async function ensureConnected() {
+    if (_state === "ready" && mcp.isConnected) return;
+    setState("connecting");
+    try {
+      const mcpTools = await mcp.listTools();
+      _metaToolMode = hasMetaTools(mcpTools);
+      setState("ready");
+    } catch (err) {
+      const translated = translateError(err);
+      if (translated instanceof AuthorizationRequiredError) {
+        setState("needs_auth");
+      } else {
+        setState("failed");
+      }
+      emitError(translated);
+      throw translated;
+    }
+  }
+  const client = {
+    get state() {
+      return _state;
+    },
+    async connect() {
+      await ensureConnected();
+    },
+    async disconnect() {
+      await mcp.disconnect();
+      _metaToolMode = null;
+      setState("idle");
+    },
+    async getConnectPageUrl() {
+      await ensureConnected();
+      try {
+        return await mcp.createConnectSession();
+      } catch (err) {
+        const translated = translateError(err);
+        if (translated instanceof AuthorizationRequiredError) {
+          setState("needs_auth");
+        }
+        throw translated;
+      }
+    },
+    auth: {
+      async signIn() {
+        await ensureConnected();
+      },
+      async signOut() {
+        await mcp.clearAuth();
+        _metaToolMode = null;
+        setState("idle");
+      },
+      async handleCallback(url) {
+        await mcp.handleCallback(url);
+        try {
+          await ensureConnected();
+        } catch (err) {
+          emitError(translateError(err));
+        }
+      },
+      isCallback(url) {
+        return mcp.isCallback(url);
+      },
+      get isAuthenticated() {
+        return _state === "ready" || mcp.isConnected;
+      }
+    },
+    integrations: {
+      async list() {
+        await ensureConnected();
+        try {
+          const { tools, errors, elicitations } = await fetchGatewayTools();
+          const statuses = parseIntegrationStatus(tools, errors, elicitations);
+          const errorMap = new Map(errors.map((e) => [e.serverId, e.reason]));
+          return statuses.map((s) => {
+            const reason = errorMap.get(s.id);
+            return reason ? { ...s, reason } : s;
+          });
+        } catch (err) {
+          const translated = translateError(err);
+          if (translated instanceof AuthorizationRequiredError) {
+            setState("needs_auth");
+          }
+          throw translated;
+        }
+      }
+    },
+    tools: {
+      async list(options) {
+        await ensureConnected();
+        try {
+          const mcpTools = await mcp.listTools();
+          const nonMetaTools = mcpTools.filter(
+            (t) => !META_TOOL_NAMES.has(t.name)
+          );
+          if (nonMetaTools.length > 0 || !hasMetaTools(mcpTools)) {
+            _metaToolMode = false;
+            return nonMetaTools.map((t) => ({
+              id: t.name,
+              name: t.name,
+              description: t.description,
+              inputSchema: t.inputSchema
+            }));
+          }
+          _metaToolMode = true;
+          const { tools, elicitations } = await fetchGatewayTools(
+            options?.limit
+          );
+          if (elicitations?.length && config.onIntegrationRequired) {
+            for (const e of elicitations) {
+              if (e.url) {
+                config.onIntegrationRequired(e.url, {
+                  id: e.integrationId ?? "",
+                  name: e.integrationName ?? e.message
+                });
+              }
+            }
+          }
+          return tools.map(toKontextTool);
+        } catch (err) {
+          const translated = translateError(err);
+          if (translated instanceof AuthorizationRequiredError) {
+            setState("needs_auth");
+          }
+          throw translated;
+        }
+      },
+      async execute(toolId, args) {
+        await ensureConnected();
+        if (_metaToolMode === null) {
+          const mcpTools = await mcp.listTools();
+          _metaToolMode = hasMetaTools(mcpTools);
+        }
+        try {
+          const result = _metaToolMode ? await mcp.callTool("EXECUTE_TOOL", {
+            tool_id: toolId,
+            tool_arguments: args ?? {}
+          }) : await mcp.callTool(toolId, args);
+          return { content: extractTextContent(result), raw: result };
+        } catch (err) {
+          const translated = translateError(err);
+          if (translated instanceof AuthorizationRequiredError) {
+            setState("needs_auth");
+          }
+          throw translated;
+        }
+      }
+    },
+    on(event, handler) {
+      if (!_listeners.has(event)) {
+        _listeners.set(event, /* @__PURE__ */ new Set());
+      }
+      _listeners.get(event).add(handler);
+      return () => {
+        _listeners.get(event)?.delete(handler);
+      };
+    },
+    get mcp() {
+      return mcp;
+    }
+  };
+  return client;
+}
+function createKontextClient(config) {
+  if (config.url !== void 0) {
+    if (typeof config.url !== "string" || config.url.trim().length === 0) {
+      throw new ConfigError(
+        "url must be a non-empty string. Omit url for hybrid mode, or provide a full MCP endpoint URL.",
+        "kontext_config_invalid_url"
+      );
+    }
+    return createSingleEndpointKontextClient(config);
+  }
+  return createKontextOrchestrator(config);
+}
+
+// src/management/types.ts
+var TOKEN_EXCHANGE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:token-exchange";
+var TOKEN_TYPE_ACCESS_TOKEN = "urn:ietf:params:oauth:token-type:access_token";
+
+// src/oauth/token-exchange.ts
+async function exchangeToken(config, subjectToken, resource, scope, subjectTokenType = TOKEN_TYPE_ACCESS_TOKEN) {
+  const body = new URLSearchParams();
+  body.set("grant_type", TOKEN_EXCHANGE_GRANT_TYPE);
+  body.set("subject_token", subjectToken);
+  body.set("subject_token_type", subjectTokenType);
+  body.set("resource", resource);
+  const headers = {
+    "Content-Type": "application/x-www-form-urlencoded"
+  };
+  if (config.clientSecret) {
+    const credentials = Buffer.from(
+      `${config.clientId}:${config.clientSecret}`
+    ).toString("base64");
+    headers["Authorization"] = `Basic ${credentials}`;
+  } else {
+    body.set("client_id", config.clientId);
+  }
+  const response = await fetch(config.tokenUrl, {
+    method: "POST",
+    headers,
+    body: body.toString()
+  });
+  if (!response.ok) {
+    let errorMessage = `Token exchange failed: ${response.status} ${response.statusText}`;
+    let errorCode;
+    let integrationName;
+    let integrationId;
+    try {
+      const errorBody = await response.json();
+      errorCode = errorBody.error;
+      if (errorBody.error_description) {
+        errorMessage = errorBody.error_description;
+      } else if (errorBody.error) {
+        errorMessage = `Token exchange failed: ${errorBody.error}`;
+      }
+      if (errorBody.integration_name || errorBody.integration_id) {
+        integrationName = errorBody.integration_name;
+        integrationId = errorBody.integration_id;
+      }
+    } catch {
+    }
+    throw new OAuthError(errorMessage, "kontext_oauth_token_exchange_failed", {
+      errorCode,
+      meta: {
+        integrationName,
+        integrationId
+      }
+    });
+  }
+  const tokenResponse = await response.json();
+  if (!tokenResponse.access_token) {
+    throw new OAuthError(
+      "Token exchange response missing access_token.",
+      "kontext_oauth_token_exchange_failed"
+    );
+  }
+  if (!tokenResponse.issued_token_type) {
+    throw new OAuthError(
+      "Token exchange response missing issued_token_type.",
+      "kontext_oauth_token_exchange_failed"
+    );
+  }
+  if (!tokenResponse.token_type) {
+    throw new OAuthError(
+      "Token exchange response missing token_type.",
+      "kontext_oauth_token_exchange_failed"
+    );
+  }
+  return tokenResponse;
+}
+
+// src/verify/errors.ts
+var TokenVerificationError = class _TokenVerificationError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "TokenVerificationError";
+    this.code = code;
+    Object.setPrototypeOf(this, _TokenVerificationError.prototype);
+  }
+};
+
+// src/verify/jwks-client.ts
+var DEFAULT_CACHE_TTL_MS = 5 * 60 * 1e3;
+var DEFAULT_REFETCH_COOLDOWN_MS = 30 * 1e3;
+var JwksClient = class {
+  jwksUrl;
+  cacheTtlMs;
+  refetchCooldownMs;
+  customFetch;
+  jwks = null;
+  lastFetchAt = 0;
+  lastRefreshAt = 0;
+  constructor(options) {
+    this.jwksUrl = new URL(options.jwksUrl);
+    this.cacheTtlMs = options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+    this.refetchCooldownMs = options.refetchCooldownMs ?? DEFAULT_REFETCH_COOLDOWN_MS;
+    this.customFetch = options.fetch;
+  }
+  /**
+   * Get the JWKS key resolver for use with jose's jwtVerify.
+   *
+   * Creates the remote JWKS on first call and caches it.
+   * The jose library handles internal caching and key lookup.
+   */
+  getKeyResolver() {
+    const now = Date.now();
+    if (this.jwks && now - this.lastFetchAt > this.cacheTtlMs) {
+      this.jwks = null;
+    }
+    if (!this.jwks) {
+      this.jwks = createRemoteJWKSet(this.jwksUrl, {
+        // jose handles caching internally, we just track our own refresh timing
+        ...this.customFetch && {
+          [/* @__PURE__ */ Symbol.for("fetch")]: this.customFetch
+        }
+      });
+      this.lastFetchAt = now;
+    }
+    return this.jwks;
+  }
+  /**
+   * Force refresh the JWKS cache.
+   *
+   * Respects the refetch cooldown to prevent rapid refetching.
+   * Returns true if refresh was performed, false if cooldown not elapsed.
+   */
+  refresh() {
+    const now = Date.now();
+    if (!this.canRefresh()) {
+      return false;
+    }
+    this.jwks = null;
+    this.lastRefreshAt = now;
+    return true;
+  }
+  /**
+   * Check if a refresh is allowed (cooldown elapsed).
+   */
+  canRefresh() {
+    return Date.now() - this.lastRefreshAt >= this.refetchCooldownMs;
+  }
+  /**
+   * Handle unknown kid errors by attempting refresh.
+   *
+   * @returns TokenVerificationError if refresh not allowed or already attempted
+   */
+  handleUnknownKid(kid) {
+    if (this.refresh()) {
+      return null;
+    }
+    return new TokenVerificationError(
+      "UNKNOWN_KID",
+      `Unknown key ID: ${kid}. JWKS refresh on cooldown.`
+    );
+  }
+  /**
+   * Clear the cache, forcing a fresh fetch on next access.
+   */
+  clearCache() {
+    this.jwks = null;
+    this.lastFetchAt = 0;
+  }
+};
+
+// src/verify/verifier.ts
+var DEFAULT_CLOCK_TOLERANCE_SEC = 30;
+var SUPPORTED_ALGORITHMS = ["ES256", "RS256"];
+var KontextTokenVerifier = class {
+  config;
+  jwksClient;
+  audiences;
+  constructor(config) {
+    this.config = {
+      jwksUrl: config.jwksUrl,
+      issuer: config.issuer,
+      audience: config.audience,
+      requiredScopes: config.requiredScopes ?? [],
+      cacheTtlMs: config.cacheTtlMs ?? 5 * 60 * 1e3,
+      refetchCooldownMs: config.refetchCooldownMs ?? 30 * 1e3,
+      clockToleranceSec: config.clockToleranceSec ?? DEFAULT_CLOCK_TOLERANCE_SEC,
+      fetch: config.fetch
+    };
+    this.audiences = Array.isArray(config.audience) ? config.audience : [config.audience];
+    this.jwksClient = new JwksClient({
+      jwksUrl: config.jwksUrl,
+      cacheTtlMs: this.config.cacheTtlMs,
+      refetchCooldownMs: this.config.refetchCooldownMs,
+      fetch: config.fetch
+    });
+  }
+  /**
+   * Verify a JWT token.
+   *
+   * @param token - The JWT token string (without "Bearer " prefix)
+   * @returns VerifyResult with success=true and claims, or success=false and error
+   */
+  async verify(token) {
+    try {
+      return await this.verifyInternal(token, false);
+    } catch (error) {
+      if (error instanceof TokenVerificationError) {
+        return { success: false, error };
+      }
+      return {
+        success: false,
+        error: new TokenVerificationError(
+          "INVALID_TOKEN_FORMAT",
+          `Unexpected verification error: ${error.message}`
+        )
+      };
+    }
+  }
+  /**
+   * Verify a JWT token and return claims or null.
+   * Simpler API for cases where you don't need error details.
+   *
+   * @param token - The JWT token string (without "Bearer " prefix)
+   * @returns VerifiedTokenClaims if valid, null if invalid
+   */
+  async verifyOrNull(token) {
+    const result = await this.verify(token);
+    return result.success ? result.claims : null;
+  }
+  /**
+   * Clear the JWKS cache, forcing a fresh fetch on next verification.
+   */
+  clearCache() {
+    this.jwksClient.clearCache();
+  }
+  async verifyInternal(token, isRetry) {
+    const JWKS = this.jwksClient.getKeyResolver();
+    try {
+      const { payload, protectedHeader } = await jwtVerify(token, JWKS, {
+        issuer: this.config.issuer,
+        audience: this.audiences,
+        clockTolerance: this.config.clockToleranceSec,
+        algorithms: SUPPORTED_ALGORITHMS
+      });
+      const alg = protectedHeader.alg;
+      if (!SUPPORTED_ALGORITHMS.includes(alg)) {
+        throw new TokenVerificationError(
+          "UNSUPPORTED_ALGORITHM",
+          `Unsupported algorithm: ${alg}. Expected one of: ${SUPPORTED_ALGORITHMS.join(", ")}`
+        );
+      }
+      const jwtPayload = payload;
+      if (typeof jwtPayload.exp !== "number" || !Number.isFinite(jwtPayload.exp) || jwtPayload.exp <= 0) {
+        throw new TokenVerificationError(
+          "MISSING_CLAIMS",
+          "Token missing required exp claim"
+        );
+      }
+      const scopes = this.parseScopes(jwtPayload.scope);
+      for (const required of this.config.requiredScopes) {
+        if (!scopes.includes(required)) {
+          throw new TokenVerificationError(
+            "MISSING_SCOPE",
+            `Missing required scope: ${required}`
+          );
+        }
+      }
+      const clientId = jwtPayload.client_id || jwtPayload.sub;
+      if (!clientId) {
+        throw new TokenVerificationError(
+          "MISSING_CLAIMS",
+          "Token missing client_id and sub claims"
+        );
+      }
+      const claims = {
+        sub: jwtPayload.sub || "",
+        clientId,
+        scopes,
+        expiresAt: new Date(jwtPayload.exp * 1e3),
+        jti: jwtPayload.jti,
+        payload: jwtPayload
+      };
+      return { success: true, claims };
+    } catch (error) {
+      if (error instanceof errors.JWKSNoMatchingKey) {
+        if (!isRetry) {
+          const kid = this.extractKid(token);
+          const refreshError = this.jwksClient.handleUnknownKid(
+            kid || "unknown"
+          );
+          if (!refreshError) {
+            return this.verifyInternal(token, true);
+          }
+          return { success: false, error: refreshError };
+        }
+        return {
+          success: false,
+          error: new TokenVerificationError(
+            "UNKNOWN_KID",
+            "No matching key found in JWKS"
+          )
+        };
+      }
+      if (error instanceof errors.JWTExpired) {
+        return {
+          success: false,
+          error: new TokenVerificationError(
+            "TOKEN_EXPIRED",
+            "Token has expired"
+          )
+        };
+      }
+      if (error instanceof errors.JWTClaimValidationFailed) {
+        const message = error.message;
+        if (message.includes("iss")) {
+          const expected = Array.isArray(this.config.issuer) ? this.config.issuer.join(" or ") : this.config.issuer;
+          return {
+            success: false,
+            error: new TokenVerificationError(
+              "INVALID_ISSUER",
+              `Invalid issuer: expected ${expected}`
+            )
+          };
+        }
+        if (message.includes("aud")) {
+          return {
+            success: false,
+            error: new TokenVerificationError(
+              "INVALID_AUDIENCE",
+              `Invalid audience: expected one of ${this.audiences.join(", ")}`
+            )
+          };
+        }
+        if (message.includes("nbf")) {
+          return {
+            success: false,
+            error: new TokenVerificationError(
+              "TOKEN_NOT_YET_VALID",
+              "Token is not yet valid (nbf claim)"
+            )
+          };
+        }
+      }
+      if (error instanceof errors.JWSSignatureVerificationFailed) {
+        return {
+          success: false,
+          error: new TokenVerificationError(
+            "INVALID_SIGNATURE",
+            "Signature verification failed"
+          )
+        };
+      }
+      if (error instanceof errors.JWSInvalid) {
+        return {
+          success: false,
+          error: new TokenVerificationError(
+            "INVALID_TOKEN_FORMAT",
+            `Invalid JWS: ${error.message}`
+          )
+        };
+      }
+      if (error instanceof TokenVerificationError) {
+        throw error;
+      }
+      throw new TokenVerificationError(
+        "INVALID_TOKEN_FORMAT",
+        `Verification failed: ${error.message}`
+      );
+    }
+  }
+  parseScopes(scope) {
+    if (!scope) return [];
+    return scope.split(" ").map((s) => s.trim()).filter(Boolean);
+  }
+  extractKid(token) {
+    try {
+      const header = decodeProtectedHeader(token);
+      return header.kid ?? null;
+    } catch {
+      return null;
+    }
+  }
+};
+
+// src/server/sessions.ts
+var SessionManager = class _SessionManager {
+  transports = /* @__PURE__ */ new Map();
+  lastAccessed = /* @__PURE__ */ new Map();
+  expiresAt = /* @__PURE__ */ new Map();
+  cleanupInterval;
+  static STALE_TIMEOUT_MS = 60 * 60 * 1e3;
+  // 1 hour
+  static CLEANUP_INTERVAL_MS = 5 * 60 * 1e3;
+  // 5 minutes
+  constructor() {
+    this.cleanupInterval = setInterval(
+      () => this.cleanupStaleSessions(),
+      _SessionManager.CLEANUP_INTERVAL_MS
+    );
+    if (this.cleanupInterval.unref) {
+      this.cleanupInterval.unref();
+    }
+  }
+  getTransport(sessionId) {
+    return this.transports.get(sessionId);
+  }
+  registerSession(sessionId, transport, callbacks, expiresAt) {
+    this.transports.set(sessionId, transport);
+    this.lastAccessed.set(sessionId, Date.now());
+    if (expiresAt !== void 0) {
+      this.expiresAt.set(sessionId, expiresAt);
+    }
+    transport.onclose = () => {
+      this.removeSession(sessionId);
+      callbacks?.onSessionClosed?.(sessionId);
+    };
+  }
+  touchSession(sessionId) {
+    if (this.transports.has(sessionId)) {
+      this.lastAccessed.set(sessionId, Date.now());
+    }
+  }
+  removeSession(sessionId) {
+    this.transports.delete(sessionId);
+    this.lastAccessed.delete(sessionId);
+    this.expiresAt.delete(sessionId);
+  }
+  /**
+   * Check if a session's token has expired.
+   * Returns true if the token's `expiresAt` has passed.
+   */
+  isSessionExpired(sessionId) {
+    const exp = this.expiresAt.get(sessionId);
+    return exp !== void 0 && Date.now() / 1e3 >= exp;
+  }
+  cleanupStaleSessions() {
+    const now = Date.now();
+    for (const [sid, lastTime] of this.lastAccessed.entries()) {
+      if (now - lastTime > _SessionManager.STALE_TIMEOUT_MS) {
+        const transport = this.transports.get(sid);
+        if (transport) {
+          void transport.close?.();
+        }
+        this.removeSession(sid);
+      }
+    }
+  }
+  destroy() {
+    clearInterval(this.cleanupInterval);
+    for (const [sid, transport] of this.transports.entries()) {
+      void transport.close?.();
+      this.removeSession(sid);
+    }
+  }
+};
+
+// src/server/kontext.ts
+var DEFAULT_API_URL = "https://api.kontext.dev";
+var METADATA_CACHE_TTL_MS = 60 * 60 * 1e3;
+var CREDENTIAL_CACHE_MAX_ENTRIES = 500;
+var RUNTIME_AUTH_CACHE_MAX_ENTRIES = 8;
+var RESOLVED_CREDENTIAL_CACHE_TTL_MS = 30 * 1e3;
+var SDK_VERSION = (() => {
+  try {
+    const esmRequire = createRequire(import.meta.url);
+    const pkg = esmRequire("../../package.json");
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+})();
+var Kontext = class _Kontext {
+  static shutdownInstances = /* @__PURE__ */ new Set();
+  static shutdownHandlersRegistered = false;
+  clientId;
+  clientSecret;
+  apiUrl;
+  tokenIssuers;
+  // AS metadata: fetched lazily, cached with TTL
+  oauthMetadata = null;
+  metadataFetchedAt = 0;
+  metadataPromise = null;
+  // Token exchange caching: keyed by `${integration}\0${subjectToken}`
+  credentialCache = /* @__PURE__ */ new Map();
+  resolvedCredentialCache = /* @__PURE__ */ new Map();
+  runtimeAuthCache = /* @__PURE__ */ new Map();
+  runtimeVerifierIds = /* @__PURE__ */ new WeakMap();
+  runtimeVerifierIdCounter = 0;
+  // Telemetry: cached service token for event reporting
+  serviceToken = null;
+  serviceTokenExp = 0;
+  serviceTokenPromise = null;
+  // Session tracking: MCP sessionId → API agentSessionId
+  agentSessionIds = /* @__PURE__ */ new Map();
+  pendingSessionDisconnects = /* @__PURE__ */ new Set();
+  constructor(options) {
+    this.clientId = options.clientId;
+    this.clientSecret = options.clientSecret ?? process.env.KONTEXT_CLIENT_SECRET;
+    this.apiUrl = (options.apiUrl ?? DEFAULT_API_URL).replace(/\/$/, "");
+    const rawTokenIssuers = Array.isArray(options.tokenIssuer) ? options.tokenIssuer : options.tokenIssuer ? options.tokenIssuer.split(",") : process.env.KONTEXT_TOKEN_ISSUER?.split(",");
+    this.tokenIssuers = Array.from(
+      new Set(rawTokenIssuers?.map((issuer) => issuer.trim()).filter(Boolean))
+    );
+    _Kontext.shutdownInstances.add(this);
+    _Kontext.ensureShutdownHandlers();
+  }
+  /**
+   * Cleanup method for runtimes that create/dispose SDK instances dynamically.
+   * Ensures this instance can be garbage-collected by removing static references.
+   */
+  async destroy() {
+    await this.disconnectAllSessions();
+    _Kontext.shutdownInstances.delete(this);
+    this.credentialCache.clear();
+    this.resolvedCredentialCache.clear();
+    this.oauthMetadata = null;
+    this.metadataFetchedAt = 0;
+    this.metadataPromise = null;
+    this.serviceToken = null;
+    this.serviceTokenExp = 0;
+    this.serviceTokenPromise = null;
+    this.agentSessionIds.clear();
+    this.pendingSessionDisconnects.clear();
+  }
+  static ensureShutdownHandlers() {
+    if (_Kontext.shutdownHandlersRegistered) return;
+    const onShutdown = () => {
+      for (const instance of _Kontext.shutdownInstances) {
+        void instance.disconnectAllSessions();
+      }
+    };
+    process.once("SIGINT", onShutdown);
+    process.once("SIGTERM", onShutdown);
+    _Kontext.shutdownHandlersRegistered = true;
+  }
+  // ===========================================================================
+  // middleware()
+  // ===========================================================================
+  /**
+   * Express middleware: `.well-known` metadata + bearer auth + MCP transport + sessions.
+   *
+   * Must be mounted at the app root (not a sub-path) because RFC 9728 requires
+   * `/.well-known/oauth-protected-resource` at the root. Use `mcpPath` to set
+   * the transport endpoint path.
+   *
+   * @param server - An `McpServer` instance for single-session use, or a
+   *   `() => McpServer` factory for concurrent sessions (recommended in production).
+   *   `McpServer.connect()` is 1:1 per the MCP spec — passing a factory ensures
+   *   each session gets its own instance.
+   *
+   * @example Factory pattern (recommended for concurrent sessions)
+   * ```typescript
+   * app.use(kontext.middleware(() => createServer()));
+   * ```
+   *
+   * @example Single instance (local dev / single session)
+   * ```typescript
+   * app.use(kontext.middleware(server));
+   * ```
+   *
+   * @example Custom path
+   * ```typescript
+   * app.use(kontext.middleware(createServer, { mcpPath: "/api/mcp" }));
+   * ```
+   */
+  middleware(server, options) {
+    const esmRequire = createRequire(import.meta.url);
+    const express = esmRequire("express");
+    const router = express.Router();
+    const mcpPath = options?.mcpPath ?? "/mcp";
+    const sessionManager = new SessionManager();
+    const omitAuth = options?.dangerouslyOmitAuth ?? false;
+    router.use((_req, res, next) => {
+      res.header("Access-Control-Allow-Origin", "*");
+      res.header(
+        "Access-Control-Allow-Headers",
+        "Content-Type, Authorization, Mcp-Session-Id, Mcp-Protocol-Version, Accept"
+      );
+      res.header("Access-Control-Expose-Headers", "Mcp-Session-Id");
+      res.header("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+      if (_req.method === "OPTIONS") {
+        res.sendStatus(204);
+        return;
+      }
+      next();
+    });
+    if (omitAuth) {
+      console.warn(
+        "[kontext] \u26A0\uFE0F  Auth is disabled (dangerouslyOmitAuth). Do NOT use in production."
+      );
+      router.use(mcpPath, express.json({ limit: options?.bodyLimit ?? "1mb" }));
+      const mcpHandler2 = this.createMcpHandler(
+        server,
+        sessionManager,
+        null,
+        options
+      );
+      router.post(mcpPath, mcpHandler2.post);
+      router.get(mcpPath, mcpHandler2.get);
+      router.delete(mcpPath, mcpHandler2.delete);
+      return router;
+    }
+    const getRuntimeAuth = async (req) => {
+      const metadata = this.applyMetadataTransform(
+        await this.getOAuthMetadata(),
+        options?.metadataTransform
+      );
+      const rsUrl = this.resolveResourceServerUrl(req, mcpPath, options);
+      return this.getOrCreateRuntimeAuthContext(
+        metadata,
+        rsUrl,
+        options?.verifier
+      );
+    };
+    router.use(async (req, res, next) => {
+      const path = req.path || req.url || "";
+      const isMetadataRequest = path.startsWith("/.well-known/oauth-authorization-server") || path.startsWith("/.well-known/oauth-protected-resource");
+      if (!isMetadataRequest) {
+        next();
+        return;
+      }
+      try {
+        const runtimeAuth = await getRuntimeAuth(req);
+        runtimeAuth.metadataRouter(req, res, next);
+      } catch (error) {
+        this.respondMetadataInitError(res, error);
+      }
+    });
+    router.use(mcpPath, express.json({ limit: options?.bodyLimit ?? "1mb" }));
+    const mcpHandler = this.createMcpHandler(
+      server,
+      sessionManager,
+      getRuntimeAuth,
+      options
+    );
+    router.post(mcpPath, mcpHandler.post);
+    router.get(mcpPath, mcpHandler.get);
+    router.delete(mcpPath, mcpHandler.delete);
+    return router;
+  }
+  // ===========================================================================
+  // require()
+  // ===========================================================================
+  /**
+   * Exchange a user's access token for an integration credential.
+   *
+   * @param integration - Integration name (e.g., "github")
+   * @param token - The user's Bearer token (from `authInfo.token`)
+   * @returns Integration credential with `accessToken` and `authorization` header
+   *
+   * @throws {IntegrationConnectionRequiredError} User hasn't connected this integration
+   * @throws {OAuthError} Token exchange failed
+   */
+  async require(integration, token) {
+    const now = Date.now();
+    this.evictExpiredCredentials(now);
+    const cacheKey = `${integration}\0${token}`;
+    const cached = this.credentialCache.get(cacheKey);
+    if (cached && now < cached.expiresAt) {
+      this.credentialCache.delete(cacheKey);
+      this.credentialCache.set(cacheKey, cached);
+      return cached.credential;
+    }
+    if (cached) {
+      this.credentialCache.delete(cacheKey);
+    }
+    const exchangeConfig = {
+      tokenUrl: `${this.apiUrl}/oauth2/token`,
+      clientId: this.clientId,
+      clientSecret: this.clientSecret
+    };
+    let response;
+    try {
+      response = await exchangeToken(exchangeConfig, token, integration);
+    } catch (err) {
+      if (err instanceof OAuthError) {
+        if (err.errorCode === "integration_required" || err.message.includes("not connected") || err.message.includes("expired") && err.message.includes("reconnect")) {
+          const integrationId = err.meta.integrationId || integration;
+          const connectUrl = await this.fetchConnectUrl(
+            token,
+            integrationId,
+            exchangeConfig
+          );
+          throw new IntegrationConnectionRequiredError(integrationId, {
+            integrationName: err.meta.integrationName,
+            connectUrl,
+            message: err.message
+          });
+        }
+      }
+      throw err;
+    }
+    const credential = {
+      accessToken: response.access_token,
+      tokenType: response.token_type,
+      authorization: `${response.token_type} ${response.access_token}`,
+      expiresIn: response.expires_in,
+      scope: response.scope,
+      integration
+    };
+    if (response.expires_in) {
+      const ttlMs = Math.min(response.expires_in - 60, 5 * 60) * 1e3;
+      if (ttlMs > 0) {
+        this.trimCacheToFit(this.credentialCache, CREDENTIAL_CACHE_MAX_ENTRIES);
+        this.credentialCache.set(cacheKey, {
+          credential,
+          expiresAt: now + ttlMs
+        });
+      }
+    }
+    return credential;
+  }
+  /**
+   * Resolve per-user credential key/value pairs for an internal MCP integration.
+   *
+   * @param integration - Integration UUID or name
+   * @param token - The user's Bearer token (from `authInfo.token`)
+   * @returns Decrypted credential map for the current user and integration
+   *
+   * @throws {IntegrationConnectionRequiredError} User has not provided required credentials
+   * @throws {OAuthError} Runtime credential resolution failed
+   */
+  async requireCredentials(integration, token) {
+    const now = Date.now();
+    this.evictExpiredResolvedCredentials(now);
+    const cacheKey = `${integration}\0${token}\0internal_credentials`;
+    const cached = this.resolvedCredentialCache.get(cacheKey);
+    if (cached && now < cached.expiresAt) {
+      this.resolvedCredentialCache.delete(cacheKey);
+      this.resolvedCredentialCache.set(cacheKey, cached);
+      return cached.credential;
+    }
+    if (cached) {
+      this.resolvedCredentialCache.delete(cacheKey);
+    }
+    const exchangeConfig = {
+      tokenUrl: `${this.apiUrl}/oauth2/token`,
+      clientId: this.clientId,
+      clientSecret: this.clientSecret
+    };
+    let gatewayAccessToken = token;
+    if (!this.isGatewayScopedToken(token)) {
+      try {
+        const exchanged = await exchangeToken(
+          exchangeConfig,
+          token,
+          "mcp-gateway"
+        );
+        gatewayAccessToken = exchanged.access_token;
+      } catch (err) {
+        throw new OAuthError(
+          "Failed to exchange subject token for runtime",
+          "kontext_credentials_exchange_failed",
+          {
+            errorCode: "credentials_exchange_failed",
+            errorDescription: err instanceof Error ? err.message : String(err ?? "unknown error")
+          }
+        );
+      }
+    }
+    const integrationId = await this.resolveRuntimeIntegrationId(
+      integration,
+      gatewayAccessToken
+    );
+    const res = await fetch(
+      `${this.apiUrl}/mcp/integrations/${integrationId}/credentials/resolve`,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${gatewayAccessToken}`,
+          "Content-Type": "application/json"
+        },
+        body: "{}"
+      }
+    );
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      const message = text && text.trim().length > 0 ? text : `HTTP ${res.status} while resolving credentials`;
+      if (res.status === 400 && message.toLowerCase().includes("credentials required")) {
+        throw new IntegrationConnectionRequiredError(integrationId, {
+          integrationName: String(integration),
+          message
+        });
+      }
+      throw new OAuthError(
+        `Failed to resolve credentials for integration ${integrationId}`,
+        "kontext_credentials_resolve_failed",
+        {
+          errorCode: "credentials_resolve_failed",
+          errorDescription: message
+        }
+      );
+    }
+    const payload = await res.json();
+    if (!payload.credentials || typeof payload.credentials !== "object" || Array.isArray(payload.credentials)) {
+      throw new OAuthError(
+        "Credential resolve returned invalid payload",
+        "kontext_credentials_invalid_payload"
+      );
+    }
+    const credentials = {};
+    for (const [key, value] of Object.entries(payload.credentials)) {
+      if (typeof value === "string") {
+        credentials[key] = value;
+      }
+    }
+    if (Object.keys(credentials).length === 0) {
+      throw new IntegrationConnectionRequiredError(integrationId, {
+        integrationName: String(integration),
+        message: "No credentials configured for this integration"
+      });
+    }
+    const resolved = {
+      integration,
+      integrationId: payload.integrationId ?? integrationId,
+      credentials
+    };
+    this.trimCacheToFit(
+      this.resolvedCredentialCache,
+      CREDENTIAL_CACHE_MAX_ENTRIES
+    );
+    this.resolvedCredentialCache.set(cacheKey, {
+      credential: resolved,
+      expiresAt: now + RESOLVED_CREDENTIAL_CACHE_TTL_MS
+    });
+    return resolved;
+  }
+  getGatewayAudiences() {
+    return /* @__PURE__ */ new Set([`${new URL(this.apiUrl).origin}/mcp`, "mcp-gateway"]);
+  }
+  isGatewayScopedToken(token) {
+    const audiences = this.extractTokenAudiences(token);
+    if (audiences.length === 0) {
+      return false;
+    }
+    const gatewayAudiences = this.getGatewayAudiences();
+    return audiences.some((audience) => gatewayAudiences.has(audience));
+  }
+  extractTokenAudiences(token) {
+    const [, payloadPart] = token.split(".");
+    if (!payloadPart) return [];
+    try {
+      const payload = JSON.parse(
+        Buffer.from(payloadPart, "base64url").toString("utf8")
+      );
+      if (typeof payload.aud === "string") {
+        return [payload.aud];
+      }
+      if (Array.isArray(payload.aud)) {
+        return payload.aud.filter(
+          (value) => typeof value === "string"
+        );
+      }
+    } catch {
+    }
+    return [];
+  }
+  // ===========================================================================
+  // Private: fetch connect URL (spec §2 — two-step init)
+  // ===========================================================================
+  async resolveRuntimeIntegrationId(integration, runtimeToken) {
+    const raw = String(integration);
+    if (this.isUuid(raw)) {
+      return raw;
+    }
+    const res = await fetch(`${this.apiUrl}/mcp/integrations`, {
+      headers: {
+        Authorization: `Bearer ${runtimeToken}`
+      }
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new OAuthError(
+        "Failed to resolve integration identifier",
+        "kontext_integration_lookup_failed",
+        {
+          errorCode: "integration_lookup_failed",
+          errorDescription: text || `HTTP ${res.status}`
+        }
+      );
+    }
+    const payload = await res.json();
+    const items = Array.isArray(payload.items) ? payload.items : [];
+    const match = items.find((item) => item.id === raw || item.name === raw);
+    const integrationId = match?.id;
+    if (!integrationId) {
+      throw new IntegrationConnectionRequiredError(raw, {
+        integrationName: raw,
+        message: `Integration ${raw} is not attached to this application`
+      });
+    }
+    return integrationId;
+  }
+  isUuid(value) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(
+      value
+    );
+  }
+  /**
+   * Fetch a browser-openable connect URL for a missing integration.
+   *
+   * Per the integration-interrupt-flow spec, the SDK:
+   * 1. Exchanges the user's token for a resource-scoped mcp-gateway JWT
+   * 2. Calls POST /mcp/integrations/:id/oauth/init with that JWT
+   * 3. Returns the `connectUrl` (intermediate endpoint with one-time token)
+   *
+   * The connect URL points to our own server (ticket pattern), which
+   * validates the ticket, sets a browser session cookie, then redirects
+   * to the actual OAuth provider.
+   */
+  async fetchConnectUrl(subjectToken, integrationId, exchangeConfig) {
+    try {
+      const gatewayToken = await exchangeToken(
+        exchangeConfig,
+        subjectToken,
+        "mcp-gateway"
+      );
+      const initUrl = `${this.apiUrl}/mcp/integrations/${integrationId}/oauth/init`;
+      const res = await fetch(initUrl, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${gatewayToken.access_token}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({})
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        console.warn(
+          `[kontext] fetchConnectUrl: init endpoint returned ${res.status}: ${text}`
+        );
+        return void 0;
+      }
+      const data = await res.json();
+      return data.connectUrl ?? data.authorizationUrl;
+    } catch (err) {
+      console.warn(
+        `[kontext] fetchConnectUrl failed:`,
+        err instanceof Error ? err.message : String(err)
+      );
+      return void 0;
+    }
+  }
+  // ===========================================================================
+  // Private: AS metadata
+  // ===========================================================================
+  async getOAuthMetadata() {
+    const now = Date.now();
+    if (this.oauthMetadata && now - this.metadataFetchedAt < METADATA_CACHE_TTL_MS) {
+      return this.oauthMetadata;
+    }
+    if (this.metadataPromise) {
+      return this.metadataPromise;
+    }
+    this.metadataPromise = this.fetchOAuthMetadata();
+    try {
+      const metadata = await this.metadataPromise;
+      this.oauthMetadata = metadata;
+      this.metadataFetchedAt = Date.now();
+      return metadata;
+    } finally {
+      this.metadataPromise = null;
+    }
+  }
+  applyMetadataTransform(metadata, metadataTransform) {
+    if (!metadataTransform) {
+      return metadata;
+    }
+    return metadataTransform(this.cloneOAuthMetadata(metadata));
+  }
+  cloneOAuthMetadata(metadata) {
+    return JSON.parse(JSON.stringify(metadata));
+  }
+  async fetchOAuthMetadata() {
+    const urls = [
+      `${this.apiUrl}/.well-known/oauth-authorization-server`,
+      `${this.apiUrl}/.well-known/openid-configuration`
+    ];
+    let lastError;
+    for (const url of urls) {
+      try {
+        const res = await fetch(url);
+        if (res.ok) {
+          return await res.json();
+        }
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+      }
+    }
+    throw new Error(
+      `Failed to fetch AS metadata from ${this.apiUrl}: ${lastError?.message ?? "unknown error"}`
+    );
+  }
+  resolveResourceServerUrl(req, mcpPath, options) {
+    if (options?.resourceServerUrl) {
+      return new URL(options.resourceServerUrl);
+    }
+    const host = req.get("host");
+    if (!host) {
+      throw new Error(
+        "Missing Host header. Set middleware({ resourceServerUrl }) to a trusted public URL."
+      );
+    }
+    return new URL(`${req.protocol}://${host}${mcpPath}`);
+  }
+  getOrCreateRuntimeAuthContext(metadata, rsUrl, customVerifier) {
+    const key = this.getRuntimeAuthCacheKey(rsUrl, customVerifier);
+    const cached = this.runtimeAuthCache.get(key);
+    if (cached) {
+      this.runtimeAuthCache.delete(key);
+      this.runtimeAuthCache.set(key, cached);
+      return cached;
+    }
+    const proxiedMetadata = { ...metadata, issuer: `${rsUrl.origin}/` };
+    const metadataRouter = mcpAuthMetadataRouter({
+      oauthMetadata: proxiedMetadata,
+      resourceServerUrl: rsUrl
+    });
+    const resourceMetadataUrl = getOAuthProtectedResourceMetadataUrl(rsUrl);
+    const verifier = customVerifier ?? this.createTokenVerifier(metadata, rsUrl);
+    const runtimeAuth = {
+      metadataRouter,
+      bearerAuth: requireBearerAuth({
+        verifier,
+        resourceMetadataUrl
+      })
+    };
+    this.trimCacheToFit(this.runtimeAuthCache, RUNTIME_AUTH_CACHE_MAX_ENTRIES);
+    this.runtimeAuthCache.set(key, runtimeAuth);
+    return runtimeAuth;
+  }
+  getRuntimeAuthCacheKey(rsUrl, customVerifier) {
+    if (!customVerifier) {
+      return `${rsUrl.href}\0default`;
+    }
+    let verifierId = this.runtimeVerifierIds.get(customVerifier);
+    if (verifierId === void 0) {
+      verifierId = ++this.runtimeVerifierIdCounter;
+      this.runtimeVerifierIds.set(customVerifier, verifierId);
+    }
+    return `${rsUrl.href}\0custom:${verifierId}`;
+  }
+  respondMetadataInitError(res, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`[kontext] Failed to fetch AS metadata: ${message}`);
+    if (res.headersSent) return;
+    res.status(503).json({
+      error: "service_unavailable",
+      error_description: "Failed to fetch authorization server metadata. Retry later."
+    });
+  }
+  evictExpiredCredentials(now) {
+    for (const [key, value] of this.credentialCache.entries()) {
+      if (value.expiresAt <= now) {
+        this.credentialCache.delete(key);
+      }
+    }
+  }
+  evictExpiredResolvedCredentials(now) {
+    for (const [key, value] of this.resolvedCredentialCache.entries()) {
+      if (value.expiresAt <= now) {
+        this.resolvedCredentialCache.delete(key);
+      }
+    }
+  }
+  trimCacheToFit(cache, maxEntries) {
+    while (cache.size >= maxEntries) {
+      const oldestKey = cache.keys().next().value;
+      if (!oldestKey) break;
+      cache.delete(oldestKey);
+    }
+  }
+  // ===========================================================================
+  // Private: token verifier
+  // ===========================================================================
+  createTokenVerifier(metadata, resourceUrl) {
+    const metadataRaw = metadata;
+    const jwksUri = metadataRaw.jwks_uri ?? `${this.apiUrl}/.well-known/jwks.json`;
+    const clientId = this.clientId;
+    const issuers = Array.from(
+      new Set(
+        [metadata.issuer, ...this.tokenIssuers].filter(
+          (issuer2) => typeof issuer2 === "string" && !!issuer2
+        )
+      )
+    );
+    if (!issuers.length) {
+      throw new Error("OAuth metadata missing issuer");
+    }
+    const issuer = issuers.length === 1 ? issuers[0] : issuers;
+    const verifier = new KontextTokenVerifier({
+      jwksUrl: jwksUri,
+      issuer,
+      audience: resourceUrl.href
+    });
+    return {
+      async verifyAccessToken(token) {
+        const result = await verifier.verify(token);
+        if (!result.success) {
+          throw new InvalidTokenError(
+            `Token verification failed: ${result.error.message}`
+          );
+        }
+        const { claims } = result;
+        const payload = claims.payload;
+        const ext = payload.ext ?? {};
+        return {
+          token,
+          clientId: claims.clientId ?? clientId,
+          scopes: claims.scopes,
+          expiresAt: Math.floor(claims.expiresAt.getTime() / 1e3),
+          extra: {
+            ...ext,
+            sub: claims.sub,
+            email: payload.email ?? ext.email
+          }
+        };
+      }
+    };
+  }
+  // ===========================================================================
+  // Private: telemetry
+  // ===========================================================================
+  async getServiceToken() {
+    if (this.serviceToken && Date.now() < this.serviceTokenExp - 3e4) {
+      return this.serviceToken;
+    }
+    if (this.serviceTokenPromise) {
+      return this.serviceTokenPromise;
+    }
+    this.serviceTokenPromise = (async () => {
+      const res = await fetch(`${this.apiUrl}/oauth2/token`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          Authorization: `Basic ${Buffer.from(this.clientId + ":" + this.clientSecret).toString("base64")}`
+        },
+        body: "grant_type=client_credentials"
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(
+          `[kontext:telemetry] client_credentials grant failed: HTTP ${res.status} ${text}`
+        );
+      }
+      const data = await res.json();
+      this.serviceToken = data.access_token;
+      this.serviceTokenExp = Date.now() + data.expires_in * 1e3;
+      return data.access_token;
+    })();
+    try {
+      return await this.serviceTokenPromise;
+    } finally {
+      this.serviceTokenPromise = null;
+    }
+  }
+  reportEvent(event) {
+    if (!this.clientSecret || !event.sessionId) return;
+    this.getServiceToken().then(
+      (token) => fetch(`${this.apiUrl}/api/v1/mcp-events`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${token}`
+        },
+        body: JSON.stringify({
+          ...event,
+          agentId: this.clientId,
+          clientId: this.clientId,
+          clientVersion: SDK_VERSION
+        })
+      }).then((res) => {
+        if (!res.ok) {
+          console.warn(
+            `[kontext:telemetry] event report failed: HTTP ${res.status}`
+          );
+        }
+      })
+    ).catch((err) => {
+      console.warn(
+        `[kontext:telemetry] error:`,
+        err instanceof Error ? err.message : String(err)
+      );
+    });
+  }
+  // ===========================================================================
+  // Private: session lifecycle
+  // ===========================================================================
+  createAgentSession(userToken, mcpSessionId, metadata) {
+    if (!this.clientSecret || !userToken) return;
+    const tokenIdentifier = createHash("sha256").update(userToken).digest("hex");
+    this.getServiceToken().then(
+      (token) => fetch(`${this.apiUrl}/api/v1/agent-sessions`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${token}`
+        },
+        body: JSON.stringify({
+          tokenIdentifier,
+          hostname: metadata?.hostname,
+          userAgent: metadata?.userAgent,
+          clientInfo: metadata?.clientInfo,
+          tokenExpiresAt: metadata?.tokenExpiresAt ? new Date(metadata.tokenExpiresAt * 1e3).toISOString() : void 0
+        })
+      }).then(async (res) => {
+        if (res.ok) {
+          const data = await res.json();
+          if (this.pendingSessionDisconnects.delete(mcpSessionId)) {
+            this.disconnectAgentSessionByAgentSessionId(
+              data.sessionId,
+              token
+            );
+            return;
+          }
+          this.agentSessionIds.set(mcpSessionId, data.sessionId);
+        } else {
+          this.pendingSessionDisconnects.delete(mcpSessionId);
+          console.warn(
+            `[kontext:sessions] create failed: HTTP ${res.status}`
+          );
+        }
+      })
+    ).catch((err) => {
+      this.pendingSessionDisconnects.delete(mcpSessionId);
+      console.warn(
+        `[kontext:sessions] error:`,
+        err instanceof Error ? err.message : String(err)
+      );
+    });
+  }
+  disconnectAgentSessionByAgentSessionId(agentSessionId, serviceToken) {
+    if (!this.clientSecret) return;
+    const tokenPromise = serviceToken ? Promise.resolve(serviceToken) : this.getServiceToken();
+    tokenPromise.then(
+      (token) => fetch(
+        `${this.apiUrl}/api/v1/agent-sessions/${agentSessionId}/disconnect`,
+        {
+          method: "POST",
+          headers: { Authorization: `Bearer ${token}` }
+        }
+      )
+    ).catch(() => {
+    });
+  }
+  disconnectAgentSession(mcpSessionId) {
+    if (!this.clientSecret) return;
+    const agentSessionId = this.agentSessionIds.get(mcpSessionId);
+    this.agentSessionIds.delete(mcpSessionId);
+    if (!agentSessionId) {
+      this.pendingSessionDisconnects.add(mcpSessionId);
+      return;
+    }
+    this.pendingSessionDisconnects.delete(mcpSessionId);
+    this.disconnectAgentSessionByAgentSessionId(agentSessionId);
+  }
+  async disconnectAllSessions() {
+    if (!this.clientSecret) return;
+    if (this.agentSessionIds.size === 0) {
+      this.pendingSessionDisconnects.clear();
+      return;
+    }
+    try {
+      const token = await this.getServiceToken();
+      await Promise.allSettled(
+        [...this.agentSessionIds.values()].map(
+          (agentSessionId) => fetch(
+            `${this.apiUrl}/api/v1/agent-sessions/${agentSessionId}/disconnect`,
+            {
+              method: "POST",
+              headers: { Authorization: `Bearer ${token}` }
+            }
+          )
+        )
+      );
+    } catch {
+    }
+    this.agentSessionIds.clear();
+    this.pendingSessionDisconnects.clear();
+  }
+  // ===========================================================================
+  // Private: MCP transport handlers
+  // ===========================================================================
+  async runBearerAuth(bearerAuth, req, res) {
+    await new Promise((resolve, reject) => {
+      let settled = false;
+      let nextCalled = false;
+      const cleanup = () => {
+        res.removeListener("finish", onResponseDone);
+        res.removeListener("close", onResponseDone);
+      };
+      const settleResolve = () => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        resolve();
+      };
+      const settleReject = (err) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        reject(err instanceof Error ? err : new Error(String(err)));
+      };
+      const onResponseDone = () => {
+        settleResolve();
+      };
+      res.once("finish", onResponseDone);
+      res.once("close", onResponseDone);
+      let middlewareResult;
+      try {
+        middlewareResult = bearerAuth(req, res, (err) => {
+          nextCalled = true;
+          if (err) {
+            settleReject(err);
+            return;
+          }
+          settleResolve();
+        });
+      } catch (err) {
+        settleReject(err);
+        return;
+      }
+      void Promise.resolve(middlewareResult).then(
+        () => {
+          if (!nextCalled && res.headersSent) {
+            settleResolve();
+          }
+        },
+        (err) => {
+          settleReject(err);
+        }
+      );
+    });
+  }
+  createMcpHandler(server, sessionManager, getRuntimeAuth, options) {
+    const callbacks = {
+      onSessionClosed: (sessionId) => {
+        options?.onSessionClosed?.(sessionId);
+        this.disconnectAgentSession(sessionId);
+      }
+    };
+    const post = async (req, res) => {
+      const traceId = crypto.randomUUID();
+      const authReq = req;
+      if (getRuntimeAuth) {
+        let bearerAuth;
+        try {
+          const runtimeAuth = await getRuntimeAuth(req);
+          bearerAuth = runtimeAuth.bearerAuth;
+        } catch (error) {
+          this.respondMetadataInitError(res, error);
+          return;
+        }
+        await this.runBearerAuth(bearerAuth, req, res);
+        const sessionId2 = req.headers["mcp-session-id"];
+        if (sessionId2) {
+          if (res.headersSent) {
+            this.reportEvent({
+              eventType: "auth_error",
+              traceId,
+              sessionId: sessionId2,
+              durationMs: 0,
+              status: "error_auth"
+            });
+            return;
+          }
+          if (authReq.auth) {
+            this.reportEvent({
+              eventType: "auth_ok",
+              traceId,
+              ownerUserId: authReq.auth.extra?.sub,
+              sessionId: sessionId2,
+              durationMs: 0,
+              status: "ok"
+            });
+          }
+        } else if (res.headersSent) {
+          return;
+        }
+      }
+      const sessionId = req.headers["mcp-session-id"];
+      if (sessionId) {
+        const transport2 = sessionManager.getTransport(sessionId);
+        if (transport2) {
+          sessionManager.touchSession(sessionId);
+          await transport2.handleRequest(req, res, req.body);
+          return;
+        }
+      }
+      if (!isInitializeRequest(req.body)) {
+        res.status(400).json({
+          jsonrpc: "2.0",
+          error: {
+            code: -32e3,
+            message: sessionId ? `Session ${sessionId} not found` : "No valid session ID provided"
+          },
+          id: null
+        });
+        return;
+      }
+      const authInfo = authReq.auth;
+      const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => crypto.randomUUID(),
+        onsessioninitialized: (sid) => {
+          sessionManager.registerSession(
+            sid,
+            transport,
+            callbacks,
+            authInfo?.expiresAt
+          );
+          options?.onSessionInitialized?.(sid, authInfo, transport);
+          this.reportEvent({
+            eventType: "initialize",
+            traceId,
+            sessionId: sid,
+            ownerUserId: authInfo?.extra?.sub,
+            durationMs: 0,
+            status: "ok"
+          });
+          this.createAgentSession(authInfo?.token, sid, {
+            hostname: req.headers["x-forwarded-for"],
+            userAgent: req.headers["user-agent"],
+            tokenExpiresAt: authInfo?.expiresAt
+          });
+        }
+      });
+      const originalHandle = transport.handleRequest.bind(transport);
+      transport.handleRequest = async (wrappedReq, wrappedRes, parsedBody) => {
+        const reqTraceId = wrappedReq === req ? traceId : crypto.randomUUID();
+        const sid = wrappedReq.headers["mcp-session-id"] ?? transport.sessionId;
+        const start = Date.now();
+        try {
+          await originalHandle(wrappedReq, wrappedRes, parsedBody);
+          if (parsedBody?.method === "tools/call") {
+            this.reportEvent({
+              eventType: "execute_tool",
+              traceId: reqTraceId,
+              toolName: parsedBody.params?.name,
+              durationMs: Date.now() - start,
+              sessionId: sid,
+              ownerUserId: authInfo?.extra?.sub,
+              status: "ok",
+              requestJson: parsedBody.params
+            });
+          } else if (parsedBody?.method === "tools/list") {
+            this.reportEvent({
+              eventType: "search_tools",
+              traceId: reqTraceId,
+              durationMs: Date.now() - start,
+              sessionId: sid,
+              ownerUserId: authInfo?.extra?.sub,
+              status: "ok"
+            });
+          }
+        } catch (err) {
+          if (parsedBody?.method === "tools/call") {
+            this.reportEvent({
+              eventType: "execute_tool",
+              traceId: reqTraceId,
+              toolName: parsedBody.params?.name,
+              durationMs: Date.now() - start,
+              sessionId: sid,
+              ownerUserId: authInfo?.extra?.sub,
+              status: "error_remote",
+              errorMessage: err instanceof Error ? err.message : String(err)
+            });
+          } else if (parsedBody?.method === "tools/list") {
+            this.reportEvent({
+              eventType: "search_tools",
+              traceId: reqTraceId,
+              durationMs: Date.now() - start,
+              sessionId: sid,
+              ownerUserId: authInfo?.extra?.sub,
+              status: "error_remote",
+              errorMessage: err instanceof Error ? err.message : String(err)
+            });
+          }
+          throw err;
+        }
+      };
+      const mcpServer = typeof server === "function" ? server() : server;
+      await mcpServer.connect(transport);
+      await transport.handleRequest(req, res, req.body);
+    };
+    const get = async (req, res) => {
+      if (getRuntimeAuth) {
+        let bearerAuth;
+        try {
+          const runtimeAuth = await getRuntimeAuth(req);
+          bearerAuth = runtimeAuth.bearerAuth;
+        } catch (error) {
+          this.respondMetadataInitError(res, error);
+          return;
+        }
+        await this.runBearerAuth(bearerAuth, req, res);
+        if (res.headersSent) {
+          return;
+        }
+      }
+      const sessionId = req.headers["mcp-session-id"] || req.headers["Mcp-Session-Id"];
+      if (!sessionId) {
+        res.status(400).json({ error: "Missing Mcp-Session-Id header" });
+        return;
+      }
+      const transport = sessionManager.getTransport(sessionId);
+      if (!transport) {
+        res.status(400).json({ error: "Session not found" });
+        return;
+      }
+      sessionManager.touchSession(sessionId);
+      await transport.handleRequest(req, res);
+    };
+    const del = async (req, res) => {
+      if (getRuntimeAuth) {
+        let bearerAuth;
+        try {
+          const runtimeAuth = await getRuntimeAuth(req);
+          bearerAuth = runtimeAuth.bearerAuth;
+        } catch (error) {
+          this.respondMetadataInitError(res, error);
+          return;
+        }
+        await this.runBearerAuth(bearerAuth, req, res);
+        if (res.headersSent) {
+          return;
+        }
+      }
+      const sessionId = req.headers["mcp-session-id"] || req.headers["Mcp-Session-Id"];
+      if (!sessionId) {
+        res.status(400).json({ error: "Missing Mcp-Session-Id header" });
+        return;
+      }
+      const transport = sessionManager.getTransport(sessionId);
+      if (!transport) {
+        res.status(400).json({ error: "Session not found" });
+        return;
+      }
+      await transport.handleRequest(req, res);
+    };
+    return { post, get, delete: del };
+  }
+};
+
+export { AuthorizationRequiredError, ConfigError, HttpError, IntegrationConnectionRequiredError, Kontext, KontextError, KontextTokenVerifier, NetworkError, OAuthError, createKontextClient, createKontextOrchestrator, isKontextError, isNetworkError, isUnauthorizedError, parseHttpError };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map