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

package/dist/utils/internal/error-handler/types.d.ts

@@ -0,0 +1,160 @@
+/**
+ * @fileoverview Shared type definitions for the error handler utilities.
+ * @module src/utils/internal/error-handler/types
+ */
+import type { JsonRpcErrorCode } from '../../../types-global/errors.js';
+/**
+ * Arbitrary key-value context attached to an error for logging and tracing.
+ *
+ * Passed as `options.context` to `ErrorHandler.handleError`. All entries are merged
+ * into the structured log record. `requestId` and `timestamp` receive special treatment:
+ * if present and valid they are used directly; otherwise they are generated automatically.
+ *
+ * @example
+ * ```ts
+ * const ctx: ErrorContext = {
+ *   requestId: 'req-abc123',
+ *   userId: 'usr-456',
+ *   resource: '/api/users',
+ * };
+ * ErrorHandler.handleError(err, { operation: 'getUser', context: ctx });
+ * ```
+ */
+export interface ErrorContext {
+    /**
+     * A unique identifier for the request or operation during which the error occurred.
+     * Used directly in log output if provided; auto-generated via `generateUUID` if absent.
+     */
+    requestId?: string;
+    /**
+     * Allows for arbitrary additional context information.
+     * Keys are strings, and values can be of any type.
+     */
+    [key: string]: unknown;
+}
+/**
+ * Configuration options for `ErrorHandler.handleError` and `ErrorHandler.tryCatch`.
+ *
+ * Controls error transformation, log output, and whether the error propagates to the caller.
+ *
+ * @example
+ * ```ts
+ * const opts: ErrorHandlerOptions = {
+ *   operation: 'fetchArticle',
+ *   context: { requestId: 'req-123', articleId: 'art-456' },
+ *   input: { id: 'art-456' },
+ *   rethrow: true,
+ *   critical: false,
+ * };
+ * ErrorHandler.handleError(err, opts);
+ * ```
+ */
+export interface ErrorHandlerOptions {
+    /**
+     * The context of the operation that caused the error.
+     * This can include `requestId` and other relevant debugging information.
+     */
+    context?: ErrorContext;
+    /**
+     * If true, indicates that the error is critical and might require immediate attention
+     * or could lead to system instability. This is primarily for logging and alerting.
+     * Defaults to `false`.
+     */
+    critical?: boolean;
+    /**
+     * A specific `JsonRpcErrorCode` to assign to the error, overriding any
+     * automatically determined error code.
+     */
+    errorCode?: JsonRpcErrorCode;
+    /**
+     * A custom function to map or transform the original error into a new `Error` instance.
+     * If provided, this function is used instead of the default `McpError` creation.
+     * @param error - The original error that occurred.
+     * @returns The transformed error.
+     */
+    errorMapper?: (error: unknown) => Error;
+    /**
+     * If true, stack traces will be included in the logs.
+     * Defaults to `true`.
+     */
+    includeStack?: boolean;
+    /**
+     * The input data or parameters that were being processed when the error occurred.
+     * This input will be sanitized before logging to prevent sensitive data exposure.
+     */
+    input?: unknown;
+    /**
+     * A descriptive name of the operation being performed when the error occurred.
+     * This helps in identifying the source or nature of the error in logs.
+     * Example: "UserLogin", "ProcessPayment", "FetchUserProfile".
+     */
+    operation: string;
+    /**
+     * If true, the (potentially transformed) error will be rethrown after handling.
+     * Defaults to `false`.
+     */
+    rethrow?: boolean;
+}
+/**
+ * A basic rule that classifies an error by matching its message or name against a pattern.
+ *
+ * Used as the element type for `COMMON_ERROR_PATTERNS` and `PROVIDER_ERROR_PATTERNS`, and
+ * as the base for the higher-level `ErrorMapping<T>` interface (which adds a `factory`).
+ *
+ * @example
+ * ```ts
+ * const rule: BaseErrorMapping = {
+ *   pattern: /not found/i,
+ *   errorCode: JsonRpcErrorCode.NotFound,
+ * };
+ * ```
+ */
+export interface BaseErrorMapping {
+    /**
+     * The `JsonRpcErrorCode` to assign if the pattern matches.
+     */
+    errorCode: JsonRpcErrorCode;
+    /**
+     * An optional custom message template for the mapped error.
+     */
+    messageTemplate?: string;
+    /**
+     * A string or regular expression to match against the error message.
+     * If a string is provided, it's used for substring matching (case-insensitive).
+     */
+    pattern: string | RegExp;
+}
+/**
+ * A pattern-based rule used by `ErrorHandler.mapError` to transform errors into a specific type `T`.
+ *
+ * Extends `BaseErrorMapping` with a `factory` that constructs the target error and an optional
+ * `additionalContext` object passed to that factory. Rules are tested in order; the first match wins.
+ *
+ * @template T The concrete `Error` subtype this mapping produces. Defaults to `Error`.
+ *
+ * @example
+ * ```ts
+ * const rule: ErrorMapping<McpError> = {
+ *   pattern: /connection refused/i,
+ *   errorCode: JsonRpcErrorCode.ServiceUnavailable,
+ *   additionalContext: { service: 'database' },
+ *   factory: (e, ctx) =>
+ *     new McpError(JsonRpcErrorCode.ServiceUnavailable, getErrorMessage(e), ctx),
+ * };
+ * ```
+ */
+export interface ErrorMapping<T extends Error = Error> extends BaseErrorMapping {
+    /**
+     * Additional static context to be merged or passed to the `factory` function
+     * when this mapping rule is applied.
+     */
+    additionalContext?: Record<string, unknown>;
+    /**
+     * A factory function that creates and returns an instance of the mapped error type `T`.
+     * @param error - The original error that occurred.
+     * @param context - Optional additional context provided in the mapping rule.
+     * @returns The newly created error instance.
+     */
+    factory: (error: unknown, context?: Record<string, unknown>) => T;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/utils/internal/error-handler/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/utils/internal/error-handler/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;IAEvB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;OAGG;IACH,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAE7B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,CAAC;IAExC;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,SAAS,EAAE,gBAAgB,CAAC;IAE5B;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,KAAK,GAAG,KAAK,CAAE,SAAQ,gBAAgB;IAC7E;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE5C;;;;;OAKG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;CACnE"}

package/dist/utils/internal/error-handler/types.js

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Shared type definitions for the error handler utilities.
+ * @module src/utils/internal/error-handler/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/utils/internal/error-handler/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/utils/internal/error-handler/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

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

@@ -0,0 +1,60 @@
+/**
+ * @fileoverview Health snapshot utility to surface observability/runtime readiness.
+ * This avoids heavy checks and focuses on quick signals for status endpoints or logs.
+ * @module src/utils/internal/health
+ */
+/**
+ * A point-in-time snapshot of server health signals.
+ * Intentionally lightweight — all fields are derived from already-initialized
+ * singletons and involve no I/O, so this is safe to call at any time.
+ */
+export interface HealthSnapshot {
+    /** Core application identity pulled from the active config. */
+    app: {
+        /** Server name (from `MCP_SERVER_NAME` or `package.json`). */
+        name: string;
+        /** Server version string (from `MCP_SERVER_VERSION` or `package.json`). */
+        version: string;
+        /** Deployment environment (e.g. `'development'`, `'production'`). */
+        environment: string;
+    };
+    /** Logger initialization state. */
+    logging: {
+        /** True when the logger has been fully initialized and is ready to emit records. */
+        initialized: boolean;
+    };
+    /** Runtime environment classification from {@link runtimeCaps}. */
+    runtime: {
+        /** True when running under Node.js or Bun. */
+        isNode: boolean;
+        /** True when running inside a Web Worker or Cloudflare Worker. */
+        isWorkerLike: boolean;
+        /** True when running in a browser main thread. */
+        isBrowserLike: boolean;
+    };
+    /** OpenTelemetry configuration state. */
+    telemetry: {
+        /** True when OpenTelemetry export is enabled (`OTEL_ENABLED=true`). */
+        enabled: boolean;
+        /** The OTel diagnostic log level, or `undefined` if not configured. */
+        diagLevel: string | undefined;
+    };
+}
+/**
+ * Returns a lightweight, synchronous health snapshot of the running server.
+ *
+ * Aggregates app identity, runtime environment flags, logger state, and
+ * OpenTelemetry configuration into a single object. Suitable for `/healthz`
+ * endpoints, startup log lines, or diagnostic tooling.
+ *
+ * No I/O is performed — all data comes from already-initialized module singletons.
+ *
+ * @returns A {@link HealthSnapshot} reflecting current server state.
+ * @example
+ * ```typescript
+ * const health = getHealthSnapshot();
+ * logger.info('Server health', health);
+ * ```
+ */
+export declare function getHealthSnapshot(): HealthSnapshot;
+//# sourceMappingURL=health.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../../src/utils/internal/health.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,GAAG,EAAE;QACH,8DAA8D;QAC9D,IAAI,EAAE,MAAM,CAAC;QACb,2EAA2E;QAC3E,OAAO,EAAE,MAAM,CAAC;QAChB,qEAAqE;QACrE,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,mCAAmC;IACnC,OAAO,EAAE;QACP,oFAAoF;QACpF,WAAW,EAAE,OAAO,CAAC;KACtB,CAAC;IACF,mEAAmE;IACnE,OAAO,EAAE;QACP,8CAA8C;QAC9C,MAAM,EAAE,OAAO,CAAC;QAChB,kEAAkE;QAClE,YAAY,EAAE,OAAO,CAAC;QACtB,kDAAkD;QAClD,aAAa,EAAE,OAAO,CAAC;KACxB,CAAC;IACF,yCAAyC;IACzC,SAAS,EAAE;QACT,uEAAuE;QACvE,OAAO,EAAE,OAAO,CAAC;QACjB,uEAAuE;QACvE,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;KAC/B,CAAC;CACH;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAoBlD"}

package/dist/utils/internal/health.js

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Health snapshot utility to surface observability/runtime readiness.
+ * This avoids heavy checks and focuses on quick signals for status endpoints or logs.
+ * @module src/utils/internal/health
+ */
+import { config } from '../../config/index.js';
+import { logger } from '../../utils/internal/logger.js';
+import { runtimeCaps } from '../../utils/internal/runtime.js';
+/**
+ * Returns a lightweight, synchronous health snapshot of the running server.
+ *
+ * Aggregates app identity, runtime environment flags, logger state, and
+ * OpenTelemetry configuration into a single object. Suitable for `/healthz`
+ * endpoints, startup log lines, or diagnostic tooling.
+ *
+ * No I/O is performed — all data comes from already-initialized module singletons.
+ *
+ * @returns A {@link HealthSnapshot} reflecting current server state.
+ * @example
+ * ```typescript
+ * const health = getHealthSnapshot();
+ * logger.info('Server health', health);
+ * ```
+ */
+export function getHealthSnapshot() {
+    return {
+        app: {
+            name: config.mcpServerName,
+            version: config.mcpServerVersion,
+            environment: config.environment,
+        },
+        runtime: {
+            isNode: runtimeCaps.isNode,
+            isWorkerLike: runtimeCaps.isWorkerLike,
+            isBrowserLike: runtimeCaps.isBrowserLike,
+        },
+        telemetry: {
+            enabled: Boolean(config.openTelemetry.enabled),
+            diagLevel: config.openTelemetry.logLevel,
+        },
+        logging: {
+            initialized: logger.isInitialized(),
+        },
+    };
+}
+//# sourceMappingURL=health.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../../../src/utils/internal/health.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAwC1D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO;QACL,GAAG,EAAE;YACH,IAAI,EAAE,MAAM,CAAC,aAAa;YAC1B,OAAO,EAAE,MAAM,CAAC,gBAAgB;YAChC,WAAW,EAAE,MAAM,CAAC,WAAW;SAChC;QACD,OAAO,EAAE;YACP,MAAM,EAAE,WAAW,CAAC,MAAM;YAC1B,YAAY,EAAE,WAAW,CAAC,YAAY;YACtC,aAAa,EAAE,WAAW,CAAC,aAAa;SACzC;QACD,SAAS,EAAE;YACT,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC;YAC9C,SAAS,EAAE,MAAM,CAAC,aAAa,CAAC,QAAQ;SACzC;QACD,OAAO,EAAE;YACP,WAAW,EAAE,MAAM,CAAC,aAAa,EAAE;SACpC;KACF,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,300 @@
+import { type RequestContext } from '../../utils/internal/requestContext.js';
+/**
+ * RFC 5424 severity levels supported by the MCP logger, ordered from least to most severe.
+ * These map internally to Pino levels for transport compatibility:
+ * - `debug` → pino `debug`
+ * - `info` / `notice` → pino `info`
+ * - `warning` → pino `warn`
+ * - `error` / `crit` → pino `error`
+ * - `alert` / `emerg` → pino `fatal`
+ */
+export type McpLogLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'crit' | 'alert' | 'emerg';
+/**
+ * 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 declare class Logger {
+    private static readonly instance;
+    private pinoLogger?;
+    private interactionLogger?;
+    private initialized;
+    private currentMcpLevel;
+    private transportType;
+    private rateLimitThreshold;
+    private rateLimitWindow;
+    private messageCounts;
+    private suppressedMessages;
+    private cleanupTimer?;
+    private constructor();
+    /**
+     * 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(): Logger;
+    private createPinoLogger;
+    private createInteractionLogger;
+    /**
+     * 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');
+     * ```
+     */
+    initialize(level?: McpLogLevel, transportType?: 'stdio' | 'http'): Promise<void>;
+    /**
+     * 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: McpLogLevel): void;
+    /**
+     * 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.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * 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());
+     * ```
+     */
+    close(): Promise<void>;
+    /**
+     * 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(): boolean;
+    private isRateLimited;
+    private flushSuppressedMessages;
+    private log;
+    private logWithError;
+    /**
+     * 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: string, context?: RequestContext): void;
+    /**
+     * 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: string, context?: RequestContext): void;
+    /**
+     * 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: string, context?: RequestContext): void;
+    /**
+     * 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: string, context?: RequestContext): void;
+    /**
+     * 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: string, errorOrContext: Error | RequestContext, context?: RequestContext): void;
+    /**
+     * 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: string, errorOrContext: Error | RequestContext, context?: RequestContext): void;
+    /**
+     * 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: string, errorOrContext: Error | RequestContext, context?: RequestContext): void;
+    /**
+     * 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: string, errorOrContext: Error | RequestContext, context?: RequestContext): void;
+    /**
+     * 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: string, errorOrContext: Error | RequestContext, context?: RequestContext): void;
+    /**
+     * 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: string, data: Record<string, unknown>): void;
+}
+/**
+ * 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 declare const logger: Logger;
+//# sourceMappingURL=logger.d.ts.map

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

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