@kontext-dev/js-sdk 0.1.0

package/dist/client/index.js

@@ -0,0 +1,2412 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { UrlElicitationRequiredError, ElicitRequestSchema, ElicitationCompleteNotificationSchema } from '@modelcontextprotocol/sdk/types.js';
+import { randomBytes } from 'crypto';
+
+// 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";
+  }
+};
+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;
+}
+
+// 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);
+}
+
+export { createKontextClient, createSingleEndpointKontextClient };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map