viafrei 0.0.2 → 1.3.12

package/dist/bridge.js

@@ -0,0 +1,242 @@
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { isJSONRPCErrorResponse, isJSONRPCRequest, isJSONRPCResultResponse } from '@modelcontextprotocol/sdk/types.js';
+import { EXIT } from './config.js';
+import { createFetch } from './fetch.js';
+import { describeFailure } from './failure.js';
+/** JSON-RPC error code we return when the relay itself could not deliver. */
+const RELAY_FAILED = -32011;
+/**
+ * How many failures in a row, with nothing succeeding in between, mean the
+ * endpoint is gone rather than having a moment.
+ *
+ * An established session is allowed to wobble - a dropped event stream comes
+ * back, a proxy restarts. It is not allowed to be dead for ever in silence:
+ * this bridge is a child process of an MCP client, and a child that has stopped
+ * working must exit so the client can say so, not sit there warning.
+ */
+const DEAD_AFTER_CONSECUTIVE_FAILURES = 3;
+/** The SDK's own words for "I have stopped trying to reopen the stream". */
+const GAVE_UP_RECONNECTING = /Maximum reconnection attempts/iu;
+/** HTTP statuses that mean the session this bridge holds no longer exists. */
+const SESSION_GONE = new Set([404, 410]);
+function readProtocolVersion(value) {
+    if (value !== null && typeof value === 'object') {
+        const version = value.protocolVersion;
+        if (typeof version === 'string') {
+            return version;
+        }
+    }
+    return undefined;
+}
+/**
+ * Pull whatever the server said about versions out of an `initialize` error.
+ * Servers differ; we look where they actually put it rather than insisting on
+ * one shape and reporting nothing when it is a different one.
+ */
+function readSupportedVersions(data) {
+    if (data === null || typeof data !== 'object') {
+        return [];
+    }
+    const record = data;
+    const candidates = [record['supported'], record['supportedVersions'], record['supported_versions'], record['protocolVersion']];
+    const versions = [];
+    for (const candidate of candidates) {
+        if (typeof candidate === 'string') {
+            versions.push(candidate);
+        }
+        else if (Array.isArray(candidate)) {
+            versions.push(...candidate.filter((entry) => typeof entry === 'string'));
+        }
+    }
+    return [...new Set(versions)];
+}
+/**
+ * Relay every JSON-RPC message between a local stdio client and a remote
+ * Streamable-HTTP MCP endpoint, in both directions, unchanged.
+ *
+ * The bridge is deliberately a *message* relay and not a client/server pair
+ * that re-implements the protocol: it never has an opinion about a method it
+ * has not heard of, so a tool added on the server works here the same day
+ * without a release. The only messages it looks inside are `initialize` and its
+ * answer - because the session's protocol version has to end up on the HTTP
+ * headers, and because a version the server cannot speak deserves a sentence
+ * rather than a stack trace.
+ */
+export async function startBridge(options, hooks) {
+    const remote = new StreamableHTTPClientTransport(new URL(options.url), {
+        fetch: createFetch(options.timeoutMs),
+        requestInit: { headers: { ...options.headers } }
+    });
+    const input = process.stdin;
+    const local = new StdioServerTransport(input, process.stdout);
+    const pendingInitialize = new Map();
+    let initialized = false;
+    let closing = false;
+    let finished = false;
+    /**
+     * The SDK transport calls `onerror` *and* rejects the `send()` promise for
+     * the same failure, and `onerror` runs first. Counting the sends in flight
+     * lets the rejection path own that failure - it is the only one that knows
+     * which request failed and can answer the client - and leaves `onerror` for
+     * the failures nothing is waiting on, such as the event stream dropping.
+     */
+    let sendsInFlight = 0;
+    /** Reset by anything arriving from the endpoint; see the constant above. */
+    let consecutiveFailures = 0;
+    const finish = (line, exitCode) => {
+        if (finished) {
+            return;
+        }
+        finished = true;
+        hooks.fatal(line, exitCode);
+    };
+    const close = async () => {
+        if (closing) {
+            return;
+        }
+        closing = true;
+        await Promise.allSettled([remote.close(), local.close()]);
+    };
+    /** Tell the local client that a request could not be delivered. */
+    const replyRelayFailure = async (id, line) => {
+        try {
+            await local.send({ jsonrpc: '2.0', id, error: { code: RELAY_FAILED, message: line } });
+        }
+        catch {
+            // The local client is gone; the shutdown path below handles it.
+        }
+    };
+    // ---- local (stdio client) -> remote (Streamable HTTP) -------------------
+    local.onmessage = (message) => {
+        const isInitialize = isJSONRPCRequest(message) && message.method === 'initialize';
+        if (isInitialize && isJSONRPCRequest(message)) {
+            pendingInitialize.set(message.id, { requested: readProtocolVersion(message.params) });
+        }
+        sendsInFlight += 1;
+        void remote
+            .send(message)
+            .catch(async (error) => {
+            const failure = describeFailure(error, options.url);
+            if (isInitialize) {
+                // Nothing works from here, and the client is waiting on this
+                // one answer. Tell it, then say it once and stop.
+                if (isJSONRPCRequest(message)) {
+                    await replyRelayFailure(message.id, failure.line);
+                }
+                finish(failure.line, failure.exitCode);
+                return;
+            }
+            hooks.warn(failure.line);
+            if (isJSONRPCRequest(message)) {
+                await replyRelayFailure(message.id, failure.line);
+            }
+            if (failure.status !== undefined && SESSION_GONE.has(failure.status)) {
+                // The server has forgotten this session. Nothing sent from
+                // here can work again, and the client cannot re-initialize
+                // through a bridge that is still pretending.
+                finish(`viafrei: ${options.url} no longer knows this session (HTTP ${failure.status}) - it expired or the server restarted; start the client's connection again`, EXIT.REFUSED);
+                return;
+            }
+            noteFailure(failure);
+        })
+            .finally(() => {
+            sendsInFlight -= 1;
+        });
+    };
+    // ---- remote (Streamable HTTP) -> local (stdio client) -------------------
+    remote.onmessage = (message) => {
+        // The endpoint is alive: whatever went wrong before is over.
+        consecutiveFailures = 0;
+        const id = 'id' in message ? message.id : undefined;
+        const pending = id === undefined ? undefined : pendingInitialize.get(id);
+        let fatalAfterRelay;
+        if (pending !== undefined && id !== undefined) {
+            pendingInitialize.delete(id);
+            if (isJSONRPCResultResponse(message)) {
+                const served = readProtocolVersion(message.result);
+                if (served !== undefined) {
+                    remote.setProtocolVersion?.(served);
+                    initialized = true;
+                    if (pending.requested !== undefined && served !== pending.requested) {
+                        hooks.warn(`viafrei: ${options.url} speaks MCP protocol ${served}, this client asked for ${pending.requested}; relaying the server's answer unchanged`);
+                    }
+                }
+            }
+            else if (isJSONRPCErrorResponse(message)) {
+                const supported = readSupportedVersions(message.error.data);
+                const spoken = supported.length > 0 ? `the server speaks ${supported.join(', ')}` : `the server did not say which versions it speaks`;
+                fatalAfterRelay = `viafrei: ${options.url} rejected MCP protocol version ${pending.requested ?? '(unspecified)'}; ${spoken}`;
+            }
+        }
+        void local.send(message).then(() => {
+            if (fatalAfterRelay !== undefined) {
+                finish(fatalAfterRelay, EXIT.PROTOCOL);
+            }
+        }, (error) => {
+            hooks.warn(`viafrei: could not write to the local client: ${error instanceof Error ? error.message : String(error)}`);
+        });
+    };
+    /**
+     * Count one failure the session survived - and stop if they stop stopping.
+     *
+     * Without this a permanently dead endpoint produced a warning per event and
+     * nothing else, for ever: the documented exit 3 never came, and the client
+     * kept a bridge that could not relay.
+     */
+    const noteFailure = (failure) => {
+        consecutiveFailures += 1;
+        if (consecutiveFailures >= DEAD_AFTER_CONSECUTIVE_FAILURES) {
+            finish(`viafrei: ${options.url} has failed ${consecutiveFailures} times in a row with nothing succeeding in between - giving up. Last failure: ${failure.line.replace(/^viafrei: /u, '')}`, failure.exitCode);
+        }
+    };
+    remote.onerror = (error) => {
+        if (closing || sendsInFlight > 0) {
+            return;
+        }
+        const failure = describeFailure(error, options.url);
+        if (!initialized) {
+            finish(failure.line, failure.exitCode);
+            return;
+        }
+        if (GAVE_UP_RECONNECTING.test(error.message)) {
+            // The SDK has run out of reconnection attempts. The session is up on
+            // paper and dead in fact; say which, once, and exit.
+            finish(`viafrei: lost the event stream from ${options.url} and could not reopen it - the endpoint is not answering any more`, EXIT.UNREACHABLE);
+            return;
+        }
+        // The session is up; a stream can drop and come back. Say so once per
+        // event, keep relaying - but keep count.
+        hooks.warn(failure.line);
+        noteFailure(failure);
+    };
+    remote.onclose = () => {
+        if (closing) {
+            return;
+        }
+        finish(`viafrei: ${options.url} closed the session`, EXIT.UNREACHABLE);
+    };
+    local.onerror = (error) => {
+        hooks.warn(`viafrei: local stdio error: ${error.message}`);
+    };
+    local.onclose = () => {
+        if (closing) {
+            return;
+        }
+        finish('', EXIT.OK);
+    };
+    /**
+     * Closing stdin is how an MCP client says goodbye, and the transport does
+     * not watch for it. Without this the bridge outlives its client: the
+     * standalone event stream keeps the event loop alive and the process hangs
+     * around holding a session open on the server.
+     */
+    input.once('end', () => {
+        void close().finally(() => {
+            finish('', EXIT.OK);
+        });
+    });
+    await remote.start();
+    await local.start();
+    return { close };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv?: readonly string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+import { realpathSync, writeSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { startBridge } from './bridge.js';
+import { EXIT, UsageError, helpText, parseOptions } from './config.js';
+import { packageVersion } from './version.js';
+/**
+ * Both writers are synchronous on purpose: the next thing that happens is
+ * usually `process.exit`, and a buffered write to a pipe is lost when it does.
+ * A failure message that does not survive the exit is not a failure message.
+ */
+/** One line to stdout - `--help`, `--version`. Never protocol traffic. */
+function out(line) {
+    try {
+        writeSync(1, `${line}\n`);
+    }
+    catch {
+        // stdout is closed. Nothing to be done about it here.
+    }
+}
+/** One line to stderr. stdout belongs to the protocol; diagnostics go here. */
+function say(line) {
+    try {
+        writeSync(2, `${line}\n`);
+    }
+    catch {
+        // stderr is closed. There is nowhere left to complain.
+    }
+}
+export async function main(argv = process.argv.slice(2)) {
+    const version = packageVersion();
+    let options;
+    try {
+        options = parseOptions(argv);
+    }
+    catch (error) {
+        if (error instanceof UsageError) {
+            say(`viafrei: ${error.message}`);
+            process.exit(EXIT.USAGE);
+        }
+        throw error;
+    }
+    if (options.showHelp) {
+        out(helpText(version));
+        process.exit(EXIT.OK);
+    }
+    if (options.showVersion) {
+        out(version);
+        process.exit(EXIT.OK);
+    }
+    if (process.stdin.isTTY) {
+        say(`viafrei ${version}: speaking MCP over stdio, relaying to ${options.url}. This is meant to be started by an MCP client; "viafrei --help" explains the options.`);
+    }
+    let stopping = false;
+    const stop = (line, code) => {
+        if (stopping) {
+            return;
+        }
+        stopping = true;
+        if (line !== '') {
+            say(line);
+        }
+        process.exit(code);
+    };
+    const handle = await startBridge(options, {
+        warn: say,
+        fatal: (line, code) => {
+            stop(line, code);
+        }
+    });
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+        process.on(signal, () => {
+            void handle.close().finally(() => {
+                process.exit(EXIT.OK);
+            });
+        });
+    }
+}
+/**
+ * Was this file the program the user started, rather than something imported?
+ *
+ * The entry point is compared BOTH as given and resolved through symlinks,
+ * because the only way anybody actually starts this package is the symlink npm
+ * writes on install: `node_modules/.bin/viafrei -> ../viafrei/dist/cli.js`.
+ * Node resolves a module's own URL through symlinks, so `argv[1]` is the link
+ * while `import.meta.url` is its target; comparing only the unresolved form
+ * made this false for every real invocation, and the process then loaded the
+ * file, ran nothing and exited 0 in silence - which is what `npx viafrei` did.
+ * Comparing only the resolved form is not enough either: under
+ * `--preserve-symlinks-main` the module URL is the link, so both forms are
+ * offered and a match on either is the answer.
+ */
+function isEntryPoint() {
+    const entry = process.argv[1];
+    if (entry === undefined) {
+        return false;
+    }
+    const candidates = [pathToFileURL(entry).href];
+    try {
+        candidates.push(pathToFileURL(realpathSync(entry)).href);
+    }
+    catch {
+        // The entry point cannot be resolved on disk; the form given is all there is.
+    }
+    return candidates.includes(import.meta.url);
+}
+const invokedDirectly = isEntryPoint();
+if (invokedDirectly || process.env['VIAFREI_FORCE_CLI'] === '1') {
+    main().catch((error) => {
+        say(`viafrei: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(EXIT.UNEXPECTED);
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Configuration for the bridge: where it connects, with which headers, and how
+ * long it waits. Every value has exactly one definition here, so the default
+ * endpoint is never typed twice.
+ */
+/** The public ViaFrei MCP deployment. Written once. */
+export declare const DEFAULT_MCP_ORIGIN = "https://mcp.viafrei.de";
+/** The MCP endpoint path. Streamable HTTP only; SSE is deprecated and absent. */
+export declare const DEFAULT_MCP_PATH = "/mcp";
+/** The endpoint the bridge talks to unless told otherwise. */
+export declare const DEFAULT_MCP_URL: string;
+/** Environment variable that overrides the endpoint. */
+export declare const URL_ENV_VAR = "VIAFREI_MCP_URL";
+/** Environment variable that overrides the request timeout, in milliseconds. */
+export declare const TIMEOUT_ENV_VAR = "VIAFREI_MCP_TIMEOUT_MS";
+/** How long a single HTTP request may take before it is given up on. */
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * Exit codes. They are part of the interface: a supervisor should be able to
+ * tell "your network is down" from "you typed the flag wrong" without parsing
+ * English.
+ */
+export declare const EXIT: {
+    /** Clean shutdown: the client closed stdin. */
+    readonly OK: 0;
+    /** Anything we did not anticipate. */
+    readonly UNEXPECTED: 1;
+    /** Bad flag, bad value, bad URL. */
+    readonly USAGE: 2;
+    /** The endpoint could not be reached at all (DNS, refused, timeout). */
+    readonly UNREACHABLE: 3;
+    /** The endpoint answered, and the answer was a refusal (an HTTP status). */
+    readonly REFUSED: 4;
+    /** The endpoint speaks a protocol version this client cannot use. */
+    readonly PROTOCOL: 5;
+};
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+export interface Options {
+    /** The endpoint to relay to. */
+    url: string;
+    /** Extra HTTP headers sent with every request (for example an API key). */
+    headers: Record<string, string>;
+    /** Per-request timeout in milliseconds. The event stream is not timed out. */
+    timeoutMs: number;
+    /** Print the version and exit. */
+    showVersion: boolean;
+    /** Print the help text and exit. */
+    showHelp: boolean;
+}
+export declare class UsageError extends Error {
+}
+/**
+ * Parse argv (without `node` and the script) plus the environment.
+ *
+ * Precedence is the one people expect: a flag beats an environment variable,
+ * an environment variable beats the built-in default.
+ */
+export declare function parseOptions(argv: readonly string[], env?: NodeJS.ProcessEnv): Options;
+export declare function helpText(version: string): string;

package/dist/config.js

@@ -0,0 +1,177 @@
+/**
+ * Configuration for the bridge: where it connects, with which headers, and how
+ * long it waits. Every value has exactly one definition here, so the default
+ * endpoint is never typed twice.
+ */
+/** The public ViaFrei MCP deployment. Written once. */
+export const DEFAULT_MCP_ORIGIN = 'https://mcp.viafrei.de';
+/** The MCP endpoint path. Streamable HTTP only; SSE is deprecated and absent. */
+export const DEFAULT_MCP_PATH = '/mcp';
+/** The endpoint the bridge talks to unless told otherwise. */
+export const DEFAULT_MCP_URL = new URL(DEFAULT_MCP_PATH, DEFAULT_MCP_ORIGIN).toString();
+/** Environment variable that overrides the endpoint. */
+export const URL_ENV_VAR = 'VIAFREI_MCP_URL';
+/** Environment variable that overrides the request timeout, in milliseconds. */
+export const TIMEOUT_ENV_VAR = 'VIAFREI_MCP_TIMEOUT_MS';
+/** How long a single HTTP request may take before it is given up on. */
+export const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * Exit codes. They are part of the interface: a supervisor should be able to
+ * tell "your network is down" from "you typed the flag wrong" without parsing
+ * English.
+ */
+export const EXIT = {
+    /** Clean shutdown: the client closed stdin. */
+    OK: 0,
+    /** Anything we did not anticipate. */
+    UNEXPECTED: 1,
+    /** Bad flag, bad value, bad URL. */
+    USAGE: 2,
+    /** The endpoint could not be reached at all (DNS, refused, timeout). */
+    UNREACHABLE: 3,
+    /** The endpoint answered, and the answer was a refusal (an HTTP status). */
+    REFUSED: 4,
+    /** The endpoint speaks a protocol version this client cannot use. */
+    PROTOCOL: 5
+};
+export class UsageError extends Error {
+}
+/** Headers a caller may not set: they belong to the transport, not to the user. */
+const RESERVED_HEADERS = new Set([
+    'content-type',
+    'accept',
+    'mcp-session-id',
+    'mcp-protocol-version',
+    'content-length',
+    'host'
+]);
+function parseHeader(raw) {
+    const separator = raw.indexOf(':');
+    if (separator < 1) {
+        throw new UsageError(`--header expects "Name: value", got ${JSON.stringify(raw)}`);
+    }
+    const name = raw.slice(0, separator).trim();
+    const value = raw.slice(separator + 1).trim();
+    if (name === '') {
+        throw new UsageError(`--header expects "Name: value", got ${JSON.stringify(raw)}`);
+    }
+    if (RESERVED_HEADERS.has(name.toLowerCase())) {
+        throw new UsageError(`--header ${name} is set by the transport and cannot be overridden`);
+    }
+    return [name, value];
+}
+function parseTimeout(raw, source) {
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new UsageError(`${source} expects a positive number of milliseconds, got ${JSON.stringify(raw)}`);
+    }
+    return Math.floor(value);
+}
+function validateUrl(raw, source) {
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        throw new UsageError(`${source} is not a valid URL: ${JSON.stringify(raw)}`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new UsageError(`${source} must be http or https, got ${JSON.stringify(parsed.protocol)}`);
+    }
+    return parsed.toString();
+}
+/**
+ * Parse argv (without `node` and the script) plus the environment.
+ *
+ * Precedence is the one people expect: a flag beats an environment variable,
+ * an environment variable beats the built-in default.
+ */
+export function parseOptions(argv, env = process.env) {
+    const options = {
+        url: DEFAULT_MCP_URL,
+        headers: {},
+        timeoutMs: DEFAULT_TIMEOUT_MS,
+        showVersion: false,
+        showHelp: false
+    };
+    const urlFromEnv = env[URL_ENV_VAR];
+    if (urlFromEnv !== undefined && urlFromEnv.trim() !== '') {
+        options.url = validateUrl(urlFromEnv.trim(), URL_ENV_VAR);
+    }
+    const timeoutFromEnv = env[TIMEOUT_ENV_VAR];
+    if (timeoutFromEnv !== undefined && timeoutFromEnv.trim() !== '') {
+        options.timeoutMs = parseTimeout(timeoutFromEnv.trim(), TIMEOUT_ENV_VAR);
+    }
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        const next = () => {
+            const value = argv[index + 1];
+            if (value === undefined || value.startsWith('--')) {
+                throw new UsageError(`${argument} expects a value`);
+            }
+            index += 1;
+            return value;
+        };
+        if (argument === '--help' || argument === '-h') {
+            options.showHelp = true;
+        }
+        else if (argument === '--version' || argument === '-V') {
+            options.showVersion = true;
+        }
+        else if (argument === '--url') {
+            options.url = validateUrl(next(), '--url');
+        }
+        else if (argument.startsWith('--url=')) {
+            options.url = validateUrl(argument.slice('--url='.length), '--url');
+        }
+        else if (argument === '--header' || argument === '-H') {
+            const [name, value] = parseHeader(next());
+            options.headers[name] = value;
+        }
+        else if (argument.startsWith('--header=')) {
+            const [name, value] = parseHeader(argument.slice('--header='.length));
+            options.headers[name] = value;
+        }
+        else if (argument === '--timeout') {
+            options.timeoutMs = parseTimeout(next(), '--timeout');
+        }
+        else if (argument.startsWith('--timeout=')) {
+            options.timeoutMs = parseTimeout(argument.slice('--timeout='.length), '--timeout');
+        }
+        else {
+            throw new UsageError(`unknown argument ${JSON.stringify(argument)} - run "viafrei --help" for the list`);
+        }
+    }
+    return options;
+}
+export function helpText(version) {
+    return [
+        `viafrei ${version} - stdio<->Streamable-HTTP bridge for the ViaFrei MCP server`,
+        '',
+        'Usage:',
+        '  npx viafrei [options]',
+        '',
+        'The bridge speaks MCP over stdio to whatever started it and relays every',
+        'message to a Streamable-HTTP MCP endpoint, in both directions. It holds no',
+        'data, writes nothing outside the OS temp directory and sends no telemetry.',
+        '',
+        'Options:',
+        `  --url <url>          endpoint to relay to (default ${DEFAULT_MCP_URL})`,
+        '  --header "N: v"      extra HTTP header, repeatable (for an API key)',
+        `  --timeout <ms>       per-request timeout (default ${DEFAULT_TIMEOUT_MS} ms)`,
+        '  -V, --version        print the version and exit',
+        '  -h, --help           print this text and exit',
+        '',
+        'Environment:',
+        `  ${URL_ENV_VAR}      same as --url`,
+        `  ${TIMEOUT_ENV_VAR}  same as --timeout`,
+        '',
+        'Exit codes:',
+        `  ${EXIT.OK}  clean shutdown            ${EXIT.UNEXPECTED}  unexpected error`,
+        `  ${EXIT.USAGE}  bad usage                 ${EXIT.UNREACHABLE}  endpoint unreachable`,
+        `  ${EXIT.REFUSED}  endpoint refused          ${EXIT.PROTOCOL}  protocol version mismatch`,
+        '',
+        'Results carry an attribution line. Show it to the person reading the answer.',
+        'Documentation: https://viafrei.de'
+    ].join('\n');
+}

package/dist/failure.d.ts

@@ -0,0 +1,61 @@
+import { type ExitCode } from './config.js';
+/**
+ * A transport failure, reduced to the one line a human needs and the exit code
+ * a supervisor needs.
+ *
+ * The rule this file exists to keep: the user of an MCP client never sees a
+ * stack trace from us. They see the URL we tried and what came back.
+ */
+export interface Failure {
+    /** One line. No newlines, no stack, names the URL and what happened. */
+    line: string;
+    /** What the process should exit with if this failure is fatal. */
+    exitCode: ExitCode;
+    /** HTTP status, when the endpoint answered at all. */
+    status?: number;
+}
+/** True when the failure is worth exactly one more attempt. */
+export declare function isRetryable(error: unknown): boolean;
+/** Raised by the fetch wrapper when our own timeout fired. */
+export declare class RequestTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+export type RedirectRefusal = 'cross-origin' | 'no-location' | 'too-many';
+/**
+ * How many same-origin hops are a redirect, and how many are a loop.
+ *
+ * Defined here, next to the sentence that quotes it, and imported by the fetch
+ * wrapper that enforces it. It used to be defined in `src/fetch.ts` and typed
+ * out again as a literal in `redirectLine()`, which is a number in two places
+ * and therefore a number that can disagree with itself.
+ */
+export declare const MAX_REDIRECTS = 5;
+/**
+ * Raised by the fetch wrapper when a redirect was not followed.
+ *
+ * Every request carries the caller's `--header` values. A redirect is the
+ * server choosing where those go next, so the choice is made here instead: one
+ * origin is one trust boundary, and crossing it is refused out loud rather than
+ * followed quietly.
+ */
+export declare class RedirectRefusedError extends Error {
+    readonly reason: RedirectRefusal;
+    readonly from: string;
+    readonly to: string;
+    readonly httpStatus: number;
+    constructor(detail: {
+        reason: RedirectRefusal;
+        from: string;
+        to: string;
+        status: number;
+    });
+}
+/**
+ * Turn any thrown value into one line plus an exit code.
+ *
+ * Three outcomes, and the distinction is the point: the endpoint answered and
+ * said no (REFUSED), the endpoint never answered (UNREACHABLE), or something
+ * else entirely (UNEXPECTED).
+ */
+export declare function describeFailure(error: unknown, url: string): Failure;