@hoyongjin/gitbook-mcp 1.0.0

package/dist/gitbook/errors.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Error classification for the GitBook API. Turns a thrown error (a
+ * @gitbook/api `GitBookAPIError`, an aborted/timed-out request, or any other
+ * failure) into a stable, non-leaky shape the tool layer can surface to the
+ * model as an `isError` result. The raw token is never included.
+ */
+export type ErrorKind = "auth" | "forbidden" | "not_found" | "conflict" | "rate_limit" | "validation" | "server" | "timeout" | "network" | "unknown";
+export interface ClassifiedError {
+    readonly kind: ErrorKind;
+    readonly status: number | undefined;
+    /** Safe, human-readable message (no secrets). */
+    readonly message: string;
+    /** Whether a retry could plausibly succeed (informational; the fetch layer already retried). */
+    readonly retryable: boolean;
+}
+export declare function classifyError(err: unknown): ClassifiedError;
+/** A single-line safe summary, e.g. for a tool's isError text. */
+export declare function describeError(err: unknown): string;

package/dist/gitbook/errors.js

@@ -0,0 +1,79 @@
+/**
+ * Error classification for the GitBook API. Turns a thrown error (a
+ * @gitbook/api `GitBookAPIError`, an aborted/timed-out request, or any other
+ * failure) into a stable, non-leaky shape the tool layer can surface to the
+ * model as an `isError` result. The raw token is never included.
+ */
+function isGitBookApiError(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        err.name === "GitBookAPIError" &&
+        typeof err.code === "number");
+}
+function kindForStatus(status) {
+    switch (status) {
+        case 400:
+            return "validation";
+        case 401:
+            return "auth";
+        case 403:
+            return "forbidden";
+        case 404:
+            return "not_found";
+        case 409:
+            return "conflict";
+        case 429:
+            return "rate_limit";
+        default:
+            return status >= 500 ? "server" : "unknown";
+    }
+}
+const FRIENDLY = {
+    auth: "Authentication failed — check GITBOOK_TOKEN (it may be invalid or revoked).",
+    forbidden: "The token lacks permission for this resource.",
+    not_found: "The requested resource was not found.",
+    conflict: "The request conflicts with the current state (e.g. the change request was already merged).",
+    rate_limit: "GitBook rate limit hit; the request was retried but kept being throttled.",
+    validation: "The request was rejected as invalid — check the arguments.",
+    server: "GitBook returned a server error.",
+    timeout: "The request to GitBook timed out.",
+    network: "Could not reach the GitBook API (network error).",
+    unknown: "The GitBook API request failed.",
+};
+export function classifyError(err) {
+    if (isGitBookApiError(err)) {
+        const status = err.code;
+        const kind = kindForStatus(status);
+        const detail = err.errorMessage ?? err.message ?? "";
+        return {
+            kind,
+            status,
+            message: detail ? `${FRIENDLY[kind]} (${detail})` : FRIENDLY[kind],
+            retryable: kind === "rate_limit" || kind === "server",
+        };
+    }
+    if (err instanceof Error) {
+        // Our own deliberate validation errors (import-URL guard; tool input guards
+        // like search's orgId/spaceId mutual-exclusion). Preserve their message —
+        // these are written FOR the model and must reach it verbatim, not be flattened
+        // to the generic "unknown" string.
+        if (err.name === "ImportUrlError" || err.name === "ToolInputError") {
+            return { kind: "validation", status: undefined, message: err.message, retryable: false };
+        }
+        // AbortError from our timeout controller.
+        if (err.name === "AbortError" || err.name === "TimeoutError") {
+            return { kind: "timeout", status: undefined, message: FRIENDLY.timeout, retryable: true };
+        }
+        // Node fetch failures surface as TypeError("fetch failed") with a `.cause`.
+        if (err.name === "TypeError" ||
+            /fetch failed|ENOTFOUND|ECONNREFUSED|ETIMEDOUT/.test(err.message)) {
+            return { kind: "network", status: undefined, message: FRIENDLY.network, retryable: true };
+        }
+    }
+    return { kind: "unknown", status: undefined, message: FRIENDLY.unknown, retryable: false };
+}
+/** A single-line safe summary, e.g. for a tool's isError text. */
+export function describeError(err) {
+    const c = classifyError(err);
+    return c.status ? `[${c.status} ${c.kind}] ${c.message}` : `[${c.kind}] ${c.message}`;
+}

package/dist/gitbook/import-url.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Scheme + credential validation for the `gitbook_import_content` source URL.
+ * We require http(s) and forbid embedded credentials (`user:pass@`): the former
+ * blocks non-web schemes (file:, gopher:, …); the latter stops a third-party
+ * credential the user pasted into the URL from being echoed back (GitBook
+ * returns the source URL in the import run, which the tool surfaces to the model).
+ *
+ * NOTE — this is NOT a full SSRF guard. This process never resolves or fetches
+ * the URL; GitBook does, server-side. So protection against internal / loopback
+ * / cloud-metadata targets (127.0.0.1, 169.254.169.254, etc.) is GitBook's
+ * responsibility, not something a host/IP denylist here could enforce.
+ *
+ * `isSafeImportUrl` is used as a zod refinement at the tool boundary (so a bad
+ * value becomes a clean validation error), and `assertSafeImportUrl` is used in
+ * the client as defense-in-depth and to normalize the URL.
+ */
+export declare class ImportUrlError extends Error {
+    readonly name = "ImportUrlError";
+}
+/** Predicate form for zod `.refine`. Returns false for any unsafe/invalid URL. */
+export declare function isSafeImportUrl(raw: string): boolean;
+/** Throwing/normalizing form for the client. Returns the normalized URL string. */
+export declare function assertSafeImportUrl(raw: string): string;

package/dist/gitbook/import-url.js

@@ -0,0 +1,51 @@
+/**
+ * Scheme + credential validation for the `gitbook_import_content` source URL.
+ * We require http(s) and forbid embedded credentials (`user:pass@`): the former
+ * blocks non-web schemes (file:, gopher:, …); the latter stops a third-party
+ * credential the user pasted into the URL from being echoed back (GitBook
+ * returns the source URL in the import run, which the tool surfaces to the model).
+ *
+ * NOTE — this is NOT a full SSRF guard. This process never resolves or fetches
+ * the URL; GitBook does, server-side. So protection against internal / loopback
+ * / cloud-metadata targets (127.0.0.1, 169.254.169.254, etc.) is GitBook's
+ * responsibility, not something a host/IP denylist here could enforce.
+ *
+ * `isSafeImportUrl` is used as a zod refinement at the tool boundary (so a bad
+ * value becomes a clean validation error), and `assertSafeImportUrl` is used in
+ * the client as defense-in-depth and to normalize the URL.
+ */
+export class ImportUrlError extends Error {
+    name = "ImportUrlError";
+}
+/** Predicate form for zod `.refine`. Returns false for any unsafe/invalid URL. */
+export function isSafeImportUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        return false;
+    if (url.username !== "" || url.password !== "")
+        return false;
+    return true;
+}
+/** Throwing/normalizing form for the client. Returns the normalized URL string. */
+export function assertSafeImportUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new ImportUrlError("sourceUrl is not a valid URL.");
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new ImportUrlError(`sourceUrl must use http(s); got scheme "${url.protocol.replace(":", "")}".`);
+    }
+    if (url.username !== "" || url.password !== "") {
+        throw new ImportUrlError("sourceUrl must not contain embedded credentials (user:pass@).");
+    }
+    return url.toString();
+}

package/dist/gitbook/resilient-fetch.d.ts

@@ -0,0 +1,42 @@
+import type { Logger } from "../logger.js";
+/**
+ * A `fetch`-shaped wrapper that adds per-attempt timeouts and bounded retries
+ * with backoff. Injected into the @gitbook/api client via its `serviceBinding`,
+ * so every one of the client's ~200 methods gets resilience for free.
+ *
+ * Retry policy (grounded in GitBook's documented behavior):
+ *   - Retry ONLY on HTTP 429 and 5xx, and on transport/timeout errors.
+ *   - Never retry other 4xx (they are deterministic client errors).
+ *   - IDEMPOTENCY: a 5xx or transport/timeout may arrive AFTER the server already
+ *     applied the request, so retrying a non-idempotent write would duplicate the
+ *     side effect (a second change request, comment, or import run). We therefore
+ *     retry 5xx/transport errors ONLY for idempotent methods (GET/HEAD/PUT/…).
+ *     429 is the exception: it means the request was rejected by rate limiting
+ *     BEFORE processing, so it is safe to retry for any method (including POST).
+ *   - On a retryable response, honor `Retry-After` (seconds or HTTP-date) and,
+ *     failing that, `X-RateLimit-Reset` (UTC epoch seconds) — for 503s during
+ *     maintenance as well as 429s. If the server asks us to wait longer than
+ *     `maxHeaderDelayMs`, stop retrying and return the response to the caller
+ *     (better than hanging a tool call or hammering the limit).
+ *   - Otherwise exponential backoff with FULL jitter: random(0, min(cap, base*2^n)).
+ *   - Respect a caller-supplied AbortSignal (do not retry a caller abort, and
+ *     short-circuit if the caller aborts during a backoff sleep).
+ */
+export interface ResilientFetchOptions {
+    timeoutMs: number;
+    maxRetries: number;
+    /** Cap concurrent in-flight requests (undefined = unbounded). */
+    maxConcurrency?: number;
+    logger?: Logger;
+    /** Injectable seams for tests. */
+    fetchImpl?: typeof fetch;
+    sleepImpl?: (ms: number) => Promise<void>;
+    randomImpl?: () => number;
+    nowMsImpl?: () => number;
+    /** Backoff base/cap in ms (defaults: 500 / 30000). */
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    /** Max server-directed (Retry-After/Reset) wait we will honor (default 60000). */
+    maxHeaderDelayMs?: number;
+}
+export declare function createResilientFetch(opts: ResilientFetchOptions): typeof fetch;

package/dist/gitbook/resilient-fetch.js

@@ -0,0 +1,155 @@
+import { createLimiter } from "../limiter.js";
+import { metrics } from "../metrics.js";
+const RETRYABLE_STATUS = (status) => status === 429 || status >= 500;
+/**
+ * Safe/idempotent methods per RFC 9110 — retrying them on a 5xx/transport error
+ * cannot duplicate a side effect. POST/PATCH are excluded: their 5xx/timeout
+ * retries are suppressed so a write that may have landed is not replayed.
+ */
+const IDEMPOTENT_METHODS = new Set(["GET", "HEAD", "OPTIONS", "PUT", "DELETE", "TRACE"]);
+function isIdempotentMethod(init) {
+    const method = (init?.method ?? "GET").toUpperCase();
+    return IDEMPOTENT_METHODS.has(method);
+}
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Parse Retry-After (delta-seconds or HTTP-date) into ms, or undefined. */
+function parseRetryAfter(value, nowMs) {
+    if (!value)
+        return undefined;
+    const secs = Number(value);
+    if (Number.isFinite(secs))
+        return Math.max(0, secs * 1000);
+    const date = Date.parse(value);
+    if (Number.isFinite(date))
+        return Math.max(0, date - nowMs);
+    return undefined;
+}
+/** Parse X-RateLimit-Reset (UTC epoch seconds) into ms-until-reset, or undefined. */
+function parseRateLimitReset(value, nowMs) {
+    if (!value)
+        return undefined;
+    const epochSecs = Number(value);
+    if (!Number.isFinite(epochSecs))
+        return undefined;
+    return Math.max(0, epochSecs * 1000 - nowMs);
+}
+function abortError(signal) {
+    return signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+}
+export function createResilientFetch(opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const sleep = opts.sleepImpl ?? defaultSleep;
+    const random = opts.randomImpl ?? Math.random;
+    const nowMs = opts.nowMsImpl ?? Date.now;
+    const base = opts.baseDelayMs ?? 500;
+    const cap = opts.maxDelayMs ?? 30_000;
+    const maxHeaderDelayMs = opts.maxHeaderDelayMs ?? 60_000;
+    const { maxRetries, timeoutMs, logger } = opts;
+    // Bound concurrent in-flight requests so a fanned-out caller cannot exhaust
+    // GitBook's rate limit in one burst. A slot is held from request initiation
+    // until the response HEADERS arrive (not full body transfer — @gitbook/api
+    // reads the body downstream), and is released across backoff sleeps so retries
+    // don't starve the pool. Adequate for GitBook's small JSON responses.
+    const limiter = opts.maxConcurrency
+        ? createLimiter(opts.maxConcurrency)
+        : undefined;
+    const backoff = (attempt) => random() * Math.min(cap, base * 2 ** attempt);
+    /** Delay for a retryable response, or `null` to stop retrying and return it. */
+    const responseDelay = (res, attempt) => {
+        // Honor an explicit server directive on ANY retryable status — a 503 during
+        // maintenance/overload commonly carries Retry-After too, not just a 429.
+        const headerDelay = parseRetryAfter(res.headers.get("retry-after"), nowMs()) ??
+            parseRateLimitReset(res.headers.get("x-ratelimit-reset"), nowMs());
+        if (headerDelay === undefined)
+            return backoff(attempt);
+        // Honor the server directive, but not beyond what a tool call can wait for.
+        return headerDelay > maxHeaderDelayMs ? null : headerDelay;
+    };
+    const resilientFetch = async (input, init) => {
+        const callerSignal = init?.signal ?? undefined;
+        const idempotent = isIdempotentMethod(init);
+        for (let attempt = 0;; attempt++) {
+            // The per-attempt timeout is armed INSIDE doFetch — i.e. only once the
+            // limiter has granted a slot and the request is actually in flight — so a
+            // request that waits in the concurrency queue does not burn its timeout
+            // budget (which would spuriously abort it before the network call runs).
+            const doFetch = async () => {
+                const timeoutController = new AbortController();
+                const timer = setTimeout(() => timeoutController.abort(), timeoutMs);
+                const signal = callerSignal
+                    ? AbortSignal.any([callerSignal, timeoutController.signal])
+                    : timeoutController.signal;
+                try {
+                    return await fetchImpl(input, { ...init, signal });
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+            };
+            // Only the fetch itself is inside the try — a later sleep() rejection must
+            // NOT be misclassified as a retryable transport error.
+            let res;
+            let caught;
+            try {
+                res = limiter ? await limiter.run(doFetch) : await doFetch();
+            }
+            catch (err) {
+                caught = err;
+            }
+            if (res) {
+                if (!RETRYABLE_STATUS(res.status) || attempt >= maxRetries)
+                    return res;
+                // Non-idempotent write: only a 429 is safe to replay (the request was
+                // rejected before processing). A 5xx may have applied — return it so the
+                // caller sees the failure rather than risking a duplicate side effect.
+                if (!idempotent && res.status !== 429)
+                    return res;
+                const delay = responseDelay(res, attempt);
+                if (delay === null)
+                    return res; // server wants longer than we'll wait
+                if (res.status === 429)
+                    metrics.inc("gitbook_rate_limited_total");
+                metrics.inc("gitbook_fetch_retries_total", {
+                    reason: res.status === 429 ? "rate_limit" : "server",
+                });
+                logger?.warn("gitbook request retrying", {
+                    status: res.status,
+                    attempt: attempt + 1,
+                    maxRetries,
+                    delayMs: Math.round(delay),
+                });
+                await res.body?.cancel().catch(() => { }); // free the connection
+                if (callerSignal?.aborted)
+                    throw abortError(callerSignal); // pre-sleep guard
+                await sleep(delay);
+                if (callerSignal?.aborted)
+                    throw abortError(callerSignal);
+                continue;
+            }
+            // Transport/timeout error.
+            if (callerSignal?.aborted)
+                throw caught; // caller abort — never retry
+            // A non-idempotent write that errored may still have reached GitBook (a
+            // timed-out POST can land server-side); do not replay it.
+            if (!idempotent)
+                throw caught;
+            if (attempt >= maxRetries)
+                throw caught;
+            const delay = backoff(attempt);
+            const reason = caught instanceof Error && caught.name === "AbortError" ? "timeout" : "network";
+            metrics.inc("gitbook_fetch_retries_total", { reason });
+            logger?.warn("gitbook request error, retrying", {
+                attempt: attempt + 1,
+                maxRetries,
+                delayMs: Math.round(delay),
+                reason,
+            });
+            await sleep(delay);
+            if (callerSignal?.aborted)
+                throw abortError(callerSignal);
+        }
+    };
+    return resilientFetch;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { ConfigError, loadConfig } from "./config.js";
+import { createLogger } from "./logger.js";
+import { runStdio } from "./transports/stdio.js";
+import { runHttp } from "./transports/http.js";
+import { SERVER_NAME, SERVER_VERSION } from "./version.js";
+function getConfig() {
+    try {
+        return loadConfig();
+    }
+    catch (err) {
+        const msg = err instanceof ConfigError ? err.message : String(err);
+        process.stderr.write(`[gitbook-mcp] ${msg}\n`);
+        process.exit(1);
+    }
+}
+async function main() {
+    const config = getConfig();
+    const logger = createLogger({ level: config.logLevel, redactSecret: config.token });
+    logger.info("starting", {
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+        transport: config.transport,
+        readOnly: config.readOnly,
+    });
+    const running = config.transport === "http" ? await runHttp(config, logger) : await runStdio(config, logger);
+    let shuttingDown = false;
+    const shutdown = async (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        logger.info("shutting down", { signal });
+        try {
+            // Bound the close so a stuck transport still lets the process exit.
+            await Promise.race([
+                running.close(),
+                new Promise((resolve) => setTimeout(resolve, 5000)),
+            ]);
+        }
+        catch (err) {
+            logger.error("shutdown error", { error: err instanceof Error ? err.message : String(err) });
+        }
+        process.exit(0);
+    };
+    process.on("SIGINT", () => void shutdown("SIGINT"));
+    process.on("SIGTERM", () => void shutdown("SIGTERM"));
+    // Last-resort diagnostics so a long-running server never dies silently.
+    process.on("unhandledRejection", (reason) => {
+        logger.error("unhandledRejection", {
+            error: reason instanceof Error ? (reason.stack ?? reason.message) : String(reason),
+        });
+    });
+    process.on("uncaughtException", (err) => {
+        logger.error("uncaughtException", { error: err.stack ?? err.message });
+        process.exit(1);
+    });
+}
+main().catch((err) => {
+    process.stderr.write(`[gitbook-mcp] fatal: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`);
+    process.exit(1);
+});

package/dist/limiter.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A minimal async concurrency limiter (counting semaphore). Bounds how many
+ * `run`-wrapped operations execute at once; the rest queue FIFO until a slot
+ * frees. Used to cap concurrent outbound GitBook HTTP requests so a fanned-out
+ * model cannot exhaust the upstream rate limit in one burst.
+ */
+export interface Limiter {
+    run<T>(fn: () => Promise<T>): Promise<T>;
+    readonly active: number;
+    readonly pending: number;
+}
+export declare function createLimiter(maxConcurrency: number): Limiter;

package/dist/limiter.js

@@ -0,0 +1,44 @@
+export function createLimiter(maxConcurrency) {
+    if (!Number.isInteger(maxConcurrency) || maxConcurrency < 1) {
+        throw new RangeError(`maxConcurrency must be a positive integer (got ${maxConcurrency})`);
+    }
+    let active = 0;
+    const queue = [];
+    const acquire = () => {
+        if (active < maxConcurrency) {
+            active++;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => queue.push(resolve));
+    };
+    const release = () => {
+        const next = queue.shift();
+        if (next) {
+            // Hand the slot directly to the next waiter (active stays unchanged).
+            next();
+        }
+        else {
+            active--;
+        }
+    };
+    return {
+        run(fn) {
+            return acquire().then(() => {
+                try {
+                    return Promise.resolve(fn()).finally(release);
+                }
+                catch (err) {
+                    // Synchronous throw from fn(): release the slot before propagating.
+                    release();
+                    throw err;
+                }
+            });
+        },
+        get active() {
+            return active;
+        },
+        get pending() {
+            return queue.length;
+        },
+    };
+}

package/dist/logger.d.ts

@@ -0,0 +1,20 @@
+import type { LogLevel } from "./config.js";
+export type LogFields = Record<string, unknown>;
+export interface Logger {
+    debug(msg: string, fields?: LogFields): void;
+    info(msg: string, fields?: LogFields): void;
+    warn(msg: string, fields?: LogFields): void;
+    error(msg: string, fields?: LogFields): void;
+    child(bindings: LogFields): Logger;
+}
+/**
+ * Scrub a literal secret (the token) out of a string. Shared with the tool/error
+ * path. The >=6 floor avoids masking trivially-short substrings; config enforces
+ * the same minimum on GITBOOK_TOKEN so an accepted token is never below it.
+ */
+export declare function redactSecret(value: string, secret: string | undefined): string;
+export declare function createLogger(opts: {
+    level: LogLevel;
+    /** Literal secret to scrub from all log strings (the GitBook token). */
+    redactSecret?: string;
+}): Logger;

package/dist/logger.js

@@ -0,0 +1,92 @@
+import { getRequestContext } from "./request-context.js";
+/**
+ * Minimal structured logger. Writes one JSON object per line to STDERR.
+ *
+ * stderr is mandatory: in stdio transport, stdout carries the JSON-RPC frames,
+ * so any stray stdout write corrupts the protocol. We therefore never use
+ * `console.log` anywhere in this server.
+ *
+ * Secrets are redacted: the configured token's literal value is scrubbed from
+ * every emitted string, and any field whose key looks secret is masked.
+ */
+const LEVEL_ORDER = { debug: 10, info: 20, warn: 30, error: 40 };
+const SECRET_KEY = /(token|authorization|auth|secret|password|apikey|api_key)/i;
+/**
+ * Scrub a literal secret (the token) out of a string. Shared with the tool/error
+ * path. The >=6 floor avoids masking trivially-short substrings; config enforces
+ * the same minimum on GITBOOK_TOKEN so an accepted token is never below it.
+ */
+export function redactSecret(value, secret) {
+    if (secret && secret.length >= 6 && value.includes(secret)) {
+        return value.split(secret).join("[REDACTED]");
+    }
+    return value;
+}
+function maskSecrets(value, literalSecret) {
+    if (typeof value === "string") {
+        return redactSecret(value, literalSecret);
+    }
+    if (Array.isArray(value))
+        return value.map((v) => maskSecrets(v, literalSecret));
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = SECRET_KEY.test(k) ? "[REDACTED]" : maskSecrets(v, literalSecret);
+        }
+        return out;
+    }
+    return value;
+}
+class StderrLogger {
+    minLevel;
+    literalSecret;
+    bindings;
+    constructor(minLevel, literalSecret, bindings = {}) {
+        this.minLevel = minLevel;
+        this.literalSecret = literalSecret;
+        this.bindings = bindings;
+    }
+    emit(level, msg, fields) {
+        if (LEVEL_ORDER[level] < LEVEL_ORDER[this.minLevel])
+            return;
+        // Stamp the active request correlation (requestId/tool) so a tool call and
+        // the GitBook fetch lines it spawns share an id. Explicit fields win.
+        const reqCtx = getRequestContext();
+        const record = {
+            level,
+            time: new Date().toISOString(),
+            name: "gitbook-mcp",
+            msg,
+            ...(reqCtx
+                ? { requestId: reqCtx.requestId, ...(reqCtx.tool ? { tool: reqCtx.tool } : {}) }
+                : {}),
+            ...this.bindings,
+            ...fields,
+        };
+        const safe = maskSecrets(record, this.literalSecret);
+        try {
+            process.stderr.write(`${JSON.stringify(safe)}\n`);
+        }
+        catch {
+            // Last-resort: never let logging throw and take down a request.
+        }
+    }
+    debug(msg, fields) {
+        this.emit("debug", msg, fields);
+    }
+    info(msg, fields) {
+        this.emit("info", msg, fields);
+    }
+    warn(msg, fields) {
+        this.emit("warn", msg, fields);
+    }
+    error(msg, fields) {
+        this.emit("error", msg, fields);
+    }
+    child(bindings) {
+        return new StderrLogger(this.minLevel, this.literalSecret, { ...this.bindings, ...bindings });
+    }
+}
+export function createLogger(opts) {
+    return new StderrLogger(opts.level, opts.redactSecret);
+}

package/dist/metrics.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Minimal in-process metrics — no external dependency. A single process-global
+ * registry, scraped via `GET /metrics` on the HTTP transport in Prometheus text
+ * exposition format. Counters are monotonic; gauges can move both ways.
+ *
+ * Tool/fetch/transport code increments via the exported `metrics` singleton.
+ * Tests call `metrics.reset()` in a `beforeEach` to isolate. Label values are
+ * only ever fixed identifiers we control (tool names, error kinds, retry
+ * reasons), so they need no escaping; we still reject characters that would
+ * break the exposition format defensively.
+ */
+export type MetricLabels = Record<string, string>;
+declare class Metrics {
+    private series;
+    /** Increment a monotonic counter (default by 1). */
+    inc(name: string, labels?: MetricLabels, by?: number): void;
+    /** Set a gauge to an absolute value. */
+    setGauge(name: string, value: number, labels?: MetricLabels): void;
+    /** Render the registry in Prometheus text exposition format. */
+    render(): string;
+    /** Test seam: clear all series. */
+    reset(): void;
+}
+export declare const metrics: Metrics;
+export type { Metrics };