@ttctl/mcp 0.0.0 → 0.1.0-rc.2

package/dist/diagnostic.d.ts

@@ -0,0 +1,262 @@
+/**
+ * Status discriminator for {@link McpToolInvokeEndRecord}. Three values
+ * cover the per-call outcome lattice:
+ *
+ *   - `"ok"` — tool callback resolved and returned a success-shaped
+ *     `ToolSuccessResponse` (no `isError: true`).
+ *   - `"error"` — tool callback resolved with a `ToolErrorResponse`
+ *     (typed domain failure, e.g. `(UNAUTHENTICATED): No auth token
+ *     found`). The MCP wire protocol carries this back to the client
+ *     verbatim; it is NOT an uncaught exception.
+ *   - `"throw"` — tool callback threw an exception that bubbled out of
+ *     the wrapper. The wrapper re-throws after emission so the MCP
+ *     SDK's default error path runs.
+ *
+ * Separating `"error"` from `"throw"` lets operators triage typed
+ * domain failures (expected, recoverable) from uncaught exceptions
+ * (unexpected, often a bug).
+ */
+export type McpToolInvokeStatus = "ok" | "error" | "throw";
+/**
+ * Common base for every MCP-side diagnostic record. Mirrors the base
+ * fields on `configWriter.ts`'s `DebugRecordBase` so a single
+ * `jq 'select(.event == ...)'` filter works across both taxonomies.
+ *
+ * - `ts` — wall-clock ISO-8601 timestamp; useful for cross-process
+ *   correlation when an MCP session and a CLI invocation interleave.
+ * - `event` — discriminator naming the variant.
+ */
+interface McpDebugRecordBase {
+    ts: string;
+}
+/**
+ * `mcp_tool_invoke_start` — emitted BEFORE the tool callback runs.
+ * Pairs 1:1 with a downstream `mcp_tool_invoke_end` (`{tool, ts}` join key,
+ * plus `duration_ms` on the end record).
+ *
+ * `args_redacted` is the redacted form of the tool input. The redaction
+ * runs through `redactBody` from `@ttctl/core` so the canonical bearer
+ * pattern (`user_<24hex>_<20alnum>`), cookie strings, and secret-named
+ * fields (`password`, `token`, etc. per `SECRET_BODY_FIELD_NAMES`) are
+ * replaced with `***REDACTED***` BEFORE the record is constructed. The
+ * resulting object is safe to serialize.
+ */
+export interface McpToolInvokeStartRecord extends McpDebugRecordBase {
+    event: "mcp_tool_invoke_start";
+    tool: string;
+    args_redacted: unknown;
+}
+/**
+ * `mcp_tool_invoke_end` — emitted AFTER the tool callback completes (or
+ * throws). `duration_ms` is `performance.now()`-derived monotonic elapsed
+ * milliseconds rounded to integer, so the value stays accurate across
+ * wall-clock adjustments during the call.
+ *
+ * The `status` field discriminates the three outcomes (see
+ * {@link McpToolInvokeStatus}).
+ */
+export interface McpToolInvokeEndRecord extends McpDebugRecordBase {
+    event: "mcp_tool_invoke_end";
+    tool: string;
+    duration_ms: number;
+    status: McpToolInvokeStatus;
+}
+/**
+ * `mcp_auth_resolve` — emitted on every auth-resolver invocation (every
+ * tool call hits the resolver). Useful for cache-miss diagnostics in
+ * long-running MCP sessions: a token rotation via a sibling
+ * `ttctl auth signin` shows up as `token_fresh: true` on the FIRST
+ * post-rotation tool call.
+ *
+ * Fields:
+ *   - `mtime_ms` — mtime of the captured config path at resolve time,
+ *     or `null` if the stat failed (file removed, permissions changed
+ *     mid-session). Stat overhead is bounded — POSIX stat is microseconds
+ *     and only fires when emission is active.
+ *   - `token_fresh` — `true` when this resolve produced a token AND the
+ *     mtime differs from the prior resolve's mtime, `false` otherwise.
+ *     The "first resolve" case (no prior mtime) reports `true` if a
+ *     token was found, `false` if `auth.token` was undefined.
+ *   - `outcome` — discriminates the three resolve outcomes: `"ok"` when
+ *     a token was returned, `"unauthenticated"` when `auth.token` was
+ *     undefined, `"config_error"` when the resolver rejected with a
+ *     `ConfigError` (NO_CREDS, PARSE, VALIDATION, PERMISSION, LOCKED).
+ *
+ * The bearer value itself is NEVER in the record — only the boolean
+ * presence signal.
+ */
+export interface McpAuthResolveRecord extends McpDebugRecordBase {
+    event: "mcp_auth_resolve";
+    mtime_ms: number | null;
+    token_fresh: boolean;
+    outcome: "ok" | "unauthenticated" | "config_error";
+}
+/**
+ * `mcp_transport_error` — emitted when a transport-layer error
+ * (`Cf403Error`, `Cf403PersistentError`, `SchedulerBearerExpired`,
+ * other named transport throws) bubbles out of a tool callback.
+ * Separates transport-cause failures from domain-cause failures so
+ * Cloudflare regressions show up as a single grep target.
+ *
+ * Fields:
+ *   - `tool` — name of the tool whose handler observed the error.
+ *   - `surface` — `"talent-profile"` / `"mobile-gateway"` / `"scheduler"`
+ *     / `"unknown"`. Extracted from the error class where possible
+ *     (`Cf403Error` carries `surface` verbatim); otherwise `"unknown"`.
+ *   - `error_class` — `err.name` (`"Cf403Error"`,
+ *     `"Cf403PersistentError"`, …). Stable across messages.
+ *   - `status` — HTTP status code when the error carries one, else
+ *     `null`. `Cf403Error`/`Cf403PersistentError` -> 403,
+ *     `SchedulerBearerExpired` -> 401.
+ */
+export interface McpTransportErrorRecord extends McpDebugRecordBase {
+    event: "mcp_transport_error";
+    tool: string;
+    surface: "talent-profile" | "mobile-gateway" | "scheduler" | "unknown";
+    error_class: string;
+    status: number | null;
+}
+/**
+ * Discriminated union of every MCP-side diagnostic record. The type
+ * system is the FIRST line of bearer-absence enforcement: no variant
+ * here admits a bearer-shaped field. The runtime substring-assertion in
+ * `__tests__/diagnostic.test.ts` is the SECOND line — catches any
+ * accidental bearer leakage via `args_redacted` (the only slot where
+ * client-supplied data flows in).
+ */
+export type McpDebugRecord = McpToolInvokeStartRecord | McpToolInvokeEndRecord | McpAuthResolveRecord | McpTransportErrorRecord;
+/**
+ * Logger signature: receives a fully-constructed record and emits it
+ * somewhere observable (stderr by default; an in-memory array in tests).
+ *
+ * The logger MUST NOT throw — diagnostic emission is a fire-and-forget
+ * side channel and an exception here would unwind the tool call. The
+ * default emitter catches and swallows any `process.stderr.write` error
+ * (rare on stdio; pipe-broken EPIPE during teardown is the only realistic
+ * case). Custom loggers should follow the same posture.
+ */
+export type McpDiagnosticLogger = (record: McpDebugRecord) => void;
+/**
+ * Replace the active MCP diagnostic logger. Wired in production by
+ * `runMcpStdio()` at server startup; called by tests in `beforeEach`
+ * to inject a capturing logger.
+ *
+ * Production callers pass `defaultLogger` (re-exported via the index)
+ * or any custom logger conforming to {@link McpDiagnosticLogger}.
+ */
+export declare function setMcpDiagnosticLogger(logger: McpDiagnosticLogger): void;
+/**
+ * Read the currently-installed logger. Tests use this for round-trip
+ * verification ("set, then read, then call"). Production code reads via
+ * {@link emitMcpDebug} instead.
+ */
+export declare function getMcpDiagnosticLogger(): McpDiagnosticLogger;
+/**
+ * Restore the default env-gated stderr logger AND clear the mtime
+ * tracker. Tests MUST call this in `afterEach` to avoid state bleeding
+ * across cases — both the logger override and the mtime baseline are
+ * module-scoped state.
+ */
+export declare function resetMcpDiagnosticLogger(): void;
+/**
+ * Emit a structured MCP debug record via the current logger. Lazy
+ * construction via the `makeRecord` thunk keeps the disabled path
+ * zero-allocation when `currentLogger === defaultLogger` and
+ * `DEBUG_ENABLED === false`: V8 inlines `defaultLogger` to a no-op and
+ * the thunk body is dead code.
+ *
+ * When a custom logger is installed (test injection), the thunk runs
+ * unconditionally — the logger sees every event regardless of env state.
+ * This is intentional: tests assert on emission shape without needing
+ * to manipulate `process.env`.
+ */
+export declare function emitMcpDebug(makeRecord: () => McpDebugRecord): void;
+/**
+ * Emit a `mcp_auth_resolve` record summarizing an auth-resolver
+ * invocation. Called by the three resolver factories
+ * (`createToolAuthResolver`, `createTokenLoader`, `createTokenResolver`)
+ * AFTER each per-call `resolveConfig` returns (or throws). The bearer
+ * itself is NEVER passed in — only `hasToken: boolean`.
+ *
+ * `mtime_ms` is captured via a synchronous `statSync` on the captured
+ * config path. Sync stat is microseconds and only fires when emission
+ * is active (the env-gate / injected-logger fast-path skips the stat
+ * entirely on the disabled path). On stat failure (file removed
+ * mid-session, permissions changed), `mtime_ms` is `null` and
+ * `token_fresh` is `false` (cannot prove freshness without a baseline).
+ */
+export declare function emitMcpAuthResolve(configPath: string, outcome: McpAuthResolveRecord["outcome"], hasToken: boolean): void;
+/**
+ * Helper: redact tool args for {@link McpToolInvokeStartRecord}. Two-pass
+ * defense:
+ *
+ *   1. `redactBody` from `@ttctl/core` replaces FIELD values whose key
+ *      matches `SECRET_BODY_FIELD_NAMES` (`password`, `token`, etc.).
+ *   2. {@link scrubBearerPatternInStrings} walks the result and replaces
+ *      any STRING value that matches the canonical bearer pattern
+ *      (`user_<24hex>_<20alnum>`). This catches the case where an LLM
+ *      client pastes a bearer-shaped value into a free-text arg like
+ *      `{ note: "user_abc..." }` that the field-name pass would miss.
+ *
+ * The MCP tool surface accepts arbitrary client-supplied JSON, so the
+ * second pass is the load-bearing defense for bearer-absence in
+ * `args_redacted`. The transport-side `redactBody` doesn't need it
+ * because GraphQL variables are typed and the bearer never appears in
+ * any documented variable slot — MCP args have no such guarantee.
+ */
+export declare function redactToolArgs(args: unknown): unknown;
+/**
+ * Extract the transport `surface` from an error-shaped value. The
+ * `Cf403Error` / `Cf403PersistentError` classes carry `surface` verbatim;
+ * `SchedulerBearerExpired` implies `"scheduler"`. Anything else returns
+ * `"unknown"` — the operator triages from `error_class` directly.
+ *
+ * Exported for tests; production code routes through
+ * {@link emitMcpTransportError}.
+ */
+export declare function extractTransportSurface(err: unknown): McpTransportErrorRecord["surface"];
+/**
+ * Extract HTTP status from a transport error. `Cf403Error` /
+ * `Cf403PersistentError` are 403 by construction; `SchedulerBearerExpired`
+ * is 401. Errors carrying a numeric `status` field return that value.
+ * Anything else returns `null`.
+ */
+export declare function extractTransportStatus(err: unknown): number | null;
+/**
+ * Recognize transport-class errors so the wrapper can emit
+ * {@link McpTransportErrorRecord} only for transport-cause failures
+ * (Cloudflare 403, scheduler bearer expired, etc.) and skip domain-cause
+ * throws (which the MCP error contract surfaces via `ToolErrorResponse`).
+ */
+export declare function isTransportError(err: unknown): boolean;
+/**
+ * Helper for wrapping a tool callback with the start/end/transport-error
+ * emission contract. The wrapped handler:
+ *
+ *   1. Captures a monotonic start time.
+ *   2. Emits `mcp_tool_invoke_start` with `redactToolArgs(input)`.
+ *   3. Runs the original handler with all forwarded arguments.
+ *   4. On success: emits `mcp_tool_invoke_end` with status `"ok"` /
+ *      `"error"` derived from the response shape, plus `duration_ms`.
+ *   5. On throw: emits `mcp_tool_invoke_end` with status `"throw"`,
+ *      then `mcp_transport_error` if the error class is transport-typed,
+ *      then re-throws.
+ *
+ * The wrapper is a closure over the tool name so the same factory
+ * produces a per-tool wrapper that names itself correctly in every
+ * emission.
+ *
+ * The MCP SDK's `ToolCallback<Args>` accepts a two-argument callback
+ * `(input, extra)` (where `extra` is `RequestHandlerExtra` carrying
+ * the active session / abort signal). Some tool callbacks accept zero
+ * arguments (no inputSchema) — the SDK calls them with `(extra)` only.
+ * The wrapper forwards `...rest` so both shapes work without per-shape
+ * branching at the call site.
+ */
+export declare function wrapToolHandler<THandler extends (...args: any[]) => Promise<{
+    isError?: boolean;
+}> | {
+    isError?: boolean;
+}>(toolName: string, handler: THandler): THandler;
+export {};
+//# sourceMappingURL=diagnostic.d.ts.map

package/dist/diagnostic.d.ts.map

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

package/dist/diagnostic.js

@@ -0,0 +1,362 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+/**
+ * MCP-side structured-event diagnostic taxonomy (issue #224). Mirrors the
+ * config-write debug taxonomy in `@ttctl/core/configWriter.ts`
+ * (`TTCTL_DEBUG_CONFIG=1`) but scoped to the MCP entry point: tool
+ * invocations, auth-resolver re-reads, and transport errors observed
+ * inside the long-lived MCP process.
+ *
+ * Two emission paths:
+ *
+ *   1. **Default env-gated stderr emitter.** Reads `TTCTL_DEBUG_MCP=1`
+ *      ONCE at module load so the disabled path constant-folds to a single
+ *      comparison in V8 (NFR: zero-cost-when-disabled). Writes one
+ *      JSON-encoded record per line to `process.stderr` — the stdio
+ *      data channel (`process.stdout`, owned by the MCP protocol) is
+ *      never touched.
+ *   2. **Injected logger.** Tests (and any future SSE/HTTP transport
+ *      wrapper) call {@link setMcpDiagnosticLogger} to replace the
+ *      default emitter with a fake that captures records into an array.
+ *      The injection point in production code is
+ *      {@link runMcpStdio} — wiring the logger ONCE at the entry point
+ *      so per-tool callsites stay free of conditional logger plumbing.
+ *
+ * Bearer-absence is a load-bearing invariant: no record variant in the
+ * {@link McpDebugRecord} discriminated union carries a bearer-shaped
+ * field, and the runtime `redactBody` pass on `args_redacted` covers
+ * the one slot that could plausibly admit one (tool args contributed by
+ * the LLM client). The test suite asserts substring-absence across every
+ * emission path; the type system enforces it at the call-site.
+ */
+import { statSync } from "node:fs";
+import { performance } from "node:perf_hooks";
+import { BEARER_PATTERN_SOURCE, REDACTED, redactBody } from "@ttctl/core";
+/**
+ * Module-load capture of `TTCTL_DEBUG_MCP=1`. Read ONCE so the disabled
+ * path constant-folds to a single `if (DEBUG_ENABLED)` comparison in V8 —
+ * the env-unset path pays zero runtime overhead per-event.
+ *
+ * Tests that exercise both env-set and env-unset paths re-import the
+ * module via dynamic `import()` after mutating `process.env`. The
+ * injection path via {@link setMcpDiagnosticLogger} sidesteps the env
+ * gate entirely (the injected logger is always called) and is the
+ * preferred pattern for new tests.
+ */
+const DEBUG_ENABLED = process.env["TTCTL_DEBUG_MCP"] === "1";
+/**
+ * Default logger: env-gated stderr emitter. When `TTCTL_DEBUG_MCP=1`,
+ * writes one JSON-encoded record per line to `process.stderr`. When
+ * unset (or any other value), no-op.
+ *
+ * The env gate is captured at module load (see {@link DEBUG_ENABLED})
+ * so a JIT'd V8 inlines this function down to either:
+ *   - `() => undefined` (env unset; constant-folded dead branch), or
+ *   - `(record) => process.stderr.write(JSON.stringify(record) + '\n')`
+ *     (env set).
+ *
+ * Stderr is chosen so the stdio data channel (stdout, owned by the MCP
+ * JSON-RPC protocol) stays uncontaminated.
+ */
+const defaultLogger = (record) => {
+    if (!DEBUG_ENABLED)
+        return;
+    try {
+        process.stderr.write(JSON.stringify(record) + "\n");
+    }
+    catch {
+        // EPIPE during teardown; nothing meaningful to do. Diagnostic
+        // emission must never unwind a tool call.
+    }
+};
+/**
+ * Module-scoped logger holder. Mirrors the `currentLevel` pattern in
+ * `@ttctl/core/lib/diagnostic-log.ts`: one global, set at entry-point
+ * wiring time, read on every emit. Module isolation keeps per-tool
+ * callsites focused on their domain (no logger parameter threading)
+ * while exposing a single test-injection point.
+ */
+let currentLogger = defaultLogger;
+/**
+ * Replace the active MCP diagnostic logger. Wired in production by
+ * `runMcpStdio()` at server startup; called by tests in `beforeEach`
+ * to inject a capturing logger.
+ *
+ * Production callers pass `defaultLogger` (re-exported via the index)
+ * or any custom logger conforming to {@link McpDiagnosticLogger}.
+ */
+export function setMcpDiagnosticLogger(logger) {
+    currentLogger = logger;
+}
+/**
+ * Read the currently-installed logger. Tests use this for round-trip
+ * verification ("set, then read, then call"). Production code reads via
+ * {@link emitMcpDebug} instead.
+ */
+export function getMcpDiagnosticLogger() {
+    return currentLogger;
+}
+/**
+ * Restore the default env-gated stderr logger AND clear the mtime
+ * tracker. Tests MUST call this in `afterEach` to avoid state bleeding
+ * across cases — both the logger override and the mtime baseline are
+ * module-scoped state.
+ */
+export function resetMcpDiagnosticLogger() {
+    currentLogger = defaultLogger;
+    lastSeenMtime.clear();
+}
+/**
+ * Emit a structured MCP debug record via the current logger. Lazy
+ * construction via the `makeRecord` thunk keeps the disabled path
+ * zero-allocation when `currentLogger === defaultLogger` and
+ * `DEBUG_ENABLED === false`: V8 inlines `defaultLogger` to a no-op and
+ * the thunk body is dead code.
+ *
+ * When a custom logger is installed (test injection), the thunk runs
+ * unconditionally — the logger sees every event regardless of env state.
+ * This is intentional: tests assert on emission shape without needing
+ * to manipulate `process.env`.
+ */
+export function emitMcpDebug(makeRecord) {
+    // Fast-path: default logger + env unset → skip the thunk entirely.
+    // Any custom logger (test injection) bypasses the gate.
+    if (currentLogger === defaultLogger && !DEBUG_ENABLED)
+        return;
+    currentLogger(makeRecord());
+}
+/**
+ * Module-scoped tracker of the last-observed mtime per config path.
+ * Lets {@link emitMcpAuthResolve} report `token_fresh: true` on the
+ * FIRST tool call after a sibling `ttctl auth signin` rotates the
+ * bearer (mtime moves; fresh resolve picks up the new value).
+ *
+ * Keyed by absolute config path so multi-session callers (theoretical
+ * future SSE transport hosting two clients) don't collide. Production
+ * use today is single-path: one MCP session = one captured path.
+ *
+ * Reset by {@link resetMcpDiagnosticLogger} so tests get a clean slate
+ * between cases.
+ */
+const lastSeenMtime = new Map();
+/**
+ * Emit a `mcp_auth_resolve` record summarizing an auth-resolver
+ * invocation. Called by the three resolver factories
+ * (`createToolAuthResolver`, `createTokenLoader`, `createTokenResolver`)
+ * AFTER each per-call `resolveConfig` returns (or throws). The bearer
+ * itself is NEVER passed in — only `hasToken: boolean`.
+ *
+ * `mtime_ms` is captured via a synchronous `statSync` on the captured
+ * config path. Sync stat is microseconds and only fires when emission
+ * is active (the env-gate / injected-logger fast-path skips the stat
+ * entirely on the disabled path). On stat failure (file removed
+ * mid-session, permissions changed), `mtime_ms` is `null` and
+ * `token_fresh` is `false` (cannot prove freshness without a baseline).
+ */
+export function emitMcpAuthResolve(configPath, outcome, hasToken) {
+    if (currentLogger === defaultLogger && !DEBUG_ENABLED)
+        return;
+    let mtime_ms;
+    try {
+        mtime_ms = statSync(configPath).mtimeMs;
+    }
+    catch {
+        mtime_ms = null;
+    }
+    const prior = lastSeenMtime.get(configPath);
+    // token_fresh is true ONLY when we have a NEW mtime AND a token.
+    // - First call (no prior): true if hasToken (the token "appears fresh"
+    //   from the resolver's POV).
+    // - mtime moved forward: true if hasToken.
+    // - mtime unchanged: false (same file, no rotation since last call).
+    // - mtime null: false (cannot prove freshness).
+    const token_fresh = mtime_ms !== null && hasToken && (prior === undefined || mtime_ms !== prior);
+    if (mtime_ms !== null)
+        lastSeenMtime.set(configPath, mtime_ms);
+    currentLogger({
+        ts: new Date().toISOString(),
+        event: "mcp_auth_resolve",
+        mtime_ms,
+        token_fresh,
+        outcome,
+    });
+}
+/**
+ * Helper: redact tool args for {@link McpToolInvokeStartRecord}. Two-pass
+ * defense:
+ *
+ *   1. `redactBody` from `@ttctl/core` replaces FIELD values whose key
+ *      matches `SECRET_BODY_FIELD_NAMES` (`password`, `token`, etc.).
+ *   2. {@link scrubBearerPatternInStrings} walks the result and replaces
+ *      any STRING value that matches the canonical bearer pattern
+ *      (`user_<24hex>_<20alnum>`). This catches the case where an LLM
+ *      client pastes a bearer-shaped value into a free-text arg like
+ *      `{ note: "user_abc..." }` that the field-name pass would miss.
+ *
+ * The MCP tool surface accepts arbitrary client-supplied JSON, so the
+ * second pass is the load-bearing defense for bearer-absence in
+ * `args_redacted`. The transport-side `redactBody` doesn't need it
+ * because GraphQL variables are typed and the bearer never appears in
+ * any documented variable slot — MCP args have no such guarantee.
+ */
+export function redactToolArgs(args) {
+    return scrubBearerPatternInStrings(redactBody(args));
+}
+/**
+ * Walk an arbitrary structure (object / array / scalar) and replace any
+ * string value matching the canonical Toptal session bearer pattern
+ * with {@link REDACTED}. The pattern source comes from `@ttctl/core` so
+ * we never duplicate the bearer regex — the lint-time leakage check
+ * uses the same constant.
+ *
+ * Pure — does not mutate the input. Designed to compose AFTER
+ * `redactBody`: any field already replaced with `***REDACTED***` is a
+ * non-matching scalar and passes through unchanged.
+ */
+function scrubBearerPatternInStrings(input) {
+    if (input === null || input === undefined)
+        return input;
+    if (typeof input === "string") {
+        return input.match(new RegExp(BEARER_PATTERN_SOURCE)) !== null ? REDACTED : input;
+    }
+    if (Array.isArray(input))
+        return input.map((item) => scrubBearerPatternInStrings(item));
+    if (typeof input !== "object")
+        return input;
+    const out = {};
+    for (const [key, value] of Object.entries(input)) {
+        out[key] = scrubBearerPatternInStrings(value);
+    }
+    return out;
+}
+/**
+ * Extract the transport `surface` from an error-shaped value. The
+ * `Cf403Error` / `Cf403PersistentError` classes carry `surface` verbatim;
+ * `SchedulerBearerExpired` implies `"scheduler"`. Anything else returns
+ * `"unknown"` — the operator triages from `error_class` directly.
+ *
+ * Exported for tests; production code routes through
+ * {@link emitMcpTransportError}.
+ */
+export function extractTransportSurface(err) {
+    if (typeof err !== "object" || err === null)
+        return "unknown";
+    const name = err.name;
+    if (name === "SchedulerBearerExpired")
+        return "scheduler";
+    const surface = err.surface;
+    if (surface === "talent-profile" || surface === "mobile-gateway" || surface === "scheduler")
+        return surface;
+    return "unknown";
+}
+/**
+ * Extract HTTP status from a transport error. `Cf403Error` /
+ * `Cf403PersistentError` are 403 by construction; `SchedulerBearerExpired`
+ * is 401. Errors carrying a numeric `status` field return that value.
+ * Anything else returns `null`.
+ */
+export function extractTransportStatus(err) {
+    if (typeof err !== "object" || err === null)
+        return null;
+    const name = err.name;
+    if (name === "Cf403Error" || name === "Cf403PersistentError")
+        return 403;
+    if (name === "SchedulerBearerExpired")
+        return 401;
+    const status = err.status;
+    if (typeof status === "number")
+        return status;
+    return null;
+}
+/**
+ * Recognize transport-class errors so the wrapper can emit
+ * {@link McpTransportErrorRecord} only for transport-cause failures
+ * (Cloudflare 403, scheduler bearer expired, etc.) and skip domain-cause
+ * throws (which the MCP error contract surfaces via `ToolErrorResponse`).
+ */
+export function isTransportError(err) {
+    if (typeof err !== "object" || err === null)
+        return false;
+    const name = err.name;
+    return name === "Cf403Error" || name === "Cf403PersistentError" || name === "SchedulerBearerExpired";
+}
+/**
+ * Helper for wrapping a tool callback with the start/end/transport-error
+ * emission contract. The wrapped handler:
+ *
+ *   1. Captures a monotonic start time.
+ *   2. Emits `mcp_tool_invoke_start` with `redactToolArgs(input)`.
+ *   3. Runs the original handler with all forwarded arguments.
+ *   4. On success: emits `mcp_tool_invoke_end` with status `"ok"` /
+ *      `"error"` derived from the response shape, plus `duration_ms`.
+ *   5. On throw: emits `mcp_tool_invoke_end` with status `"throw"`,
+ *      then `mcp_transport_error` if the error class is transport-typed,
+ *      then re-throws.
+ *
+ * The wrapper is a closure over the tool name so the same factory
+ * produces a per-tool wrapper that names itself correctly in every
+ * emission.
+ *
+ * The MCP SDK's `ToolCallback<Args>` accepts a two-argument callback
+ * `(input, extra)` (where `extra` is `RequestHandlerExtra` carrying
+ * the active session / abort signal). Some tool callbacks accept zero
+ * arguments (no inputSchema) — the SDK calls them with `(extra)` only.
+ * The wrapper forwards `...rest` so both shapes work without per-shape
+ * branching at the call site.
+ */
+export function wrapToolHandler(toolName, handler) {
+    const wrapped = async (...args) => {
+        const input = args[0];
+        const start = performance.now();
+        emitMcpDebug(() => {
+            return {
+                ts: new Date().toISOString(),
+                event: "mcp_tool_invoke_start",
+                tool: toolName,
+                args_redacted: redactToolArgs(input),
+            };
+        });
+        try {
+            const result = (await handler(...args));
+            const duration_ms = Math.round(performance.now() - start);
+            const status = result.isError === true ? "error" : "ok";
+            emitMcpDebug(() => {
+                return {
+                    ts: new Date().toISOString(),
+                    event: "mcp_tool_invoke_end",
+                    tool: toolName,
+                    duration_ms,
+                    status,
+                };
+            });
+            return result;
+        }
+        catch (err) {
+            const duration_ms = Math.round(performance.now() - start);
+            emitMcpDebug(() => {
+                return {
+                    ts: new Date().toISOString(),
+                    event: "mcp_tool_invoke_end",
+                    tool: toolName,
+                    duration_ms,
+                    status: "throw",
+                };
+            });
+            if (isTransportError(err)) {
+                emitMcpDebug(() => {
+                    return {
+                        ts: new Date().toISOString(),
+                        event: "mcp_transport_error",
+                        tool: toolName,
+                        surface: extractTransportSurface(err),
+                        error_class: err.name ?? "Error",
+                        status: extractTransportStatus(err),
+                    };
+                });
+            }
+            throw err;
+        }
+    };
+    return wrapped;
+}
+//# sourceMappingURL=diagnostic.js.map

package/dist/diagnostic.js.map

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