@cyanheads/mcp-ts-core 0.1.0-beta.12

package/dist/utils/internal/logger.js

@@ -0,0 +1,573 @@
+import pino from 'pino';
+import { config } from '../../config/index.js';
+import { requestContextService } from '../../utils/internal/requestContext.js';
+const mcpToPinoLevel = {
+    emerg: 'fatal',
+    alert: 'fatal',
+    crit: 'error',
+    error: 'error',
+    warning: 'warn',
+    notice: 'info',
+    info: 'info',
+    debug: 'debug',
+};
+const pinoToMcpLevelSeverity = {
+    fatal: 0,
+    error: 2,
+    warn: 4,
+    info: 6,
+    debug: 7,
+};
+const isServerless = typeof process === 'undefined' || process.env.IS_SERVERLESS === 'true';
+/** Pino redact paths for sensitive fields (top-level, one-deep, two-deep). */
+const SENSITIVE_PINO_FIELDS = [
+    'password',
+    'token',
+    'secret',
+    'apiKey',
+    'credential',
+    'jwt',
+    'ssn',
+    'cvv',
+    'authorization',
+    'cookie',
+    'clientsecret',
+    'client_secret',
+    'private_key',
+    'privatekey',
+].flatMap((field) => [field, `*.${field}`, `*.*.${field}`]);
+/**
+ * Singleton structured logger backed by Pino with RFC 5424 level semantics.
+ *
+ * Features:
+ * - Environment-adaptive output: pretty-printed (pino-pretty) in HTTP development mode,
+ *   JSON to stderr in stdio/production mode (MCP spec requires clean stdout).
+ * - Optional file sinks: `combined.log` at the configured log level, `error.log` for
+ *   errors and above, and `interactions.log` for structured interaction records.
+ * - Sensitive field redaction via Pino's `redact` option.
+ * - Per-message rate limiting to suppress log storms; suppressed counts are flushed
+ *   at the end of each rate-limit window.
+ * - OpenTelemetry trace context is auto-injected via {@link RequestContext} fields.
+ * - Serverless-safe: when `IS_SERVERLESS=true` or `process` is unavailable, falls
+ *   back to minimal Pino config without file transports or Node.js APIs.
+ *
+ * Obtain the singleton via {@link logger} or `Logger.getInstance()`.
+ */
+export class Logger {
+    static instance = new Logger();
+    pinoLogger;
+    interactionLogger;
+    initialized = false;
+    currentMcpLevel = 'info';
+    transportType;
+    rateLimitThreshold = 10;
+    rateLimitWindow = 60000;
+    messageCounts = new Map();
+    suppressedMessages = new Map();
+    cleanupTimer;
+    constructor() {
+        // The constructor is now safe to call in a global scope.
+    }
+    /**
+     * Returns the singleton `Logger` instance.
+     *
+     * Prefer importing the pre-resolved {@link logger} export rather than calling this directly.
+     *
+     * @returns The singleton `Logger` instance.
+     * @example
+     * ```ts
+     * import { Logger } from '../../utils/internal/logger.js';
+     * const log = Logger.getInstance();
+     * ```
+     */
+    static getInstance() {
+        return Logger.instance;
+    }
+    async createPinoLogger(level, transportType) {
+        const pinoLevel = mcpToPinoLevel[level] ?? 'info';
+        const pinoOptions = {
+            level: pinoLevel,
+            base: {
+                env: config.environment,
+                version: config.mcpServerVersion,
+                pid: !isServerless ? process.pid : undefined,
+            },
+            redact: {
+                paths: SENSITIVE_PINO_FIELDS,
+                censor: '[REDACTED]',
+            },
+        };
+        if (isServerless) {
+            return pino(pinoOptions);
+        }
+        // Node.js specific transports
+        const { default: fs } = await import('node:fs');
+        const { default: path } = await import('node:path');
+        const transports = [];
+        const isDevelopment = config.environment === 'development';
+        const isTest = config.environment === 'testing';
+        // CRITICAL: STDIO transport MUST NOT output colored logs to stdout.
+        // The MCP specification requires clean JSON-RPC on stdout with no ANSI codes.
+        // Only use pretty/colored output for HTTP mode or when explicitly debugging.
+        // Respect NO_COLOR environment variable (https://no-color.org/)
+        const noColorEnv = process.env.NO_COLOR === '1' || process.env.FORCE_COLOR === '0';
+        const useColoredOutput = isDevelopment && transportType !== 'stdio' && !noColorEnv;
+        if (useColoredOutput && !isServerless) {
+            // Try to resolve 'pino-pretty' robustly even when bundled (e.g., Bun/ESM),
+            // falling back to JSON stdout if resolution fails.
+            try {
+                const { createRequire } = await import('node:module');
+                const require = createRequire(import.meta.url);
+                const prettyTarget = require.resolve('pino-pretty');
+                transports.push({
+                    target: prettyTarget,
+                    options: { colorize: true, translateTime: 'yyyy-mm-dd HH:MM:ss' },
+                });
+            }
+            catch (err) {
+                // Only log to console if TTY to avoid polluting stderr in STDIO mode
+                if (process.stderr?.isTTY) {
+                    console.warn(`[Logger Init] Pretty transport unavailable (${err instanceof Error ? err.message : String(err)}); falling back to stdout JSON.`);
+                }
+                transports.push({ target: 'pino/file', options: { destination: 1 } });
+            }
+        }
+        else if (!isTest) {
+            // CRITICAL: For STDIO transport, logs MUST go to stderr (fd 2), NOT stdout (fd 1).
+            // The MCP specification requires only JSON-RPC messages on stdout.
+            // For HTTP transport or production, we also use stderr to avoid polluting stdout.
+            transports.push({ target: 'pino/file', options: { destination: 2 } });
+        }
+        if (config.logsPath) {
+            try {
+                if (!fs.existsSync(config.logsPath)) {
+                    fs.mkdirSync(config.logsPath, { recursive: true });
+                }
+                transports.push({
+                    level: pinoLevel,
+                    target: 'pino/file',
+                    options: {
+                        destination: path.join(config.logsPath, 'combined.log'),
+                        mkdir: true,
+                    },
+                });
+                transports.push({
+                    level: 'error',
+                    target: 'pino/file',
+                    options: {
+                        destination: path.join(config.logsPath, 'error.log'),
+                        mkdir: true,
+                    },
+                });
+            }
+            catch (err) {
+                // Only log to console if TTY to avoid polluting stderr in STDIO mode
+                if (process.stderr?.isTTY) {
+                    console.error(`[Logger Init] Failed to configure file logging: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
+        return pino({ ...pinoOptions, transport: { targets: transports } });
+    }
+    async createInteractionLogger() {
+        if (isServerless || !config.logsPath)
+            return;
+        const { default: path } = await import('node:path');
+        return pino({
+            redact: {
+                paths: SENSITIVE_PINO_FIELDS,
+                censor: '[REDACTED]',
+            },
+            transport: {
+                target: 'pino/file',
+                options: {
+                    destination: path.join(config.logsPath, 'interactions.log'),
+                    mkdir: true,
+                },
+            },
+        });
+    }
+    /**
+     * Initializes the logger, constructing Pino transports appropriate for the environment.
+     *
+     * Must be called once at server startup before any log methods are used. Subsequent calls
+     * are no-ops (a warning is emitted instead). After initialization, a startup `info` entry
+     * is written confirming the active level.
+     *
+     * @param level - MCP log level to apply. Defaults to `'info'`.
+     * @param transportType - Active transport (`'stdio'` or `'http'`). Determines whether
+     *   colored pretty-print output is enabled. In `'stdio'` mode, logs are always written
+     *   to stderr (fd 2) to preserve stdout for MCP JSON-RPC.
+     * @returns Promise that resolves when Pino transports and file sinks are ready.
+     * @example
+     * ```ts
+     * await logger.initialize('debug', 'http');
+     * ```
+     */
+    async initialize(level = 'info', transportType) {
+        if (this.initialized) {
+            this.warning('Logger already initialized.', requestContextService.createRequestContext({
+                operation: 'loggerReinit',
+            }));
+            return;
+        }
+        this.currentMcpLevel = level;
+        this.transportType = transportType;
+        this.pinoLogger = await this.createPinoLogger(level, transportType);
+        this.interactionLogger = await this.createInteractionLogger();
+        // Start the cleanup timer only after initialization and only in Node.js
+        if (!isServerless && !this.cleanupTimer) {
+            this.cleanupTimer = setInterval(() => this.flushSuppressedMessages(), this.rateLimitWindow);
+            this.cleanupTimer.unref?.();
+        }
+        this.initialized = true;
+        this.info(`Logger initialized. MCP level: ${level}.`, requestContextService.createRequestContext({ operation: 'loggerInit' }));
+    }
+    /**
+     * Changes the active log level at runtime without restarting transports.
+     *
+     * Has no effect if the logger has not been initialized; a console error is emitted
+     * to stderr when running in a TTY. After the level is updated, an `info` entry is
+     * written to confirm the change.
+     *
+     * @param newLevel - The new MCP log level to apply.
+     * @example
+     * ```ts
+     * logger.setLevel('debug');
+     * ```
+     */
+    setLevel(newLevel) {
+        if (!this.pinoLogger || !this.initialized) {
+            // Only log to console if TTY to avoid polluting stderr in STDIO mode
+            if (process.stderr?.isTTY) {
+                console.error('Cannot set level: Logger not initialized.');
+            }
+            return;
+        }
+        this.currentMcpLevel = newLevel;
+        this.pinoLogger.level = mcpToPinoLevel[newLevel] ?? 'info';
+        this.info(`Log level changed to ${newLevel}.`, requestContextService.createRequestContext({
+            operation: 'loggerSetLevel',
+        }));
+    }
+    /**
+     * Implements the `AsyncDisposable` protocol (`await using logger`).
+     *
+     * Delegates to {@link close}. Allows the logger to be used with `await using` in
+     * TypeScript 5.2+ explicit resource management contexts.
+     *
+     * @returns Promise that resolves when all transports have been flushed and closed.
+     */
+    async [Symbol.asyncDispose]() {
+        return await this.close();
+    }
+    /**
+     * Flushes all pending log entries and shuts down transports gracefully.
+     *
+     * Clears the rate-limit cleanup timer, flushes any suppressed message counts,
+     * and waits for both the main Pino logger and the interaction logger to drain
+     * before resolving. Safe to call multiple times — subsequent calls on an
+     * already-closed logger resolve immediately.
+     *
+     * @returns Promise that resolves when all writes have completed.
+     * @example
+     * ```ts
+     * process.on('SIGTERM', () => logger.close());
+     * ```
+     */
+    async close() {
+        if (!this.initialized)
+            return Promise.resolve();
+        this.info('Logger shutting down.', requestContextService.createRequestContext({ operation: 'loggerClose' }));
+        if (this.cleanupTimer)
+            clearInterval(this.cleanupTimer);
+        this.flushSuppressedMessages();
+        // Wait for all pending writes to complete
+        const flushPino = (pinoInstance, label) => {
+            const { promise, resolve } = Promise.withResolvers();
+            if (pinoInstance != null) {
+                pinoInstance.flush((err) => {
+                    // Only log to console if TTY AND not in STDIO mode
+                    // In STDIO mode, stdout is reserved for MCP JSON-RPC, so avoid polluting stderr with shutdown noise
+                    if (err && process.stderr?.isTTY && this.transportType !== 'stdio') {
+                        console.error(`Error flushing ${label}:`, err);
+                    }
+                    resolve();
+                });
+            }
+            else {
+                resolve();
+            }
+            return promise;
+        };
+        await Promise.all([
+            flushPino(this.pinoLogger, 'main logger'),
+            flushPino(this.interactionLogger, 'interaction logger'),
+        ]);
+        this.initialized = false;
+    }
+    /**
+     * Returns whether the logger has been successfully initialized.
+     *
+     * Use this to guard code that should only run after {@link initialize} has resolved,
+     * or to skip logging in contexts where initialization may not have occurred.
+     *
+     * @returns `true` if {@link initialize} has completed and {@link close} has not yet been called.
+     * @example
+     * ```ts
+     * if (logger.isInitialized()) {
+     *   logger.info('Server ready', ctx);
+     * }
+     * ```
+     */
+    isInitialized() {
+        return this.initialized;
+    }
+    isRateLimited(message) {
+        const now = Date.now();
+        const entry = this.messageCounts.get(message);
+        if (!entry) {
+            this.messageCounts.set(message, { count: 1, firstSeen: now });
+            return false;
+        }
+        if (now - entry.firstSeen > this.rateLimitWindow) {
+            this.messageCounts.set(message, { count: 1, firstSeen: now });
+            return false;
+        }
+        entry.count++;
+        if (entry.count > this.rateLimitThreshold) {
+            this.suppressedMessages.set(message, (this.suppressedMessages.get(message) || 0) + 1);
+            return true;
+        }
+        return false;
+    }
+    flushSuppressedMessages() {
+        if (this.suppressedMessages.size === 0)
+            return;
+        for (const [message, count] of this.suppressedMessages.entries()) {
+            this.warning(`Log message suppressed ${count} times due to rate limiting.`, requestContextService.createRequestContext({
+                operation: 'loggerRateLimitFlush',
+                additionalContext: { originalMessage: message },
+            }));
+        }
+        this.suppressedMessages.clear();
+        this.messageCounts.clear();
+    }
+    log(level, msg, context, error) {
+        if (!this.pinoLogger || !this.initialized)
+            return;
+        const pinoLevel = mcpToPinoLevel[level] ?? 'info';
+        const currentPinoLevel = mcpToPinoLevel[this.currentMcpLevel] ?? 'info';
+        const levelSeverity = pinoToMcpLevelSeverity[pinoLevel];
+        const currentLevelSeverity = pinoToMcpLevelSeverity[currentPinoLevel];
+        if (typeof levelSeverity === 'number' &&
+            typeof currentLevelSeverity === 'number' &&
+            levelSeverity > currentLevelSeverity) {
+            return;
+        }
+        if (this.isRateLimited(msg))
+            return;
+        const logObject = { ...context };
+        if (error)
+            logObject.err = pino.stdSerializers.err(error);
+        this.pinoLogger[pinoLevel](logObject, msg);
+    }
+    logWithError(level, msg, errorOrContext, context) {
+        const errorObj = errorOrContext instanceof Error ? errorOrContext : undefined;
+        const actualContext = errorOrContext instanceof Error ? context : errorOrContext;
+        this.log(level, msg, actualContext, errorObj);
+    }
+    /**
+     * Logs a diagnostic message at `debug` severity (RFC 5424 level 7).
+     *
+     * Suppressed unless the active log level is `'debug'`. Use for verbose tracing,
+     * internal state dumps, and low-level request/response details.
+     *
+     * @param msg - Human-readable log message.
+     * @param context - Optional request context providing `requestId`, `traceId`, and related fields.
+     * @example
+     * ```ts
+     * logger.debug('Cache miss', ctx);
+     * ```
+     */
+    debug(msg, context) {
+        this.log('debug', msg, context);
+    }
+    /**
+     * Logs an informational message at `info` severity (RFC 5424 level 6).
+     *
+     * Use for normal operational events: server startup, request completions, configuration loaded.
+     *
+     * @param msg - Human-readable log message.
+     * @param context - Optional request context.
+     * @example
+     * ```ts
+     * logger.info('Server listening on :3000', ctx);
+     * ```
+     */
+    info(msg, context) {
+        this.log('info', msg, context);
+    }
+    /**
+     * Logs a notice-level message at `notice` severity (RFC 5424 level 5).
+     *
+     * Use for significant but non-error conditions: configuration changes, deprecation notices,
+     * expected state transitions worth tracking. Maps to pino `info` level internally.
+     *
+     * @param msg - Human-readable log message.
+     * @param context - Optional request context.
+     * @example
+     * ```ts
+     * logger.notice('Feature flag toggled', ctx);
+     * ```
+     */
+    notice(msg, context) {
+        this.log('notice', msg, context);
+    }
+    /**
+     * Logs a warning message at `warning` severity (RFC 5424 level 4).
+     *
+     * Use for recoverable abnormal conditions: deprecated API usage, retried operations,
+     * non-fatal misconfigurations. Maps to pino `warn` level internally.
+     *
+     * @param msg - Human-readable log message.
+     * @param context - Optional request context.
+     * @example
+     * ```ts
+     * logger.warning('Rate limit approaching', ctx);
+     * ```
+     */
+    warning(msg, context) {
+        this.log('warning', msg, context);
+    }
+    /**
+     * Logs an error-level message at `error` severity (RFC 5424 level 3).
+     *
+     * Use when an operation fails but the server can continue. The `errorOrContext`
+     * parameter accepts either an `Error` (serialized via `pino.stdSerializers.err`) or a
+     * `RequestContext` when no error object is available. Maps to pino `error` level.
+     *
+     * @param msg - Human-readable description of the failure.
+     * @param errorOrContext - The `Error` to serialize, or a `RequestContext` if no error object exists.
+     * @param context - Request context; required when `errorOrContext` is an `Error`.
+     * @example
+     * ```ts
+     * logger.error('Failed to fetch resource', err, ctx);
+     * logger.error('Invalid state encountered', ctx);
+     * ```
+     */
+    error(msg, errorOrContext, context) {
+        this.logWithError('error', msg, errorOrContext, context);
+    }
+    /**
+     * Logs a critical error at `crit` severity (RFC 5424 level 2).
+     *
+     * Use for serious failures that impair a subsystem but do not crash the process —
+     * for example, a storage provider going offline. Maps to pino `error` level.
+     *
+     * @param msg - Human-readable description of the critical condition.
+     * @param errorOrContext - The `Error` to serialize, or a `RequestContext` if no error object exists.
+     * @param context - Request context; required when `errorOrContext` is an `Error`.
+     * @example
+     * ```ts
+     * logger.crit('Database connection pool exhausted', err, ctx);
+     * ```
+     */
+    crit(msg, errorOrContext, context) {
+        this.logWithError('crit', msg, errorOrContext, context);
+    }
+    /**
+     * Logs an alert-level message at `alert` severity (RFC 5424 level 1).
+     *
+     * Use when immediate human intervention is required — for example, a security breach
+     * detected or critical data loss imminent. Maps to pino `fatal` level.
+     *
+     * @param msg - Human-readable description of the alert condition.
+     * @param errorOrContext - The `Error` to serialize, or a `RequestContext` if no error object exists.
+     * @param context - Request context; required when `errorOrContext` is an `Error`.
+     * @example
+     * ```ts
+     * logger.alert('Unauthorized admin access detected', err, ctx);
+     * ```
+     */
+    alert(msg, errorOrContext, context) {
+        this.logWithError('alert', msg, errorOrContext, context);
+    }
+    /**
+     * Logs an emergency-level message at `emerg` severity (RFC 5424 level 0).
+     *
+     * Use for conditions that render the system completely unusable — process about to exit,
+     * unrecoverable internal state. Maps to pino `fatal` level.
+     *
+     * @param msg - Human-readable description of the emergency.
+     * @param errorOrContext - The `Error` to serialize, or a `RequestContext` if no error object exists.
+     * @param context - Request context; required when `errorOrContext` is an `Error`.
+     * @example
+     * ```ts
+     * logger.emerg('Unrecoverable state — shutting down', err, ctx);
+     * ```
+     */
+    emerg(msg, errorOrContext, context) {
+        this.logWithError('emerg', msg, errorOrContext, context);
+    }
+    /**
+     * Alias for {@link emerg}. Provided for callers familiar with the pino/winston `fatal` level.
+     *
+     * Maps to RFC 5424 `emerg` (level 0) and pino `fatal` internally.
+     *
+     * @param msg - Human-readable description of the fatal condition.
+     * @param errorOrContext - The `Error` to serialize, or a `RequestContext` if no error object exists.
+     * @param context - Request context; required when `errorOrContext` is an `Error`.
+     * @example
+     * ```ts
+     * logger.fatal('Process terminating due to unhandled exception', err, ctx);
+     * ```
+     */
+    fatal(msg, errorOrContext, context) {
+        this.emerg(msg, errorOrContext, context);
+    }
+    /**
+     * Writes a structured interaction record to the dedicated `interactions.log` file sink.
+     *
+     * Interaction logs capture high-level semantic events (tool invocations, resource reads,
+     * prompt renders) as structured JSON, separate from the main operational log stream.
+     * This sink is only available when `config.logsPath` is set and the runtime is not serverless;
+     * a `warning` is emitted if the logger is called before the sink is ready.
+     *
+     * @param interactionName - Identifier for the interaction type (e.g., `'tool:my_tool'`).
+     * @param data - Arbitrary structured data to include alongside `interactionName` in the log record.
+     * @example
+     * ```ts
+     * logger.logInteraction('tool:echo_message', { requestId: ctx.requestId, input });
+     * ```
+     */
+    logInteraction(interactionName, data) {
+        if (!this.interactionLogger) {
+            if (!isServerless)
+                this.warning('Interaction logger not available.', (data.context || {}));
+            return;
+        }
+        this.interactionLogger.info({ interactionName, ...data });
+    }
+}
+/**
+ * Pre-resolved singleton logger instance. Import this directly rather than calling
+ * `Logger.getInstance()` in most contexts.
+ *
+ * Must be initialized once at startup via `logger.initialize()` before any log methods
+ * will produce output. Log calls made before initialization are silently dropped.
+ *
+ * @example
+ * ```ts
+ * import { logger } from '../../utils/internal/logger.js';
+ *
+ * // At startup:
+ * await logger.initialize('debug', 'http');
+ *
+ * // In application code:
+ * logger.info('Request received', ctx);
+ * logger.error('Upstream failure', err, ctx);
+ * ```
+ */
+export const logger = Logger.getInstance();
+//# sourceMappingURL=logger.js.map

package/dist/utils/internal/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../../src/utils/internal/logger.ts"],"names":[],"mappings":"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"}

package/dist/utils/internal/performance.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview Performance utility for tool execution with modern observability.
+ * Wraps tool logic to measure duration, payload sizes, and memory usage, and
+ * records results to OpenTelemetry plus structured logs. No manual spans beyond
+ * the single wrapper span here per project guidelines.
+ * @module src/utils/internal/performance
+ */
+import type { performance as PerfHooksPerformance } from 'node:perf_hooks';
+import type { RequestContext } from '../../utils/internal/requestContext.js';
+/**
+ * Dynamically loads Node's `perf_hooks` module.
+ * Exposed as a named export so tests can inject a mock loader into
+ * {@link initHighResTimer} without patching the dynamic import machinery.
+ *
+ * @returns A promise resolving to the `perf_hooks` module shape (just the `performance` export).
+ */
+export declare function loadPerfHooks(): Promise<{
+    performance: typeof PerfHooksPerformance;
+}>;
+/**
+ * Initializes the module-level high-resolution timer used by {@link nowMs}.
+ *
+ * Resolution priority:
+ * 1. `globalThis.performance.now` — available in Cloudflare Workers and modern browsers.
+ * 2. `node:perf_hooks` `performance.now` — loaded dynamically to stay Workers-compatible.
+ * 3. `Date.now()` — millisecond-precision fallback; a warning is logged when this path is taken.
+ *
+ * Must be called once during server startup (before any tool executions) to ensure
+ * sub-millisecond timing accuracy. Subsequent calls are safe but no-ops in practice
+ * because the module-level `performanceNow` closure is overwritten each time.
+ *
+ * @param perfLoader - Optional override for the `perf_hooks` import; defaults to
+ *   {@link loadPerfHooks}. Inject a mock here in unit tests.
+ * @returns A promise that resolves once the timer is ready.
+ */
+export declare function initHighResTimer(perfLoader?: typeof loadPerfHooks): Promise<void>;
+/**
+ * Returns the current time in milliseconds using the highest-resolution timer
+ * available in this environment.
+ *
+ * The precision depends on which timer was selected by {@link initHighResTimer}:
+ * sub-millisecond after a successful init, millisecond-granular otherwise.
+ * The returned value is suitable for computing durations but its epoch origin
+ * is implementation-defined — do not treat it as a wall-clock timestamp.
+ *
+ * @returns Current time in milliseconds.
+ */
+export declare const nowMs: () => number;
+/**
+ * Wraps a tool's logic function with full observability: an OpenTelemetry span,
+ * OTel metric counters/histogram, structured log, and memory/payload size capture.
+ *
+ * The caller supplies the raw tool logic as `toolLogicFn`; this function handles
+ * all instrumentation so tool handlers stay free of telemetry boilerplate.
+ *
+ * On success the resolved value is passed through transparently.
+ * On failure the error is re-thrown after being recorded on the span and metrics;
+ * `McpError` instances surface their numeric `code` as the error code attribute.
+ *
+ * @template T - The resolved type of the tool's return value.
+ * @param toolLogicFn - Zero-argument async function containing the tool's business logic.
+ * @param context - Request context extended with `toolName`; used for span/log correlation.
+ * @param inputPayload - The raw input object passed to the tool, serialized to compute byte size.
+ * @returns A promise that resolves with the tool's return value or rejects with the original error.
+ *
+ * @example
+ * ```typescript
+ * const result = await measureToolExecution(
+ *   () => myToolHandler(parsedInput),
+ *   { ...requestContext, toolName: 'my_tool' },
+ *   parsedInput,
+ * );
+ * ```
+ */
+export declare function measureToolExecution<T>(toolLogicFn: () => Promise<T>, context: RequestContext & {
+    toolName: string;
+}, inputPayload: unknown): Promise<T>;
+//# sourceMappingURL=performance.d.ts.map

package/dist/utils/internal/performance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance.d.ts","sourceRoot":"","sources":["../../../src/utils/internal/performance.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,IAAI,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAM3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAkCzE;;;;;;GAMG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC;IAC7C,WAAW,EAAE,OAAO,oBAAoB,CAAC;CAC1C,CAAC,CAID;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,GAAE,OAAO,aAA6B,GAC/C,OAAO,CAAC,IAAI,CAAC,CAsBf;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,QAAO,MAA0B,CAAC;AAgCpD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,WAAW,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC7B,OAAO,EAAE,cAAc,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,EAC9C,YAAY,EAAE,OAAO,GACpB,OAAO,CAAC,CAAC,CAAC,CA6FZ"}