@cyanheads/mcp-ts-core 0.13.11 → 0.13.13

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

@@ -3,31 +3,97 @@
  * Enhanced with cause chain extraction and circular reference detection.
  * @module src/utils/internal/error-handler/helpers
  */
+import { type Span } from '@opentelemetry/api';
 import { ZodError } from 'zod';
 /**
- * Formats a ZodError as a human-readable sentence.
+ * What the error path writes for a field whose read throws — a getter, a
+ * `Proxy` trap, a revoked `Proxy` — as the log-data walk does.
+ */
+export declare const UNREADABLE = "[Unreadable]";
+/** `value[key]`, or {@link UNREADABLE} when reading it throws. */
+export declare function readField(value: object, key: PropertyKey): unknown;
+/**
+ * An error's `message` or `name`, as read, written as text: a string as it is;
+ * any other primitive as `String` converts it, which runs no caller code and
+ * never throws, a `Symbol` included (`'Symbol(description)'`), so a `message`
+ * set to `404` reads `'404'`; and an object or function as {@link UNREADABLE},
+ * since converting one runs its own `toString`, which can throw or return
+ * anything.
+ */
+export declare function errorText(value: unknown): string;
+/**
+ * `value instanceof type`, or `false` when the check throws — a revoked
+ * `Proxy`, a `getPrototypeOf` trap — so such a value is handled as the
+ * non-instance it cannot be shown not to be.
+ */
+export declare function isInstance<T>(value: unknown, type: abstract new (...args: never[]) => T): value is T;
+/**
+ * A copy of `value`'s own enumerable fields, as a spread makes it (`{}` for
+ * `undefined`), or `undefined` when making it throws — a getter that throws, a
+ * `Proxy` whose trap throws.
+ */
+export declare function copyFields<T extends object>(value: T | undefined): T | undefined;
+/**
+ * A shallow copy of the `data` a thrown `McpError` carries, so the error path
+ * reads plain fields rather than the thrown value's. Nothing is serialized: the
+ * log record writes the copy through the bounded log walk, and the wire
+ * boundaries check it with {@link readWireErrorData}. `undefined` when `error`
+ * is not an `McpError`, carries no object `data`, or its `data` cannot be read
+ * or copied — a getter, a revoked `Proxy`, a throwing `ownKeys` trap.
+ */
+export declare function readErrorData(error: unknown): Record<string, unknown> | undefined;
+/**
+ * {@link readErrorData} for a response: every field is one the wire carries.
+ * A field `JSON.stringify` cannot write is {@link UNREADABLE}, since a response
+ * holding one is never sent and the client waits for it, and a field that takes
+ * more than {@link WIRE_VALUES} JSON values to write is `'[Truncated]'`. Every
+ * other field is the thrown value itself, so readable `data` is sent byte for
+ * byte as thrown.
+ */
+export declare function readWireErrorData(error: unknown): Record<string, unknown> | undefined;
+/**
+ * `value` when it is an `Error`, else an `Error` whose message is `String(value)`
+ * — or {@link UNREADABLE} when the value can be neither checked nor converted
+ * (a revoked `Proxy`, a null-prototype object).
+ */
+export declare function asError(value: unknown): Error;
+/**
+ * Marks `span` failed with `error`: records an `Error` as the span's exception,
+ * then sets the `ERROR` status with its `message` (any other value as `String`
+ * converts it). Never throws: an exception the span cannot read — a field
+ * whose getter throws, which the SDK's `recordException` reads unguarded — is
+ * left unrecorded, and a message that cannot be read is {@link UNREADABLE}.
+ */
+export declare function recordSpanFailure(span: Span, error: unknown): void;
+/**
+ * Formats a ZodError as a single readable line: `<dotted.path>: <message>`.
  *
  * `ZodError.message` is a serialized JSON array of `ZodIssue` objects — useful for
  * debugging but unreadable in logs, client error messages, and UI surfaces. This
- * helper extracts the first issue's message (typically the most actionable) and
- * appends path + overflow count so `error.message` reads as prose.
+ * helper renders the first issue (typically the most actionable) with its path
+ * leading, the form every other path-bearing renderer in the framework uses, so
+ * a custom message written as a full sentence stays intact. An issue with an
+ * empty path renders as its bare message, and a count of the remaining issues
+ * trails as ` (+N more)`.
  *
  * Pair with `ErrorHandler.classifyOnly` (which returns `data: { issues }`) to
  * preserve the structured issue array for clients that can render field-level
  * errors.
  *
  * @param err - The ZodError to format.
- * @returns A single-line sentence, e.g. `"Expected string at nctId (+2 more)"`.
+ * @returns A single line, e.g. `"nctId: Invalid input: expected string, received number (+2 more)"`.
  */
 export declare function formatZodErrorMessage(err: ZodError): string;
 /**
  * Retrieves a descriptive name for an error object or value.
  *
- * - `Error` instances → `error.name` (e.g. `'TypeError'`), falling back to `'Error'`.
+ * - `Error` instances → `error.name` (e.g. `'TypeError'`), falling back to `'Error'`;
+ *   a `name` that is not a string is written as {@link errorText} writes it.
  * - `null` → `'NullValueEncountered'`
  * - `undefined` → `'UndefinedValueEncountered'`
  * - Non-plain objects with a named constructor → `'<ConstructorName>Encountered'`
  * - Everything else → `'<typeof value>Encountered'` (e.g. `'stringEncountered'`)
+ * - A value whose inspection throws (a `name` getter, a revoked `Proxy`) → `'[Unreadable]'`
  *
  * @param error - The error object or value.
  * @returns A stable, human-readable string identifying the error's type.
@@ -44,13 +110,16 @@ export declare function getErrorName(error: unknown): string;
  * Extracts a human-readable message string from any thrown value.
  *
  * Handles every JavaScript type so that `catch (e)` blocks never produce `[object Object]`:
- * - `AggregateError` → combines up to 3 inner error messages after the outer message.
- * - `Error` → `error.message`
+ * - `AggregateError` → combines up to 3 inner error messages after the outer message,
+ *   each one that cannot be read as `'[Unreadable]'`.
+ * - `Error` → `error.message`, or `'[Unreadable]'` when reading it throws (a getter);
+ *   a `message` that is not a string, the outer's or a member's, as {@link errorText} writes it.
  * - `null` / `undefined` → descriptive literal strings.
  * - Primitives (`string`, `number`, `boolean`, `bigint`, `symbol`) → string-coerced value.
  * - Functions → `[function <name>]`
  * - Objects → JSON-serialized if possible; otherwise constructor name fallback.
- * - If conversion itself throws, returns a safe fallback describing the conversion error.
+ * - A value whose inspection throws (a getter, a `Proxy` trap, a revoked `Proxy`) →
+ *   `'[Unreadable]'`, never the text of what the read threw.
  *
  * @param error - The thrown value to extract a message from.
  * @returns A non-empty string describing the error.
@@ -72,6 +141,13 @@ export declare function getErrorMessage(error: unknown): string;
  * with `depth: 0` being the original (outermost) error and increasing depth tracking nested causes.
  */
 export interface ErrorCauseNode {
+    /**
+     * The error's own string `code`, when it carries one — the transport code a
+     * fetch failure keeps: `ECONNREFUSED` on the `cause` of Node's
+     * `TypeError: fetch failed`, `ConnectionRefused` on Bun's rejection itself.
+     * `McpError`'s numeric JSON-RPC code is not copied.
+     */
+    code?: string;
     /** Additional data from McpError instances */
     data?: Record<string, unknown>;
     /** Depth in the cause chain (0 = original error) */
@@ -92,8 +168,14 @@ export interface ErrorCauseNode {
  * - or `maxDepth` is reached (sentinel node appended, then stops).
  *
  * String causes are treated as terminal `StringError` nodes.
- * `McpError` nodes include the `data` property when present.
+ * `McpError` nodes include the `data` property when present, and any `Error`
+ * node carrying a string `code` includes it.
  * Circular references are detected via `WeakSet` identity tracking.
+ * Every read is guarded: a `name`, `message`, or `stack` whose read throws is
+ * `'[Unreadable]'` on its node, an unreadable `code` or `data` is left out, and
+ * a cause that cannot be read or inspected — a throwing `cause` getter, a
+ * revoked `Proxy` — ends the chain as a node whose `name` and `message` are
+ * both `'[Unreadable]'`.
  *
  * @param error - The outermost error to start traversal from.
  * @param maxDepth - Maximum number of nodes to traverse before stopping. Defaults to `20`.

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

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../../src/utils/internal/error-handler/helpers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAK/B;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAQ3D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAoBnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAqDtD;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,SAAK,GAAG,cAAc,EAAE,CAkEtF"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../../src/utils/internal/error-handler/helpers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,IAAI,EAAkB,MAAM,oBAAoB,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAK/B;;;GAGG;AACH,eAAO,MAAM,UAAU,iBAAiB,CAAC;AAEzC,kEAAkE;AAClE,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAMlE;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAKhD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,QAAQ,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,GACzC,KAAK,IAAI,CAAC,CAMZ;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,SAAS,GAAG,CAAC,GAAG,SAAS,CAMhF;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAMjF;AAiCD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAKrF;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAM7C;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAiBlE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAQ3D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAwBnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAsDtD;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAcD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,SAAK,GAAG,cAAc,EAAE,CA+EtF"}

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

@@ -3,42 +3,206 @@
  * Enhanced with cause chain extraction and circular reference detection.
  * @module src/utils/internal/error-handler/helpers
  */
+import { SpanStatusCode } from '@opentelemetry/api';
 import { ZodError } from 'zod';
 import { McpError } from '../../../types-global/errors.js';
 import { isAggregateError } from '../../types/guards.js';
 /**
- * Formats a ZodError as a human-readable sentence.
+ * What the error path writes for a field whose read throws — a getter, a
+ * `Proxy` trap, a revoked `Proxy` — as the log-data walk does.
+ */
+export const UNREADABLE = '[Unreadable]';
+/** `value[key]`, or {@link UNREADABLE} when reading it throws. */
+export function readField(value, key) {
+    try {
+        return value[key];
+    }
+    catch {
+        return UNREADABLE;
+    }
+}
+/**
+ * An error's `message` or `name`, as read, written as text: a string as it is;
+ * any other primitive as `String` converts it, which runs no caller code and
+ * never throws, a `Symbol` included (`'Symbol(description)'`), so a `message`
+ * set to `404` reads `'404'`; and an object or function as {@link UNREADABLE},
+ * since converting one runs its own `toString`, which can throw or return
+ * anything.
+ */
+export function errorText(value) {
+    if (typeof value === 'string')
+        return value;
+    return value === null || (typeof value !== 'object' && typeof value !== 'function')
+        ? String(value)
+        : UNREADABLE;
+}
+/**
+ * `value instanceof type`, or `false` when the check throws — a revoked
+ * `Proxy`, a `getPrototypeOf` trap — so such a value is handled as the
+ * non-instance it cannot be shown not to be.
+ */
+export function isInstance(value, type) {
+    try {
+        return value instanceof type;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A copy of `value`'s own enumerable fields, as a spread makes it (`{}` for
+ * `undefined`), or `undefined` when making it throws — a getter that throws, a
+ * `Proxy` whose trap throws.
+ */
+export function copyFields(value) {
+    try {
+        return { ...value };
+    }
+    catch {
+        return;
+    }
+}
+/**
+ * A shallow copy of the `data` a thrown `McpError` carries, so the error path
+ * reads plain fields rather than the thrown value's. Nothing is serialized: the
+ * log record writes the copy through the bounded log walk, and the wire
+ * boundaries check it with {@link readWireErrorData}. `undefined` when `error`
+ * is not an `McpError`, carries no object `data`, or its `data` cannot be read
+ * or copied — a getter, a revoked `Proxy`, a throwing `ownKeys` trap.
+ */
+export function readErrorData(error) {
+    if (!isInstance(error, McpError))
+        return;
+    const data = readField(error, 'data');
+    return typeof data === 'object' && data !== null
+        ? copyFields(data)
+        : undefined;
+}
+/**
+ * JSON values one `data` field may take to write before the wire check gives it
+ * up: about 6 MB of JSON, checked in tens of milliseconds. `JSON.stringify`
+ * writes a shared object once per reference, so 17 objects that each refer to
+ * the next three times write 43 million values: seconds and gigabytes to
+ * serialize, and a response a stdio client cannot read.
+ */
+const WIRE_VALUES = 1_000_000;
+/** Thrown by the wire check's replacer once a field passes {@link WIRE_VALUES}. */
+const OVER_WIRE_BUDGET = Symbol('over wire budget');
+/**
+ * `value` when `JSON.stringify` writes it within {@link WIRE_VALUES} values;
+ * `'[Truncated]'` when it would take more, and {@link UNREADABLE} when it
+ * cannot be written at all — a getter or a revoked `Proxy` that throws on read
+ * at any depth, a `BigInt`, a cycle, a `toJSON` that throws.
+ */
+function wireField(value) {
+    let values = 0;
+    try {
+        JSON.stringify(value, (_key, field) => {
+            if (++values > WIRE_VALUES)
+                throw OVER_WIRE_BUDGET;
+            return field;
+        });
+        return value;
+    }
+    catch (error) {
+        return error === OVER_WIRE_BUDGET ? '[Truncated]' : UNREADABLE;
+    }
+}
+/**
+ * {@link readErrorData} for a response: every field is one the wire carries.
+ * A field `JSON.stringify` cannot write is {@link UNREADABLE}, since a response
+ * holding one is never sent and the client waits for it, and a field that takes
+ * more than {@link WIRE_VALUES} JSON values to write is `'[Truncated]'`. Every
+ * other field is the thrown value itself, so readable `data` is sent byte for
+ * byte as thrown.
+ */
+export function readWireErrorData(error) {
+    const copy = readErrorData(error);
+    if (copy === undefined)
+        return;
+    for (const key of Object.keys(copy))
+        copy[key] = wireField(copy[key]);
+    return copy;
+}
+/**
+ * `value` when it is an `Error`, else an `Error` whose message is `String(value)`
+ * — or {@link UNREADABLE} when the value can be neither checked nor converted
+ * (a revoked `Proxy`, a null-prototype object).
+ */
+export function asError(value) {
+    try {
+        return value instanceof Error ? value : new Error(String(value));
+    }
+    catch {
+        return new Error(UNREADABLE);
+    }
+}
+/**
+ * Marks `span` failed with `error`: records an `Error` as the span's exception,
+ * then sets the `ERROR` status with its `message` (any other value as `String`
+ * converts it). Never throws: an exception the span cannot read — a field
+ * whose getter throws, which the SDK's `recordException` reads unguarded — is
+ * left unrecorded, and a message that cannot be read is {@link UNREADABLE}.
+ */
+export function recordSpanFailure(span, error) {
+    let message;
+    try {
+        if (error instanceof Error) {
+            try {
+                span.recordException(error);
+            }
+            catch {
+                // The span could not read it; the status below still marks the failure.
+            }
+            message = String(error.message);
+        }
+        else {
+            message = String(error);
+        }
+    }
+    catch {
+        message = UNREADABLE;
+    }
+    span.setStatus({ code: SpanStatusCode.ERROR, message });
+}
+/**
+ * Formats a ZodError as a single readable line: `<dotted.path>: <message>`.
  *
  * `ZodError.message` is a serialized JSON array of `ZodIssue` objects — useful for
  * debugging but unreadable in logs, client error messages, and UI surfaces. This
- * helper extracts the first issue's message (typically the most actionable) and
- * appends path + overflow count so `error.message` reads as prose.
+ * helper renders the first issue (typically the most actionable) with its path
+ * leading, the form every other path-bearing renderer in the framework uses, so
+ * a custom message written as a full sentence stays intact. An issue with an
+ * empty path renders as its bare message, and a count of the remaining issues
+ * trails as ` (+N more)`.
  *
  * Pair with `ErrorHandler.classifyOnly` (which returns `data: { issues }`) to
  * preserve the structured issue array for clients that can render field-level
  * errors.
  *
  * @param err - The ZodError to format.
- * @returns A single-line sentence, e.g. `"Expected string at nctId (+2 more)"`.
+ * @returns A single line, e.g. `"nctId: Invalid input: expected string, received number (+2 more)"`.
  */
 export function formatZodErrorMessage(err) {
     const issues = err.issues;
     const first = issues[0];
     if (!first)
         return 'Validation failed';
-    const path = first.path.length > 0 ? ` at ${first.path.map(String).join('.')}` : '';
+    const path = first.path.length > 0 ? `${first.path.map(String).join('.')}: ` : '';
     const rest = issues.length - 1;
     const tail = rest > 0 ? ` (+${rest} more)` : '';
-    return `${first.message}${path}${tail}`;
+    return `${path}${first.message}${tail}`;
 }
 /**
  * Retrieves a descriptive name for an error object or value.
  *
- * - `Error` instances → `error.name` (e.g. `'TypeError'`), falling back to `'Error'`.
+ * - `Error` instances → `error.name` (e.g. `'TypeError'`), falling back to `'Error'`;
+ *   a `name` that is not a string is written as {@link errorText} writes it.
  * - `null` → `'NullValueEncountered'`
  * - `undefined` → `'UndefinedValueEncountered'`
  * - Non-plain objects with a named constructor → `'<ConstructorName>Encountered'`
  * - Everything else → `'<typeof value>Encountered'` (e.g. `'stringEncountered'`)
+ * - A value whose inspection throws (a `name` getter, a revoked `Proxy`) → `'[Unreadable]'`
  *
  * @param error - The error object or value.
  * @returns A stable, human-readable string identifying the error's type.
@@ -51,35 +215,43 @@ export function formatZodErrorMessage(err) {
  * ```
  */
 export function getErrorName(error) {
-    if (error instanceof Error) {
-        return error.name || 'Error';
-    }
-    if (error === null) {
-        return 'NullValueEncountered';
-    }
-    if (error === undefined) {
-        return 'UndefinedValueEncountered';
+    try {
+        if (error instanceof Error) {
+            const name = readField(error, 'name');
+            return name ? errorText(name) : 'Error';
+        }
+        if (error === null) {
+            return 'NullValueEncountered';
+        }
+        if (error === undefined) {
+            return 'UndefinedValueEncountered';
+        }
+        if (typeof error === 'object' &&
+            error.constructor &&
+            typeof error.constructor.name === 'string' &&
+            error.constructor.name !== 'Object') {
+            return `${error.constructor.name}Encountered`;
+        }
+        return `${typeof error}Encountered`;
     }
-    if (typeof error === 'object' &&
-        error !== null &&
-        error.constructor &&
-        typeof error.constructor.name === 'string' &&
-        error.constructor.name !== 'Object') {
-        return `${error.constructor.name}Encountered`;
+    catch {
+        return UNREADABLE;
     }
-    return `${typeof error}Encountered`;
 }
 /**
  * Extracts a human-readable message string from any thrown value.
  *
  * Handles every JavaScript type so that `catch (e)` blocks never produce `[object Object]`:
- * - `AggregateError` → combines up to 3 inner error messages after the outer message.
- * - `Error` → `error.message`
+ * - `AggregateError` → combines up to 3 inner error messages after the outer message,
+ *   each one that cannot be read as `'[Unreadable]'`.
+ * - `Error` → `error.message`, or `'[Unreadable]'` when reading it throws (a getter);
+ *   a `message` that is not a string, the outer's or a member's, as {@link errorText} writes it.
  * - `null` / `undefined` → descriptive literal strings.
  * - Primitives (`string`, `number`, `boolean`, `bigint`, `symbol`) → string-coerced value.
  * - Functions → `[function <name>]`
  * - Objects → JSON-serialized if possible; otherwise constructor name fallback.
- * - If conversion itself throws, returns a safe fallback describing the conversion error.
+ * - A value whose inspection throws (a getter, a `Proxy` trap, a revoked `Proxy`) →
+ *   `'[Unreadable]'`, never the text of what the read threw.
  *
  * @param error - The thrown value to extract a message from.
  * @returns A non-empty string describing the error.
@@ -100,16 +272,17 @@ export function getErrorMessage(error) {
             return formatZodErrorMessage(error);
         }
         if (error instanceof Error) {
+            const message = errorText(readField(error, 'message'));
             // AggregateError should surface combined messages succinctly
             if (isAggregateError(error)) {
                 const inner = error.errors
-                    .map((e) => (e instanceof Error ? e.message : String(e)))
+                    .map((e) => errorText(readField(asError(e), 'message')))
                     .filter(Boolean)
                     .slice(0, 3)
                     .join('; ');
-                return inner ? `${error.message}: ${inner}` : error.message;
+                return inner ? `${message}: ${inner}` : message;
             }
-            return error.message;
+            return message;
         }
         if (error === null) {
             return 'Null value encountered as error';
@@ -147,8 +320,19 @@ export function getErrorMessage(error) {
         // c8 ignore next
         return '[unrepresentable error]';
     }
-    catch (conversionError) {
-        return `Error converting error to string: ${conversionError instanceof Error ? conversionError.message : 'Unknown conversion error'}`;
+    catch {
+        return UNREADABLE;
+    }
+}
+/** Stands in, inside {@link extractErrorCauseChain}, for a `cause` whose read threw. */
+const UNREADABLE_CAUSE = Symbol('unreadable cause');
+/** `value instanceof Error`, or `undefined` when the check throws: a revoked `Proxy`, a `getPrototypeOf` trap. */
+function errorCheck(value) {
+    try {
+        return value instanceof Error;
+    }
+    catch {
+        return;
     }
 }
 /**
@@ -160,8 +344,14 @@ export function getErrorMessage(error) {
  * - or `maxDepth` is reached (sentinel node appended, then stops).
  *
  * String causes are treated as terminal `StringError` nodes.
- * `McpError` nodes include the `data` property when present.
+ * `McpError` nodes include the `data` property when present, and any `Error`
+ * node carrying a string `code` includes it.
  * Circular references are detected via `WeakSet` identity tracking.
+ * Every read is guarded: a `name`, `message`, or `stack` whose read throws is
+ * `'[Unreadable]'` on its node, an unreadable `code` or `data` is left out, and
+ * a cause that cannot be read or inspected — a throwing `cause` getter, a
+ * revoked `Proxy` — ends the chain as a node whose `name` and `message` are
+ * both `'[Unreadable]'`.
  *
  * @param error - The outermost error to start traversal from.
  * @param maxDepth - Maximum number of nodes to traverse before stopping. Defaults to `20`.
@@ -197,21 +387,35 @@ export function extractErrorCauseChain(error, maxDepth = 20) {
             }
             seen.add(current);
         }
-        if (current instanceof Error) {
+        const isError = current === UNREADABLE_CAUSE ? undefined : errorCheck(current);
+        if (isError === undefined) {
+            chain.push({ name: UNREADABLE, message: UNREADABLE, depth });
+            break;
+        }
+        if (isError) {
+            const err = current;
+            const code = readField(err, 'code');
+            const stack = readField(err, 'stack');
             const node = {
-                name: current.name,
-                message: current.message,
+                name: errorText(readField(err, 'name')),
+                message: errorText(readField(err, 'message')),
                 depth,
+                ...(typeof code === 'string' && code !== UNREADABLE ? { code } : {}),
                 // Only include stack if it exists (exact optional property types)
-                ...(current.stack !== undefined ? { stack: current.stack } : {}),
+                ...(stack !== undefined ? { stack: stack } : {}),
             };
             // Extract data from McpError instances
-            if (current instanceof McpError && current.data) {
-                node.data = current.data;
-            }
+            const data = err instanceof McpError ? readField(err, 'data') : undefined;
+            if (data && data !== UNREADABLE)
+                node.data = data;
             chain.push(node);
             // Continue traversing cause chain
-            current = current.cause;
+            try {
+                current = err.cause;
+            }
+            catch {
+                current = UNREADABLE_CAUSE;
+            }
         }
         else if (typeof current === 'string') {
             chain.push({

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

@@ -1 +1 @@
-{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../../src/utils/internal/error-handler/helpers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAE/B,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAa;IACjD,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;IAC1B,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACxB,IAAI,CAAC,KAAK;QAAE,OAAO,mBAAmB,CAAC;IACvC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACpF,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;IAC/B,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IAChD,OAAO,GAAG,KAAK,CAAC,OAAO,GAAG,IAAI,GAAG,IAAI,EAAE,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC,IAAI,IAAI,OAAO,CAAC;IAC/B,CAAC;IACD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO,sBAAsB,CAAC;IAChC,CAAC;IACD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,2BAA2B,CAAC;IACrC,CAAC;IACD,IACE,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,KAAK,CAAC,WAAW;QACjB,OAAO,KAAK,CAAC,WAAW,CAAC,IAAI,KAAK,QAAQ;QAC1C,KAAK,CAAC,WAAW,CAAC,IAAI,KAAK,QAAQ,EACnC,CAAC;QACD,OAAO,GAAG,KAAK,CAAC,WAAW,CAAC,IAAI,aAAa,CAAC;IAChD,CAAC;IACD,OAAO,GAAG,OAAO,KAAK,aAAa,CAAC;AACtC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,CAAC;QACH,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;YAC9B,OAAO,qBAAqB,CAAC,KAAK,CAAC,CAAC;QACtC,CAAC;QACD,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;YAC3B,6DAA6D;YAC7D,IAAI,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC5B,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM;qBACvB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;qBACxD,MAAM,CAAC,OAAO,CAAC;qBACf,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;qBACX,IAAI,CAAC,IAAI,CAAC,CAAC;gBACd,OAAO,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;YAC9D,CAAC;YACD,OAAO,KAAK,CAAC,OAAO,CAAC;QACvB,CAAC;QACD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,OAAO,iCAAiC,CAAC;QAC3C,CAAC;QACD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,sCAAsC,CAAC;QAChD,CAAC;QACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;YAC5D,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;QACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAC;QAC1B,CAAC;QACD,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;YAChC,OAAO,aAAa,KAAK,CAAC,IAAI,IAAI,WAAW,GAAG,CAAC;QACnD,CAAC;QACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;gBACnC,IAAI,IAAI,IAAI,IAAI,KAAK,IAAI;oBAAE,OAAO,IAAI,CAAC;YACzC,CAAC;YAAC,MAAM,CAAC;gBACP,eAAe;YACjB,CAAC;YACD,MAAM,IAAI,GAAI,KAA6C,CAAC,WAAW,EAAE,IAAI,CAAC;YAC9E,OAAO,8CAA8C,IAAI,IAAI,QAAQ,GAAG,CAAC;QAC3E,CAAC;QACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAC;QAC1B,CAAC;QACD,iBAAiB;QACjB,OAAO,yBAAyB,CAAC;IACnC,CAAC;IAAC,OAAO,eAAe,EAAE,CAAC;QACzB,OAAO,qCAAqC,eAAe,YAAY,KAAK,CAAC,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,0BAA0B,EAAE,CAAC;IACxI,CAAC;AACH,CAAC;AAoBD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAc,EAAE,QAAQ,GAAG,EAAE;IAClE,MAAM,KAAK,GAAqB,EAAE,CAAC;IACnC,MAAM,IAAI,GAAG,IAAI,OAAO,EAAU,CAAC;IACnC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,OAAO,OAAO,IAAI,KAAK,GAAG,QAAQ,EAAE,CAAC;QACnC,+BAA+B;QAC/B,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACpD,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;gBACtB,KAAK,CAAC,IAAI,CAAC;oBACT,IAAI,EAAE,mBAAmB;oBACzB,OAAO,EAAE,kDAAkD;oBAC3D,KAAK;iBACN,CAAC,CAAC;gBACH,MAAM;YACR,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACpB,CAAC;QAED,IAAI,OAAO,YAAY,KAAK,EAAE,CAAC;YAC7B,MAAM,IAAI,GAAmB;gBAC3B,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,KAAK;gBACL,kEAAkE;gBAClE,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACjE,CAAC;YAEF,uCAAuC;YACvC,IAAI,OAAO,YAAY,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;gBAChD,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;YAC3B,CAAC;YAED,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAEjB,kCAAkC;YAClC,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC;QAC1B,CAAC;aAAM,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YACvC,KAAK,CAAC,IAAI,CAAC;gBACT,IAAI,EAAE,aAAa;gBACnB,OAAO,EAAE,OAAO;gBAChB,KAAK;aACN,CAAC,CAAC;YACH,MAAM;QACR,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC;gBACT,IAAI,EAAE,YAAY,CAAC,OAAO,CAAC;gBAC3B,OAAO,EAAE,eAAe,CAAC,OAAO,CAAC;gBACjC,KAAK;aACN,CAAC,CAAC;YACH,MAAM;QACR,CAAC;QAED,KAAK,EAAE,CAAC;IACV,CAAC;IAED,IAAI,KAAK,IAAI,QAAQ,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC;YACT,IAAI,EAAE,kBAAkB;YACxB,OAAO,EAAE,+CAA+C,QAAQ,EAAE;YAClE,KAAK;SACN,CAAC,CAAC;IACL,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../../src/utils/internal/error-handler/helpers.ts"],"names":[],"mappings":"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"}

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

@@ -52,6 +52,9 @@ export interface ErrorHandlerOptions {
      * This can include `requestId` and other relevant debugging information.
      * It reaches the log record only, never the returned error's client-visible
      * `data`; put caller-actionable fields in the thrown `McpError`'s `data`.
+     * A context, or its `extra`, whose fields throw when copied — an own getter,
+     * a `Proxy` trap — is written as `'[Unreadable]'` under `context` or `extra`
+     * rather than failing the call.
      */
     context?: ErrorContext;
     /**
@@ -73,8 +76,21 @@ export interface ErrorHandlerOptions {
      */
     errorMapper?: (error: unknown) => Error;
     /**
-     * If true, stack traces will be included in the logs.
-     * Defaults to `true`.
+     * Whether the log record carries stack traces. Defaults to `true`: the
+     * record's `extra.stack` is then the throw site's stack — never a context's
+     * `extra.stack` — and each stack is written once: a `causeChain` node
+     * carrying the record's stack, or the same stack as the node before it, is
+     * written without it.
+     *
+     * `false` makes the record stack-free, as a `RequestCancelled` always is: no
+     * `extra.stack`, no `extra.errorData.originalStack`, no `stack` on any
+     * `extra.errorData.causeChain` node nor `originalStack` in a node's `data`,
+     * and every `Error` in the record — in `errorData`, `input`, or the
+     * context's `extra` — written without its `stack`, whether this handler, the
+     * thrown `McpError`'s own `data`, or the caller supplied the field. Any other
+     * key named `stack` is the caller's data and is written as given. The chain
+     * itself stays, each node keeping its other fields. The returned error and
+     * the exception recorded on the active span are the same either way.
      */
     includeStack?: boolean;
     /**
@@ -97,9 +113,10 @@ export interface ErrorHandlerOptions {
      * Level to emit this failure's log record at, in place of `error`.
      *
      * Set by the tool handler factory when the thrown error's `data.reason` names
-     * a contract entry declaring one (#380), and to `notice` for the framework's
+     * a contract entry declaring one (#380), to `notice` for the framework's
      * own `invalid_arguments` and `client_capability_missing` refusals when no
-     * entry declares one (#567). It moves the level of that one record
+     * entry declares one (#567), and to `notice` for a scope check's
+     * missing-scope refusal (#585). It moves the level of that one record
      * and adds `mcp.error.severity` to the `mcp.errors.classified` increment;
      * everything else the handler does — the span status, the rebuilt `McpError`,
      * the structured fields — is unchanged. A `RequestCancelled` keeps its own

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/utils/internal/error-handler/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACxF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,YAAa,SAAQ,OAAO,CAAC,cAAc,CAAC;IAC3D;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;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;IAElB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,qBAAqB,CAAC;CAClC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,SAAS,EAAE,gBAAgB,CAAC;IAE5B;;;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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/utils/internal/error-handler/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACxF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,YAAa,SAAQ,OAAO,CAAC,cAAc,CAAC;IAC3D;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;OAQG;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;;;;;;;;;;;;;;;;OAgBG;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;IAElB;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,EAAE,qBAAqB,CAAC;CAClC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,SAAS,EAAE,gBAAgB,CAAC;IAE5B;;;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"}