@loop_ouroboros/mcp-hub-lite 1.0.0

package/dist/server/src/utils/mcp-error-handler.js

@@ -0,0 +1,270 @@
+/**
+ * Type guard function to check if an unknown error object is a CMDError.
+ * Validates that the object has the required properties of a CMDError.
+ *
+ * @param error - The error object to validate
+ * @returns True if the error is a CMDError, false otherwise
+ */
+function isCMDError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        'message' in error &&
+        'data' in error &&
+        typeof error.code === 'number' &&
+        typeof error.message === 'string');
+}
+/**
+ * MCP Hub Lite's error code mapping from internal gateway error codes
+ * to standard MCP protocol error codes. This mapping ensures compliance
+ * with the MCP specification while maintaining internal error categorization.
+ *
+ * The mapping follows these conventions:
+ * - 6001: Gateway internal error → Service unavailable (-32001)
+ * - 6002: Connection timeout → Request timeout (-32002)
+ * - 6003: Tool not found → MCP tool not found (-32801)
+ * - 6004: Tool execution failed → MCP execution failed (-32802)
+ * - 6005: Initialization failed → MCP initialization failed (-32803)
+ */
+export const MCPHubLiteErrorMap = {
+    // Map gateway internal errors to standard MCP error codes
+    6001: -32001, // Gateway internal error -> Service unavailable
+    6002: -32002, // Connection timeout -> Request timeout
+    6003: -32801, // Tool not found -> MCP tool not found
+    6004: -32802, // Tool execution failed -> MCP execution failed
+    6005: -32803 // Initialization failed -> MCP initialization failed
+};
+/**
+ * MCPErrorHandler provides standardized error handling and conversion for the MCP Hub Lite system.
+ * This class is responsible for converting internal application errors (both native JavaScript Error
+ * objects and custom CMDError objects) into standardized MCP protocol error responses that comply
+ * with the Model Context Protocol specification.
+ *
+ * The handler ensures consistent error formatting across the entire system, providing appropriate
+ * error codes, messages, and extended metadata that clients can use for proper error handling
+ * and user feedback. It supports both generic JavaScript errors and structured CMDError objects
+ * with categorized error codes.
+ *
+ * Usage scenarios include:
+ * - Converting backend server errors to MCP-compliant responses
+ * - Standardizing error responses from different MCP server implementations
+ * - Providing consistent error metadata for client-side error handling
+ * - Maintaining compatibility with the MCP protocol specification
+ */
+export class MCPErrorHandler {
+    /**
+     * Converts internal errors to standardized MCP error responses.
+     * This method handles both native JavaScript Error objects and custom CMDError objects,
+     * mapping them to appropriate MCP error codes and formatting them according to the
+     * MCP protocol specification.
+     *
+     * For native Error objects, it creates a standard MCP error with service unavailable
+     * code (-32001) and includes debugging information like stack trace and error name.
+     * For CMDError objects, it maps the internal error code ranges to appropriate MCP
+     * standard error codes based on error categories (system, security, business, etc.).
+     *
+     * @param error - The error to convert, either a native Error or CMDError object
+     * @returns A standardized MCPError object compliant with the MCP protocol
+     *
+     * @example
+     * ```typescript
+     * // Converting a native Error
+     * const mcpError = MCPErrorHandler.toMCPError(new Error('Connection failed'));
+     *
+     * // Converting a CMDError
+     * const cmdError: CMDError = { code: 6003, message: 'Tool not found', data: {} };
+     * const mcpError = MCPErrorHandler.toMCPError(cmdError);
+     * ```
+     */
+    static toMCPError(error) {
+        if (error instanceof Error) {
+            // Generic error mapping to standard MCP error
+            return {
+                code: -32001, // Default to service unavailable
+                message: error.message,
+                data: {
+                    originalError: error.message,
+                    timestamp: new Date().toISOString()
+                },
+                'x-mcp': {
+                    details: {
+                        stack: error.stack,
+                        name: error.name
+                    },
+                    suggestedActions: ['Check server status', 'Retry request']
+                }
+            };
+        }
+        else if (isCMDError(error)) {
+            // Map CMD errors to MCP errors
+            const mcpCode = this.mapCMDToMCPErrorCode(error.code);
+            return {
+                code: mcpCode,
+                message: error.message,
+                data: error.data,
+                'x-mcp': {
+                    details: error.error?.context,
+                    suggestedActions: ['Refer to error details', 'Retry or contact administrator']
+                }
+            };
+        }
+        // Default MCP error
+        return {
+            code: -32001,
+            message: 'Unknown error',
+            'x-mcp': {
+                suggestedActions: ['Retry request']
+            }
+        };
+    }
+    /**
+     * Maps internal CMD error codes to standardized MCP error codes.
+     * This private method implements the core logic for converting categorized
+     * internal error codes to appropriate MCP standard error codes based on
+     * error type ranges:
+     *
+     * - 1000-1999: System errors → Service unavailable (-32001)
+     * - 2000-2999: Security errors → Authentication/Authorization failed (-32806/-32807)
+     * - 3000-3999: Business errors → Invalid parameter (-32602)
+     * - 5000-5999: MCP protocol errors → Direct mapping or service unavailable
+     * - 6000-6999: Gateway-specific errors → Specific MCP error codes via switch
+     *
+     * The mapping ensures that internal error categorization is preserved while
+     * maintaining compliance with the external MCP protocol standard.
+     *
+     * @param cmdCode - The internal CMD error code to map
+     * @returns The corresponding standardized MCP error code
+     *
+     * @private
+     */
+    static mapCMDToMCPErrorCode(cmdCode) {
+        // System error mapping
+        if (cmdCode >= 1000 && cmdCode <= 1999) {
+            return -32001; // Service unavailable
+        }
+        // Security error mapping
+        if (cmdCode >= 2000 && cmdCode <= 2999) {
+            return -32806; // Authentication failed or -32807 Authorization failed
+        }
+        // Business error mapping
+        if (cmdCode >= 3000 && cmdCode <= 3999) {
+            return -32602; // Invalid parameter (typically used for business validation errors)
+        }
+        // MCP protocol errors, use standard codes directly
+        if (cmdCode >= 5000 && cmdCode <= 5999) {
+            // If it's a standard MCP error code, return directly
+            if (cmdCode >= 5800 && cmdCode <= 5815) {
+                // Corresponds to -328xx range
+                return -(32900 - (cmdCode - 5800));
+            }
+            return -32001; // Default
+        }
+        // Gateway-specific error code mapping
+        if (cmdCode >= 6000 && cmdCode <= 6999) {
+            switch (cmdCode) {
+                case 6001:
+                    return -32001; // Service unavailable
+                case 6002:
+                    return -32002; // Request timeout
+                case 6003:
+                    return -32801; // Tool not found
+                case 6004:
+                    return -32802; // Execution failed
+                default:
+                    return -32001;
+            }
+        }
+        return -32001; // Default MCP error code
+    }
+}
+/**
+ * MCPErrorsMiddleware provides middleware functionality for handling and normalizing
+ * error responses from backend MCP servers. This class acts as an intermediary layer
+ * that ensures all error responses conform to the standard MCP protocol format,
+ * regardless of how the backend server originally formatted its errors.
+ *
+ * The middleware intercepts JSON-RPC responses containing errors and validates
+ * whether they already comply with the MCP error standard. If they don't, it
+ * converts them using the MCPErrorHandler to ensure consistent error formatting
+ * across all connected MCP servers.
+ *
+ * This is particularly useful when integrating with various MCP server implementations
+ * that may have different error handling conventions, ensuring that clients receive
+ * standardized error responses regardless of the underlying server implementation.
+ */
+export class MCPErrorsMiddleware {
+    /**
+     * Handles and normalizes error responses from backend MCP servers.
+     * This method processes JSON-RPC responses and ensures that any error objects
+     * are converted to the standard MCP error format if they aren't already compliant.
+     *
+     * The method performs the following steps:
+     * 1. Checks if the response contains an error field
+     * 2. Validates if the error is already in standard MCP format
+     * 3. If not standard, converts the error to MCP format using MCPErrorHandler
+     * 4. Returns the normalized response with standardized error formatting
+     *
+     * Non-error responses are returned unchanged to maintain performance.
+     *
+     * @param response - The raw response from a backend MCP server
+     * @returns The response with standardized error formatting if applicable, otherwise the original response
+     *
+     * @example
+     * ```typescript
+     * // Handle a response with a non-standard error
+     * const rawResponse = { jsonrpc: '2.0', id: 1, error: new Error('Connection failed') };
+     * const normalizedResponse = MCPErrorsMiddleware.handleBackendMCPErrors(rawResponse);
+     * // normalizedResponse.error will be in standard MCP format
+     * ```
+     */
+    static handleBackendMCPErrors(response) {
+        if (typeof response === 'object' && response !== null && 'error' in response) {
+            const rpcResponse = response;
+            // If it's already in standard MCP error format, return directly
+            if (this.isStandardMCPError(rpcResponse.error)) {
+                return response;
+            }
+            // Ensure error is of type Error or CMDError
+            let errorToConvert;
+            if (rpcResponse.error instanceof Error) {
+                errorToConvert = rpcResponse.error;
+            }
+            else if (isCMDError(rpcResponse.error)) {
+                errorToConvert = rpcResponse.error;
+            }
+            else {
+                // If neither, create a generic error
+                errorToConvert = new Error(typeof rpcResponse.error === 'object' && rpcResponse.error !== null
+                    ? rpcResponse.error.message || 'Unknown error'
+                    : String(rpcResponse.error));
+            }
+            // Otherwise convert non-standard errors to standard format
+            return {
+                jsonrpc: '2.0',
+                error: MCPErrorHandler.toMCPError(errorToConvert),
+                id: rpcResponse.id
+            };
+        }
+        return response;
+    }
+    /**
+     * Type guard function to check if an error object conforms to the standard MCP error format.
+     * This private method validates that the error object has the required properties
+     * (code as number, message as string) and optional data property according to
+     * the MCP specification.
+     *
+     * @param error - The error object to validate
+     * @returns True if the error conforms to MCP standard format, false otherwise
+     *
+     * @private
+     */
+    static isStandardMCPError(error) {
+        return (typeof error === 'object' &&
+            error !== null &&
+            'code' in error &&
+            'message' in error &&
+            typeof error.code === 'number' &&
+            typeof error.message === 'string' &&
+            ('data' in error ? error.data !== undefined : true));
+    }
+}

package/dist/server/src/utils/port-checker.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Port occupancy checker utility
+ * Checks if a port is in use and attempts to identify the occupying process
+ */
+export interface PortCheckResult {
+    inUse: boolean;
+    pid?: number;
+    processName?: string;
+    commandLine?: string;
+    isSelfProject?: boolean;
+}
+/**
+ * Check if port is in use
+ */
+export declare function checkPort(port: number): Promise<PortCheckResult>;
+//# sourceMappingURL=port-checker.d.ts.map

package/dist/server/src/utils/port-checker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-checker.d.ts","sourceRoot":"","sources":["../../../../src/utils/port-checker.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAatE"}

package/dist/server/src/utils/port-checker.js

@@ -0,0 +1,242 @@
+/**
+ * Port occupancy checker utility
+ * Checks if a port is in use and attempts to identify the occupying process
+ */
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import { PidManager } from '../pid/manager.js';
+const execAsync = promisify(exec);
+/**
+ * Check if port is in use
+ */
+export async function checkPort(port) {
+    try {
+        const platform = process.platform;
+        if (platform === 'win32') {
+            return await checkPortWindows(port);
+        }
+        else {
+            return await checkPortUnix(port);
+        }
+    }
+    catch {
+        // Return not in use on check failure (safe default)
+        return { inUse: false };
+    }
+}
+/**
+ * Checks if a specific port is in use on Windows platform.
+ *
+ * This function uses the Windows `netstat` command to identify processes that are
+ * listening on the specified port. It parses the netstat output to extract the
+ * process ID (PID) and then retrieves detailed process information using WMIC.
+ *
+ * The function specifically looks for connections in the "LISTENING" state and
+ * matches the local address to ensure it's the exact port being checked.
+ *
+ * @param port - The port number to check for occupancy (e.g., 7788)
+ * @returns {Promise<PortCheckResult>} A promise that resolves to a PortCheckResult object
+ *          containing information about whether the port is in use, the PID of the
+ *          occupying process, process name, command line, and whether it's the current project
+ *
+ * @example
+ * ```typescript
+ * const result = await checkPortWindows(7788);
+ * if (result.inUse) {
+ *   console.log(`Port 7788 is used by PID ${result.pid} (${result.processName})`);
+ * }
+ * ```
+ */
+async function checkPortWindows(port) {
+    try {
+        // Use netstat to find the process occupying the port
+        const { stdout } = await execAsync(`netstat -ano | findstr :${port}`);
+        if (!stdout.trim()) {
+            return { inUse: false };
+        }
+        // Parse netstat output to extract PID
+        const lines = stdout.trim().split('\n');
+        for (const line of lines) {
+            const parts = line.trim().split(/\s+/);
+            const localAddress = parts[1];
+            const state = parts[3];
+            const pid = parseInt(parts[4], 10);
+            // Check if it's in LISTENING state and is the target port
+            if (state === 'LISTENING' && localAddress.endsWith(`:${port}`)) {
+                // Get process details
+                const processInfo = await getProcessInfoWindows(pid);
+                // Check if it's the current project's process
+                const isSelfProject = await isSelfProjectProcess(pid, processInfo.commandLine);
+                return {
+                    inUse: true,
+                    pid,
+                    processName: processInfo.processName,
+                    commandLine: processInfo.commandLine,
+                    isSelfProject
+                };
+            }
+        }
+        return { inUse: false };
+    }
+    catch {
+        return { inUse: false };
+    }
+}
+/**
+ * Checks if a specific port is in use on Unix platforms (Linux, macOS).
+ *
+ * This function uses the `lsof` (list open files) command to identify processes that are
+ * listening on the specified port. It filters for TCP connections in LISTEN state and
+ * extracts the process ID (PID) from the output.
+ *
+ * After identifying the PID, it retrieves detailed process information using the `ps` command
+ * to get the process name and full command line arguments.
+ *
+ * @param port - The port number to check for occupancy (e.g., 7788)
+ * @returns {Promise<PortCheckResult>} A promise that resolves to a PortCheckResult object
+ *          containing information about whether the port is in use, the PID of the
+ *          occupying process, process name, command line, and whether it's the current project
+ *
+ * @example
+ * ```typescript
+ * const result = await checkPortUnix(7788);
+ * if (result.inUse) {
+ *   console.log(`Port 7788 is used by PID ${result.pid} (${result.processName})`);
+ * }
+ * ```
+ */
+async function checkPortUnix(port) {
+    try {
+        // Use lsof to find the process occupying the port
+        const { stdout } = await execAsync(`lsof -i :${port} -sTCP:LISTEN -t`);
+        if (!stdout.trim()) {
+            return { inUse: false };
+        }
+        const pid = parseInt(stdout.trim().split('\n')[0], 10);
+        // Get process details
+        const processInfo = await getProcessInfoUnix(pid);
+        // Check if it's the current project's process
+        const isSelfProject = await isSelfProjectProcess(pid, processInfo.commandLine);
+        return {
+            inUse: true,
+            pid,
+            processName: processInfo.processName,
+            commandLine: processInfo.commandLine,
+            isSelfProject
+        };
+    }
+    catch {
+        return { inUse: false };
+    }
+}
+/**
+ * Retrieves detailed process information for a given PID on Windows.
+ *
+ * This function uses the Windows Management Instrumentation Command-line (WMIC) tool
+ * to query process details including the process name and full command line arguments.
+ * It parses the WMIC output to extract the relevant information and handles potential
+ * errors gracefully by returning default values.
+ *
+ * @param pid - The process ID to query for information
+ * @returns {Promise<{ processName: string; commandLine: string }>} A promise that resolves to an object
+ *          containing the process name and command line arguments, or default values if the query fails
+ *
+ * @example
+ * ```typescript
+ * const info = await getProcessInfoWindows(12345);
+ * console.log(`Process: ${info.processName}`);
+ * console.log(`Command: ${info.commandLine}`);
+ * ```
+ */
+async function getProcessInfoWindows(pid) {
+    try {
+        // Use wmic to get process details
+        const { stdout } = await execAsync(`wmic process where ProcessId=${pid} get Name,CommandLine /format:list`);
+        const lines = stdout.split('\n').filter((line) => line.trim());
+        let processName = 'Unknown';
+        let commandLine = '';
+        for (const line of lines) {
+            if (line.startsWith('CommandLine=')) {
+                commandLine = line.substring('CommandLine='.length).trim();
+            }
+            else if (line.startsWith('Name=')) {
+                processName = line.substring('Name='.length).trim();
+            }
+        }
+        return { processName, commandLine };
+    }
+    catch {
+        return { processName: 'Unknown', commandLine: '' };
+    }
+}
+/**
+ * Retrieves detailed process information for a given PID on Unix platforms (Linux, macOS).
+ *
+ * This function uses the `ps` (process status) command to query process details including
+ * the process name (comm) and full command line arguments (args). It parses the ps output
+ * to extract the relevant information and handles potential errors gracefully by returning
+ * default values.
+ *
+ * @param pid - The process ID to query for information
+ * @returns {Promise<{ processName: string; commandLine: string }>} A promise that resolves to an object
+ *          containing the process name and command line arguments, or default values if the query fails
+ *
+ * @example
+ * ```typescript
+ * const info = await getProcessInfoUnix(12345);
+ * console.log(`Process: ${info.processName}`);
+ * console.log(`Command: ${info.commandLine}`);
+ * ```
+ */
+async function getProcessInfoUnix(pid) {
+    try {
+        // Use ps to get process details
+        const { stdout } = await execAsync(`ps -p ${pid} -o comm=,args=`);
+        const parts = stdout.trim().split(/\s+/);
+        const processName = parts[0] || 'Unknown';
+        const commandLine = stdout.trim();
+        return { processName, commandLine };
+    }
+    catch {
+        return { processName: 'Unknown', commandLine: '' };
+    }
+}
+/**
+ * Determines whether a given process belongs to the current MCP Hub Lite project.
+ *
+ * This function performs two checks to identify if a process is part of the current project:
+ * 1. **PID File Check**: Compares the provided PID with the PID stored in the project's PID file
+ * 2. **Command Line Signature Check**: Searches for project-specific signatures in the command line
+ *
+ * The function uses a list of project signatures including the project name 'mcp-hub-lite',
+ * the compiled entry file path 'dist/server/src/index.js', and the source entry file 'src/index.ts'.
+ *
+ * @param pid - The process ID to check
+ * @param commandLine - The full command line used to start the process
+ * @returns {Promise<boolean>} A promise that resolves to true if the process belongs to the current project, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const isSelf = await isSelfProjectProcess(12345, 'node dist/server/src/index.js');
+ * if (isSelf) {
+ *   console.log('This is our project process');
+ * }
+ * ```
+ */
+async function isSelfProjectProcess(pid, commandLine) {
+    // Check 1: Check if the PID recorded in the PID file matches
+    const savedPid = PidManager.getPid();
+    if (savedPid === pid) {
+        return true;
+    }
+    // Check 2: Check if the command line contains project signatures
+    if (!commandLine) {
+        return false;
+    }
+    const projectSignatures = [
+        'mcp-hub-lite', // Project name
+        'dist/server/src/index.js', // Compiled entry file
+        'src/index.ts' // Source code entry file
+    ];
+    return projectSignatures.some((signature) => commandLine.includes(signature));
+}

package/dist/server/src/utils/request-context.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Request context management using AsyncLocalStorage for request-scoped data.
+ *
+ * This module provides a way to store and access request-specific context data
+ * across asynchronous operations without having to pass context objects through
+ * every function call. It uses Node.js AsyncLocalStorage to maintain context
+ * throughout the request lifecycle.
+ *
+ * The primary use case is storing client context information (sessionId, clientName,
+ * cwd, project, etc.) that needs to be accessible from any part of the application
+ * during request processing.
+ *
+ * @module utils/request-context
+ */
+import { AsyncLocalStorage } from 'async_hooks';
+import type { ClientContext } from '../../shared/types/client.types.js';
+/**
+ * AsyncLocalStorage instance for storing request context.
+ *
+ * This storage holds the ClientContext object for the current request and
+ * makes it available throughout the entire request processing chain,
+ * including asynchronous operations and nested function calls.
+ *
+ * @example
+ * ```typescript
+ * // In route handler
+ * await requestContext.run(clientContext, async () => {
+ *   // Any code executed here can access the client context
+ *   const ctx = getClientContext();
+ *   console.log(ctx.sessionId);
+ * });
+ * ```
+ */
+export declare const requestContext: AsyncLocalStorage<ClientContext>;
+/**
+ * Retrieves the current request's client context.
+ *
+ * This function returns the ClientContext object stored in the AsyncLocalStorage
+ * for the current request. It should only be called within a request context
+ * that has been established using requestContext.run().
+ *
+ * @returns {ClientContext | undefined} The current request's client context, or undefined if not in a request context
+ *
+ * @example
+ * ```typescript
+ * const context = getClientContext();
+ * if (context) {
+ *   console.log(`Processing request for session: ${context.sessionId}`);
+ * }
+ * ```
+ */
+export declare function getClientContext(): ClientContext | undefined;
+/**
+ * Retrieves the current request's working directory (cwd).
+ *
+ * This is a convenience function that extracts the cwd property from the
+ * current request's client context. It's commonly used in file operations
+ * that need to respect the client's current working directory.
+ *
+ * @returns {string | undefined} The current request's working directory, or undefined if not available
+ *
+ * @example
+ * ```typescript
+ * const cwd = getClientCwd();
+ * if (cwd) {
+ *   const fullPath = path.join(cwd, relativePath);
+ * }
+ * ```
+ */
+export declare function getClientCwd(): string | undefined;
+//# sourceMappingURL=request-context.d.ts.map

package/dist/server/src/utils/request-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-context.d.ts","sourceRoot":"","sources":["../../../../src/utils/request-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc,kCAAyC,CAAC;AAErE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,SAAS,CAE5D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,IAAI,MAAM,GAAG,SAAS,CAEjD"}

package/dist/server/src/utils/request-context.js

@@ -0,0 +1,73 @@
+/**
+ * Request context management using AsyncLocalStorage for request-scoped data.
+ *
+ * This module provides a way to store and access request-specific context data
+ * across asynchronous operations without having to pass context objects through
+ * every function call. It uses Node.js AsyncLocalStorage to maintain context
+ * throughout the request lifecycle.
+ *
+ * The primary use case is storing client context information (sessionId, clientName,
+ * cwd, project, etc.) that needs to be accessible from any part of the application
+ * during request processing.
+ *
+ * @module utils/request-context
+ */
+import { AsyncLocalStorage } from 'async_hooks';
+/**
+ * AsyncLocalStorage instance for storing request context.
+ *
+ * This storage holds the ClientContext object for the current request and
+ * makes it available throughout the entire request processing chain,
+ * including asynchronous operations and nested function calls.
+ *
+ * @example
+ * ```typescript
+ * // In route handler
+ * await requestContext.run(clientContext, async () => {
+ *   // Any code executed here can access the client context
+ *   const ctx = getClientContext();
+ *   console.log(ctx.sessionId);
+ * });
+ * ```
+ */
+export const requestContext = new AsyncLocalStorage();
+/**
+ * Retrieves the current request's client context.
+ *
+ * This function returns the ClientContext object stored in the AsyncLocalStorage
+ * for the current request. It should only be called within a request context
+ * that has been established using requestContext.run().
+ *
+ * @returns {ClientContext | undefined} The current request's client context, or undefined if not in a request context
+ *
+ * @example
+ * ```typescript
+ * const context = getClientContext();
+ * if (context) {
+ *   console.log(`Processing request for session: ${context.sessionId}`);
+ * }
+ * ```
+ */
+export function getClientContext() {
+    return requestContext.getStore();
+}
+/**
+ * Retrieves the current request's working directory (cwd).
+ *
+ * This is a convenience function that extracts the cwd property from the
+ * current request's client context. It's commonly used in file operations
+ * that need to respect the client's current working directory.
+ *
+ * @returns {string | undefined} The current request's working directory, or undefined if not available
+ *
+ * @example
+ * ```typescript
+ * const cwd = getClientCwd();
+ * if (cwd) {
+ *   const fullPath = path.join(cwd, relativePath);
+ * }
+ * ```
+ */
+export function getClientCwd() {
+    return requestContext.getStore()?.cwd;
+}