@mcp-ts/sdk 2.3.4 → 2.4.1

package/dist/{multi-session-client-C_kPHpD5.d.ts → multi-session-client-Bwm-efqg.d.ts}

@@ -1,4 +1,4 @@
-import { b as Event, M as McpConnectionEvent, d as McpObservabilityEvent, c as McpConnectionState } from './events-CK3N--3g.js';
+import { b as Event, M as McpConnectionEvent, d as McpObservabilityEvent, c as McpConnectionState } from './events-C4m7tK1U.js';
 import { ListToolsResult, CallToolResult, ListPromptsResult, GetPromptResult, ListResourcesResult, ReadResourceResult } from '@modelcontextprotocol/sdk/types.js';
 import { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
 import { OAuthClientMetadata, OAuthClientInformationMixed, OAuthClientInformationFull, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
@@ -18,8 +18,6 @@ interface AgentsOAuthProvider extends OAuthClientProvider {
     }>;
     consumeState(state: string): Promise<void>;
     deleteCodeVerifier(): Promise<void>;
-    isTokenExpired(): boolean;
-    setTokenExpiresAt(expiresAt: number): void;
 }
 interface StorageOAuthClientProviderOptions {
     userId: string;
@@ -51,7 +49,6 @@ declare class StorageOAuthClientProvider implements AgentsOAuthProvider {
     private _authUrl;
     private _clientId;
     private onRedirectCallback?;
-    private tokenExpiresAt?;
     /**
      * Creates a new session-backed OAuth provider
      * @param options - Provider configuration
@@ -61,17 +58,17 @@ declare class StorageOAuthClientProvider implements AgentsOAuthProvider {
     get clientId(): string | undefined;
     set clientId(clientId_: string | undefined);
     /**
-     * Loads OAuth data from the session store
+     * Loads OAuth credentials from the session store
      * @private
      */
-    private getSessionData;
+    private getCredentials;
     /**
-     * Saves OAuth data to the session store
-     * @param data - Partial OAuth data to save
+     * Saves OAuth credentials to the session store
+     * @param data - Partial OAuth credentials to save
      * @private
      * @throws Error if session doesn't exist (session must be created by controller layer)
      */
-    private saveSessionData;
+    private patchCredentials;
     /**
      * Retrieves stored OAuth client information
      */
@@ -86,20 +83,18 @@ declare class StorageOAuthClientProvider implements AgentsOAuthProvider {
     saveTokens(tokens: OAuthTokens): Promise<void>;
     get authUrl(): string | undefined;
     state(): Promise<string>;
-    checkState(_state: string): Promise<{
+    checkState(state: string): Promise<{
         valid: boolean;
         serverId?: string;
         error?: string;
     }>;
-    consumeState(_state: string): Promise<void>;
+    consumeState(state: string): Promise<void>;
     redirectToAuthorization(authUrl: URL): Promise<void>;
     invalidateCredentials(scope: "all" | "client" | "tokens" | "verifier"): Promise<void>;
     saveCodeVerifier(verifier: string): Promise<void>;
     codeVerifier(): Promise<string>;
     deleteCodeVerifier(): Promise<void>;
     tokens(): Promise<OAuthTokens | undefined>;
-    isTokenExpired(): boolean;
-    setTokenExpiresAt(expiresAt: number): void;
 }
 
 /**
@@ -198,11 +193,15 @@ declare class MCPClient {
     /**
      * Saves current session state to the session store
      * Creates new session if it doesn't exist, updates if it does
-     * @param ttl - Time-to-live in seconds (defaults to 12hr for connected sessions)
-     * @param active - Session status marker used to avoid unnecessary TTL rewrites
+     * @param status - Session lifecycle status used by storage cleanup
      * @private
      */
     private saveSession;
+    /**
+     * Removes transient setup/auth sessions without masking the original error.
+     * @private
+     */
+    private deleteTransientSession;
     /**
      * Try to connect using available transports
      * @returns The corrected transport type object if successful
@@ -223,7 +222,7 @@ declare class MCPClient {
      * Saves active session to Redis after successful authentication
      * @param authCode - Authorization code received from OAuth callback
      */
-    finishAuth(authCode: string): Promise<void>;
+    finishAuth(authCode: string, state?: string): Promise<void>;
     /**
      * Lists all available tools from the connected MCP server
      * @returns List of tools with their schemas and descriptions
@@ -283,10 +282,15 @@ declare class MCPClient {
      */
     isConnected(): boolean;
     /**
-     * Disconnects from the MCP server and cleans up resources
-     * Does not remove session from Redis - use clearSession() for that
+     * Disconnects from the MCP server and cleans up resources.
+     * Does not remove session from Redis — use clearSession() for that.
+     *
+     * For Streamable HTTP sessions, sends an HTTP DELETE to the MCP endpoint
+     * before closing, as recommended by the MCP Streamable HTTP spec
+     * (section "Session Management", rule 5). This is best-effort — errors
+     * (e.g. server already restarted, 404/405 responses) are silently ignored.
      */
-    disconnect(reason?: string): void;
+    disconnect(): Promise<void>;
     /**
      * Dispose of all event emitters
      * Call this when the client is no longer needed
@@ -322,19 +326,6 @@ declare class MCPClient {
      * @returns Session ID
      */
     getSessionId(): string;
-    /**
-     * Gets MCP server configuration for all active user sessions
-     * Loads sessions from storage and returns server connection metadata.
-     * OAuth refresh is handled by SDK transports through their authProvider.
-     * @deprecated This returns legacy connection metadata only and does not
-     * include OAuth tokens or generated Authorization headers. Prefer
-     * MultiSessionClient or explicit MCPClient instances so SDK transports can
-     * own OAuth refresh and reauthorization.
-     * @param userId - User ID to fetch sessions for
-     * @returns Object keyed by sanitized server labels containing transport and url.
-     * @static
-     */
-    static getMcpServerConfig(userId: string): Promise<Record<string, any>>;
 }
 
 /**
@@ -384,12 +375,8 @@ declare class MultiSessionClient {
      *
      * A session is considered connectable when:
      * - It has a `serverId`, `serverUrl`, and `callbackUrl` (i.e. it was fully initialized)
-     * - Its `active` flag is not explicitly `false` — sessions with `active: false` are
-     *   either mid-OAuth flow, auth-pending, or previously failed. We skip those here
+     * - Its status is `active`. Pending sessions are skipped here
      *   and let the OAuth flow complete separately before we try to reconnect them.
-     *
-     * Note: Sessions where `active` is `undefined` (legacy records) are included
-     * for backwards compatibility.
      */
     private getActiveSessions;
     /**
@@ -405,6 +392,9 @@ declare class MultiSessionClient {
      * Connects a single session, with built-in deduplication to prevent race conditions.
      *
      * - If a client for this session already exists and is connected, returns immediately.
+     * - If the existing client entry is no longer connected (e.g. it was explicitly
+     *   disconnected), it is evicted so that `establishConnectionWithRetries` creates a
+     *   fresh transport — preventing "Client already connected" errors from the SDK.
      * - If a connection attempt for this session is already in-flight (e.g. from a
      *   concurrent call), it joins the existing promise instead of starting a new one.
      *   This is the key concurrency lock — the `connectionPromises` map acts as a
@@ -436,6 +426,17 @@ declare class MultiSessionClient {
      * re-fetching and re-connecting on every request.
      */
     connect(): Promise<void>;
+    /**
+     * Drops all cached `MCPClient` instances and reconnects fresh from storage.
+     *
+     * Call this when downstream MCP servers have expired their transport sessions
+     * (e.g. after a remote server restart) and subsequent tool calls return
+     * "Session not found. Reconnect without session header." errors.
+     *
+     * OAuth tokens are preserved in the storage backend — no re-authentication
+     * is required. Only the in-memory transport sessions are cleared.
+     */
+    reconnect(): Promise<void>;
     /**
      * Returns all currently connected `MCPClient` instances.
      *
@@ -446,10 +447,14 @@ declare class MultiSessionClient {
     /**
      * Gracefully disconnects all active MCP clients and clears the internal client list.
      *
+     * For Streamable HTTP sessions, each client sends an HTTP DELETE to its MCP
+     * endpoint per the spec before closing locally. All disconnects run in
+     * parallel so shutdown is not serialised across many sessions.
+     *
      * Call this during server shutdown or when a user logs out to free up
      * underlying transport resources (SSE streams, HTTP connections, etc.).
      */
-    disconnect(): void;
+    disconnect(): Promise<void>;
 }
 
 export { MCPClient as M, StorageOAuthClientProvider as S, MultiSessionClient as a };

package/dist/{multi-session-client-C7hGqzgM.d.mts → multi-session-client-k-9RvWvi.d.mts}

@@ -1,4 +1,4 @@
-import { b as Event, M as McpConnectionEvent, d as McpObservabilityEvent, c as McpConnectionState } from './events-CK3N--3g.mjs';
+import { b as Event, M as McpConnectionEvent, d as McpObservabilityEvent, c as McpConnectionState } from './events-C4m7tK1U.mjs';
 import { ListToolsResult, CallToolResult, ListPromptsResult, GetPromptResult, ListResourcesResult, ReadResourceResult } from '@modelcontextprotocol/sdk/types.js';
 import { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
 import { OAuthClientMetadata, OAuthClientInformationMixed, OAuthClientInformationFull, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
@@ -18,8 +18,6 @@ interface AgentsOAuthProvider extends OAuthClientProvider {
     }>;
     consumeState(state: string): Promise<void>;
     deleteCodeVerifier(): Promise<void>;
-    isTokenExpired(): boolean;
-    setTokenExpiresAt(expiresAt: number): void;
 }
 interface StorageOAuthClientProviderOptions {
     userId: string;
@@ -51,7 +49,6 @@ declare class StorageOAuthClientProvider implements AgentsOAuthProvider {
     private _authUrl;
     private _clientId;
     private onRedirectCallback?;
-    private tokenExpiresAt?;
     /**
      * Creates a new session-backed OAuth provider
      * @param options - Provider configuration
@@ -61,17 +58,17 @@ declare class StorageOAuthClientProvider implements AgentsOAuthProvider {
     get clientId(): string | undefined;
     set clientId(clientId_: string | undefined);
     /**
-     * Loads OAuth data from the session store
+     * Loads OAuth credentials from the session store
      * @private
      */
-    private getSessionData;
+    private getCredentials;
     /**
-     * Saves OAuth data to the session store
-     * @param data - Partial OAuth data to save
+     * Saves OAuth credentials to the session store
+     * @param data - Partial OAuth credentials to save
      * @private
      * @throws Error if session doesn't exist (session must be created by controller layer)
      */
-    private saveSessionData;
+    private patchCredentials;
     /**
      * Retrieves stored OAuth client information
      */
@@ -86,20 +83,18 @@ declare class StorageOAuthClientProvider implements AgentsOAuthProvider {
     saveTokens(tokens: OAuthTokens): Promise<void>;
     get authUrl(): string | undefined;
     state(): Promise<string>;
-    checkState(_state: string): Promise<{
+    checkState(state: string): Promise<{
         valid: boolean;
         serverId?: string;
         error?: string;
     }>;
-    consumeState(_state: string): Promise<void>;
+    consumeState(state: string): Promise<void>;
     redirectToAuthorization(authUrl: URL): Promise<void>;
     invalidateCredentials(scope: "all" | "client" | "tokens" | "verifier"): Promise<void>;
     saveCodeVerifier(verifier: string): Promise<void>;
     codeVerifier(): Promise<string>;
     deleteCodeVerifier(): Promise<void>;
     tokens(): Promise<OAuthTokens | undefined>;
-    isTokenExpired(): boolean;
-    setTokenExpiresAt(expiresAt: number): void;
 }
 
 /**
@@ -198,11 +193,15 @@ declare class MCPClient {
     /**
      * Saves current session state to the session store
      * Creates new session if it doesn't exist, updates if it does
-     * @param ttl - Time-to-live in seconds (defaults to 12hr for connected sessions)
-     * @param active - Session status marker used to avoid unnecessary TTL rewrites
+     * @param status - Session lifecycle status used by storage cleanup
      * @private
      */
     private saveSession;
+    /**
+     * Removes transient setup/auth sessions without masking the original error.
+     * @private
+     */
+    private deleteTransientSession;
     /**
      * Try to connect using available transports
      * @returns The corrected transport type object if successful
@@ -223,7 +222,7 @@ declare class MCPClient {
      * Saves active session to Redis after successful authentication
      * @param authCode - Authorization code received from OAuth callback
      */
-    finishAuth(authCode: string): Promise<void>;
+    finishAuth(authCode: string, state?: string): Promise<void>;
     /**
      * Lists all available tools from the connected MCP server
      * @returns List of tools with their schemas and descriptions
@@ -283,10 +282,15 @@ declare class MCPClient {
      */
     isConnected(): boolean;
     /**
-     * Disconnects from the MCP server and cleans up resources
-     * Does not remove session from Redis - use clearSession() for that
+     * Disconnects from the MCP server and cleans up resources.
+     * Does not remove session from Redis — use clearSession() for that.
+     *
+     * For Streamable HTTP sessions, sends an HTTP DELETE to the MCP endpoint
+     * before closing, as recommended by the MCP Streamable HTTP spec
+     * (section "Session Management", rule 5). This is best-effort — errors
+     * (e.g. server already restarted, 404/405 responses) are silently ignored.
      */
-    disconnect(reason?: string): void;
+    disconnect(): Promise<void>;
     /**
      * Dispose of all event emitters
      * Call this when the client is no longer needed
@@ -322,19 +326,6 @@ declare class MCPClient {
      * @returns Session ID
      */
     getSessionId(): string;
-    /**
-     * Gets MCP server configuration for all active user sessions
-     * Loads sessions from storage and returns server connection metadata.
-     * OAuth refresh is handled by SDK transports through their authProvider.
-     * @deprecated This returns legacy connection metadata only and does not
-     * include OAuth tokens or generated Authorization headers. Prefer
-     * MultiSessionClient or explicit MCPClient instances so SDK transports can
-     * own OAuth refresh and reauthorization.
-     * @param userId - User ID to fetch sessions for
-     * @returns Object keyed by sanitized server labels containing transport and url.
-     * @static
-     */
-    static getMcpServerConfig(userId: string): Promise<Record<string, any>>;
 }
 
 /**
@@ -384,12 +375,8 @@ declare class MultiSessionClient {
      *
      * A session is considered connectable when:
      * - It has a `serverId`, `serverUrl`, and `callbackUrl` (i.e. it was fully initialized)
-     * - Its `active` flag is not explicitly `false` — sessions with `active: false` are
-     *   either mid-OAuth flow, auth-pending, or previously failed. We skip those here
+     * - Its status is `active`. Pending sessions are skipped here
      *   and let the OAuth flow complete separately before we try to reconnect them.
-     *
-     * Note: Sessions where `active` is `undefined` (legacy records) are included
-     * for backwards compatibility.
      */
     private getActiveSessions;
     /**
@@ -405,6 +392,9 @@ declare class MultiSessionClient {
      * Connects a single session, with built-in deduplication to prevent race conditions.
      *
      * - If a client for this session already exists and is connected, returns immediately.
+     * - If the existing client entry is no longer connected (e.g. it was explicitly
+     *   disconnected), it is evicted so that `establishConnectionWithRetries` creates a
+     *   fresh transport — preventing "Client already connected" errors from the SDK.
      * - If a connection attempt for this session is already in-flight (e.g. from a
      *   concurrent call), it joins the existing promise instead of starting a new one.
      *   This is the key concurrency lock — the `connectionPromises` map acts as a
@@ -436,6 +426,17 @@ declare class MultiSessionClient {
      * re-fetching and re-connecting on every request.
      */
     connect(): Promise<void>;
+    /**
+     * Drops all cached `MCPClient` instances and reconnects fresh from storage.
+     *
+     * Call this when downstream MCP servers have expired their transport sessions
+     * (e.g. after a remote server restart) and subsequent tool calls return
+     * "Session not found. Reconnect without session header." errors.
+     *
+     * OAuth tokens are preserved in the storage backend — no re-authentication
+     * is required. Only the in-memory transport sessions are cleared.
+     */
+    reconnect(): Promise<void>;
     /**
      * Returns all currently connected `MCPClient` instances.
      *
@@ -446,10 +447,14 @@ declare class MultiSessionClient {
     /**
      * Gracefully disconnects all active MCP clients and clears the internal client list.
      *
+     * For Streamable HTTP sessions, each client sends an HTTP DELETE to its MCP
+     * endpoint per the spec before closing locally. All disconnects run in
+     * parallel so shutdown is not serialised across many sessions.
+     *
      * Call this during server shutdown or when a user logs out to free up
      * underlying transport resources (SSE streams, HTTP connections, etc.).
      */
-    disconnect(): void;
+    disconnect(): Promise<void>;
 }
 
 export { MCPClient as M, StorageOAuthClientProvider as S, MultiSessionClient as a };

package/dist/server/index.d.mts

@@ -1,14 +1,21 @@
-export { M as MCPClient, a as MultiSessionClient, S as StorageOAuthClientProvider } from '../multi-session-client-C7hGqzgM.mjs';
+export { M as MCPClient, a as MultiSessionClient, S as StorageOAuthClientProvider } from '../multi-session-client-k-9RvWvi.mjs';
 export { U as UnauthorizedError, s as sanitizeServerLabel } from '../utils-DELRKQPU.mjs';
 import { OAuthClientInformationMixed, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
 export { OAuthClientInformation, OAuthClientInformationFull, OAuthClientMetadata, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
-import { M as McpConnectionEvent, d as McpObservabilityEvent } from '../events-CK3N--3g.mjs';
-export { D as Disposable, E as Emitter, b as Event, c as McpConnectionState } from '../events-CK3N--3g.mjs';
-import { r as McpRpcResponse, q as McpRpcRequest } from '../types-CxFaaZrM.mjs';
-export { a as CallToolRequest, b as CallToolResponse, f as ConnectRequest, g as ConnectResponse, n as ListToolsResponse, T as ToolClient, u as ToolClientProvider, v as ToolInfo } from '../types-CxFaaZrM.mjs';
+import { M as McpConnectionEvent, d as McpObservabilityEvent } from '../events-C4m7tK1U.mjs';
+export { D as Disposable, E as Emitter, b as Event, c as McpConnectionState } from '../events-C4m7tK1U.mjs';
+import { r as McpRpcResponse, q as McpRpcRequest } from '../types-DCk_IF4L.mjs';
+export { a as CallToolRequest, b as CallToolResponse, f as ConnectRequest, g as ConnectResponse, n as ListToolsResponse, T as ToolClient, u as ToolClientProvider, v as ToolInfo } from '../types-DCk_IF4L.mjs';
 export { CallToolResult, ListToolsResult, Tool } from '@modelcontextprotocol/sdk/types.js';
 import '@modelcontextprotocol/sdk/client/auth.js';
 
+interface OAuthState {
+    nonce: string;
+    sessionId: string;
+    serverId: string;
+    createdAt: number;
+}
+type SessionStatus = 'pending' | 'active';
 interface Session {
     sessionId: string;
     serverId?: string;
@@ -17,19 +24,30 @@ interface Session {
     transportType: 'sse' | 'streamable-http';
     callbackUrl: string;
     createdAt: number;
+    updatedAt?: number;
+    /**
+     * Storage-owned expiration timestamp for pending/inactive sessions.
+     * Active sessions use updatedAt-based dormancy cleanup instead.
+     */
+    expiresAt?: number | null;
     userId: string;
     headers?: Record<string, string>;
+    authUrl?: string | null;
     /**
-     * Session status marker used for TTL transitions:
-     * - false: short-lived intermediate/error/auth-pending session state
-     *          (keep this value when connection/auth is incomplete or failed)
-     * - true: active long-lived session state after successful connection/auth completion
+     * Session status marker used for lifecycle cleanup:
+     * - pending: short-lived intermediate/auth-pending session state
+     * - active: restorable session after successful connection/auth completion
      */
-    active?: boolean;
-    clientInformation?: OAuthClientInformationMixed;
-    tokens?: OAuthTokens;
-    codeVerifier?: string;
-    clientId?: string;
+    status?: SessionStatus;
+}
+interface SessionCredentials {
+    sessionId: string;
+    userId: string;
+    clientInformation?: OAuthClientInformationMixed | null;
+    tokens?: OAuthTokens | null;
+    codeVerifier?: string | null;
+    clientId?: string | null;
+    oauthState?: OAuthState | null;
 }
 type SessionMutationType = 'create' | 'update' | 'delete';
 interface SessionMutationEvent {
@@ -39,7 +57,6 @@ interface SessionMutationEvent {
     timestamp: number;
     session?: Session;
     patch?: Partial<Session>;
-    ttl?: number;
 }
 type SessionMutationListener = (event: SessionMutationEvent) => void | Promise<void>;
 /**
@@ -57,21 +74,32 @@ interface SessionStore {
     /**
      * Creates a new session. Throws if session already exists.
      * @param session - Session data to create
-     * @param ttl - Optional TTL in seconds (defaults to backend's default)
      */
-    create(session: Session, ttl?: number): Promise<void>;
+    create(session: Session): Promise<void>;
     /**
      * Updates an existing session with partial data. Throws if session does not exist.
      * @param userId - User identifier
      * @param sessionId - Session identifier
      * @param data - Partial session data to update
-     * @param ttl - Optional TTL in seconds (defaults to backend's default)
      */
-    update(userId: string, sessionId: string, data: Partial<Session>, ttl?: number): Promise<void>;
+    update(userId: string, sessionId: string, data: Partial<Session>): Promise<void>;
+    /**
+     * Patches runtime credentials for an existing session.
+     * These values are separated from connection metadata in durable SQL stores.
+     */
+    patchCredentials(userId: string, sessionId: string, data: Partial<SessionCredentials>): Promise<void>;
     /**
      * Retrieves a session
      */
     get(userId: string, sessionId: string): Promise<Session | null>;
+    /**
+     * Retrieves runtime credentials for a session.
+     */
+    getCredentials(userId: string, sessionId: string): Promise<SessionCredentials | null>;
+    /**
+     * Clears runtime credentials without removing connection metadata.
+     */
+    clearCredentials(userId: string, sessionId: string): Promise<void>;
     /**
      * Gets full session data for all sessions owned by a user
      */
@@ -221,7 +249,7 @@ declare class SSEConnectionManager {
     /**
      * Cleanup and close all connections
      */
-    dispose(): void;
+    dispose(): Promise<void>;
 }
 /**
  * Create an SSE endpoint handler compatible with Node.js HTTP frameworks.

package/dist/server/index.d.ts

@@ -1,14 +1,21 @@
-export { M as MCPClient, a as MultiSessionClient, S as StorageOAuthClientProvider } from '../multi-session-client-C_kPHpD5.js';
+export { M as MCPClient, a as MultiSessionClient, S as StorageOAuthClientProvider } from '../multi-session-client-Bwm-efqg.js';
 export { U as UnauthorizedError, s as sanitizeServerLabel } from '../utils-DELRKQPU.js';
 import { OAuthClientInformationMixed, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
 export { OAuthClientInformation, OAuthClientInformationFull, OAuthClientMetadata, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
-import { M as McpConnectionEvent, d as McpObservabilityEvent } from '../events-CK3N--3g.js';
-export { D as Disposable, E as Emitter, b as Event, c as McpConnectionState } from '../events-CK3N--3g.js';
-import { r as McpRpcResponse, q as McpRpcRequest } from '../types-CxFaaZrM.js';
-export { a as CallToolRequest, b as CallToolResponse, f as ConnectRequest, g as ConnectResponse, n as ListToolsResponse, T as ToolClient, u as ToolClientProvider, v as ToolInfo } from '../types-CxFaaZrM.js';
+import { M as McpConnectionEvent, d as McpObservabilityEvent } from '../events-C4m7tK1U.js';
+export { D as Disposable, E as Emitter, b as Event, c as McpConnectionState } from '../events-C4m7tK1U.js';
+import { r as McpRpcResponse, q as McpRpcRequest } from '../types-DCk_IF4L.js';
+export { a as CallToolRequest, b as CallToolResponse, f as ConnectRequest, g as ConnectResponse, n as ListToolsResponse, T as ToolClient, u as ToolClientProvider, v as ToolInfo } from '../types-DCk_IF4L.js';
 export { CallToolResult, ListToolsResult, Tool } from '@modelcontextprotocol/sdk/types.js';
 import '@modelcontextprotocol/sdk/client/auth.js';
 
+interface OAuthState {
+    nonce: string;
+    sessionId: string;
+    serverId: string;
+    createdAt: number;
+}
+type SessionStatus = 'pending' | 'active';
 interface Session {
     sessionId: string;
     serverId?: string;
@@ -17,19 +24,30 @@ interface Session {
     transportType: 'sse' | 'streamable-http';
     callbackUrl: string;
     createdAt: number;
+    updatedAt?: number;
+    /**
+     * Storage-owned expiration timestamp for pending/inactive sessions.
+     * Active sessions use updatedAt-based dormancy cleanup instead.
+     */
+    expiresAt?: number | null;
     userId: string;
     headers?: Record<string, string>;
+    authUrl?: string | null;
     /**
-     * Session status marker used for TTL transitions:
-     * - false: short-lived intermediate/error/auth-pending session state
-     *          (keep this value when connection/auth is incomplete or failed)
-     * - true: active long-lived session state after successful connection/auth completion
+     * Session status marker used for lifecycle cleanup:
+     * - pending: short-lived intermediate/auth-pending session state
+     * - active: restorable session after successful connection/auth completion
      */
-    active?: boolean;
-    clientInformation?: OAuthClientInformationMixed;
-    tokens?: OAuthTokens;
-    codeVerifier?: string;
-    clientId?: string;
+    status?: SessionStatus;
+}
+interface SessionCredentials {
+    sessionId: string;
+    userId: string;
+    clientInformation?: OAuthClientInformationMixed | null;
+    tokens?: OAuthTokens | null;
+    codeVerifier?: string | null;
+    clientId?: string | null;
+    oauthState?: OAuthState | null;
 }
 type SessionMutationType = 'create' | 'update' | 'delete';
 interface SessionMutationEvent {
@@ -39,7 +57,6 @@ interface SessionMutationEvent {
     timestamp: number;
     session?: Session;
     patch?: Partial<Session>;
-    ttl?: number;
 }
 type SessionMutationListener = (event: SessionMutationEvent) => void | Promise<void>;
 /**
@@ -57,21 +74,32 @@ interface SessionStore {
     /**
      * Creates a new session. Throws if session already exists.
      * @param session - Session data to create
-     * @param ttl - Optional TTL in seconds (defaults to backend's default)
      */
-    create(session: Session, ttl?: number): Promise<void>;
+    create(session: Session): Promise<void>;
     /**
      * Updates an existing session with partial data. Throws if session does not exist.
      * @param userId - User identifier
      * @param sessionId - Session identifier
      * @param data - Partial session data to update
-     * @param ttl - Optional TTL in seconds (defaults to backend's default)
      */
-    update(userId: string, sessionId: string, data: Partial<Session>, ttl?: number): Promise<void>;
+    update(userId: string, sessionId: string, data: Partial<Session>): Promise<void>;
+    /**
+     * Patches runtime credentials for an existing session.
+     * These values are separated from connection metadata in durable SQL stores.
+     */
+    patchCredentials(userId: string, sessionId: string, data: Partial<SessionCredentials>): Promise<void>;
     /**
      * Retrieves a session
      */
     get(userId: string, sessionId: string): Promise<Session | null>;
+    /**
+     * Retrieves runtime credentials for a session.
+     */
+    getCredentials(userId: string, sessionId: string): Promise<SessionCredentials | null>;
+    /**
+     * Clears runtime credentials without removing connection metadata.
+     */
+    clearCredentials(userId: string, sessionId: string): Promise<void>;
     /**
      * Gets full session data for all sessions owned by a user
      */
@@ -221,7 +249,7 @@ declare class SSEConnectionManager {
     /**
      * Cleanup and close all connections
      */
-    dispose(): void;
+    dispose(): Promise<void>;
 }
 /**
  * Create an SSE endpoint handler compatible with Node.js HTTP frameworks.