@chrischall/mcp-utils 0.23.3 → 0.25.0

package/dist/healthcheck/index.d.ts

@@ -15,7 +15,11 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
  * question each answers: is there a credential at all, did the far side accept
  * it, and did the round-trip work.
  */
-export type CredentialHealthcheckArm = 'ok' | 'no_credential' | 'credential_rejected' | 'timeout' | 'http' | 'transport' | 'unknown';
+export type CredentialHealthcheckArm = 'ok' | 'no_credential' | 'credential_rejected'
+/** Credentials are fine; no session is live. See {@link sessionProbe}. */
+ | 'session_expired'
+/** A second factor is outstanding, so the far side is holding the sign-in. */
+ | 'verification_pending' | 'timeout' | 'http' | 'transport' | 'unknown';
 /** What a consumer's resolver reports. NEVER the credential value itself. */
 export interface CredentialState {
     /**
@@ -53,7 +57,11 @@ export interface RegisterCredentialHealthcheckToolArgs {
     prefix: string;
     /** Display host for the probe URL and hint copy, e.g. `'api.freshbooks.com'`. */
     hostLabel: string;
-    /** Optional path, for display only: the probe URL is `https://<hostLabel><probePath>`. */
+    /**
+     * Optional path, for display only: the probe URL is
+     * `https://<hostLabel>/<probePath>`, with the separator inserted only when
+     * `probePath` does not already begin with one.
+     */
     probePath?: string;
     /**
      * Resolve the credential the way the real tools do — same cache, same
@@ -68,7 +76,16 @@ export interface RegisterCredentialHealthcheckToolArgs {
      * are already set.
      */
     resolveCredential: () => Promise<CredentialState>;
-    /** One authenticated round-trip. Only called when a credential resolved. */
+    /**
+     * One authenticated round-trip. Only called when a credential resolved.
+     *
+     * **It reports failure only by THROWING.** A probe that resolves is reported
+     * healthy, whatever it resolved to — so a 2xx is not, on its own, proof of a
+     * session. A cookie-session portal answers a dead session with a login page
+     * served 200, or a redirect to one; a probe that hands either back reports
+     * `ok: true` and tells the caller to go debug a tool. {@link sessionProbe}
+     * builds a compliant probe from the one closure only the consumer can write.
+     */
     probeFn: () => Promise<unknown>;
     /**
      * Classify a thrown error into an arm, and optionally override the hint and
@@ -121,21 +138,133 @@ export interface CredentialHealthcheckResult {
     };
     hint: string;
 }
+/** The text result an MCP tool handler returns. */
+export type HealthcheckToolResult = {
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+};
+/** The credential arm's one-line description, shared with the adaptive tool. */
+export declare function credentialHealthcheckDescription(hostLabel: string): string;
 /**
- * Register `${prefix}_healthcheck` for a connector whose health is about a
- * CREDENTIAL rather than a browser bridge — OAuth connectors, API-key
- * connectors, and the fetchproxy MCPs that only BOOTSTRAP a token and then
- * talk to an API directly.
+ * The credential healthcheck's whole body, without the registration: what a
+ * connector reports when its health is about a CREDENTIAL rather than a browser
+ * bridge — OAuth connectors, API-key connectors, and the fetchproxy MCPs that
+ * only BOOTSTRAP a token and then talk to an API directly.
  *
  * It exists because those three failures are indistinguishable today and have
  * different fixes: nothing minted a credential, something minted one the far
  * side rejects, and the far side is simply down. The bridge helper
- * (`registerBridgeHealthcheckTool`, in `../fetchproxy/`) answers the equivalent question for
- * MCPs where every request rides the bridge.
+ * ({@link runBridgeHealthcheck}, in `../fetchproxy/`) answers the equivalent
+ * question for MCPs where every request rides the bridge.
  *
  * The probe is SKIPPED when no credential resolved — probing without one
  * produces a 401 that reads like a rejected credential and points at the wrong
  * fix.
+ *
+ * Split out from the registration so ONE tool can serve a server with two
+ * transports and choose between the arms per call
+ * (`registerAdaptiveHealthcheckTool`, in `../fetchproxy/`, which is where the
+ * bridge arm's optional peer dependency already lives).
+ * `registerCredentialHealthcheckTool` is unchanged and still the right choice
+ * for a server with only this arm.
+ */
+export declare function runCredentialHealthcheck(args: RegisterCredentialHealthcheckToolArgs): Promise<HealthcheckToolResult>;
+/**
+ * Register `${prefix}_healthcheck` for a connector whose health is about a
+ * CREDENTIAL rather than a browser bridge. The body is
+ * {@link runCredentialHealthcheck}.
  */
 export declare function registerCredentialHealthcheckTool(args: RegisterCredentialHealthcheckToolArgs): void;
+/**
+ * The probe reached the far side and it declined to serve the data — a login
+ * page, or a redirect to one. Its own class so a classifier can tell it apart
+ * from a network failure.
+ */
+export declare class SessionNotLiveError extends Error {
+    readonly hostLabel: string;
+    readonly detail: string;
+    constructor(hostLabel: string, detail: string);
+}
+/** A non-2xx from the far side, carrying the status the healthcheck reports. */
+export declare class ProbeHttpError extends Error {
+    readonly hostLabel: string;
+    readonly status: number;
+    constructor(hostLabel: string, status: number);
+}
+/** The minimum a {@link sessionProbe} request has to report. */
+export interface ProbeResponse {
+    status: number;
+    body: string;
+}
+export interface SessionProbeOptions {
+    /** Make the authenticated request. Must NOT sign in — a diagnostic observes. */
+    request: () => Promise<ProbeResponse>;
+    /**
+     * **The site-specific closure**, and the only part of this that cannot be
+     * generalised: does this body mean "not signed in"?
+     *
+     * It stays with the consumer because getting it wrong is silent and specific.
+     * One real portal links to two-factor setup from every signed-in page, so a
+     * body-wide match on `twoFactor` reports "signed out" for every request; the
+     * fix was to scope it to the `<title>`, which is knowable only next to the
+     * markup. A library that guessed this would be wrong in both directions.
+     */
+    signedOut: (body: string) => boolean;
+    /** Used in the thrown messages. Defaults to a neutral phrase. */
+    hostLabel?: string;
+}
+/**
+ * Build a `probeFn` that JUDGES its response instead of merely completing.
+ *
+ * `probeFn`'s contract is that it reports failure by throwing, so any probe
+ * that can resolve on a signed-out response silently reports healthy. Every
+ * connector whose probe rides a client that throws on non-2xx complies by
+ * accident — and that accident does not hold against a SOFT wall, where a dead
+ * session comes back 200 with a login page.
+ *
+ * The rules here are the generic ones:
+ *
+ *  - a 3xx is signed out, because under a manual-redirect fetch the bounce to
+ *    the login page arrives with no body to judge;
+ *  - any other non-2xx is an upstream error carrying its status;
+ *  - a 2xx is signed out if the consumer's closure says so.
+ *
+ * Pair with {@link sessionClassifier} to turn those into arms and remedies.
+ */
+export declare function sessionProbe(opts: SessionProbeOptions): () => Promise<string>;
+export interface SessionClassifierOptions {
+    /** Tool-name prefix, used to name the remedy tools in the default copy. */
+    prefix: string;
+    /** Display host named in the default copy, e.g. `'my.atriumhealth.org'`. */
+    hostLabel: string;
+    /** A second factor is outstanding. Read at classification time, not captured. */
+    verificationPending?: () => boolean;
+    /** The far side refused this username and password. */
+    credentialsRejected?: () => boolean;
+    /** Per-kind copy overrides, for a connector whose remedy is not a tool call. */
+    hints?: Partial<Record<'session_expired' | 'verification_pending' | 'credential_rejected' | 'http', string>>;
+}
+/**
+ * Build a `classifyThrown` that names WHICH signed-out state a
+ * {@link sessionProbe} failure is.
+ *
+ * All three arrive as the same login page and have three different remedies,
+ * so reporting them as one sends people to the wrong fix — telling somebody
+ * with an outstanding code to check their password sends them to change a
+ * credential that is already correct.
+ *
+ * **A refused credential outranks a pending verification.** Both flags can be
+ * set at once, and retrying a code against a password the far side refuses is
+ * futile. Two call sites in one repo disagreed about this order, which is the
+ * argument for the order living in exactly one place.
+ *
+ * Returns `undefined` for anything it does not recognise, so the built-in
+ * ladder still classifies a network failure rather than being shadowed.
+ */
+export declare function sessionClassifier(opts: SessionClassifierOptions): (err: unknown) => {
+    kind: string;
+    hint?: string;
+} | undefined;
 //# sourceMappingURL=index.d.ts.map

package/dist/healthcheck/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/healthcheck/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAChC,IAAI,GACJ,eAAe,GACf,qBAAqB,GACrB,SAAS,GACT,MAAM,GACN,WAAW,GACX,SAAS,CAAC;AAEd,6EAA6E;AAC7E,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qCAAqC;IACpD;;;;;;OAMG;IACH,MAAM,EAAE,SAAS,CAAC;IAClB,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,SAAS,EAAE,MAAM,CAAC;IAClB,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;OAWG;IACH,iBAAiB,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,CAAC;IAClD,4EAA4E;IAC5E,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC;;;;;;;;;;;;;;OAcG;IACH,cAAc,CAAC,EAAE,CACf,GAAG,EAAE,OAAO,KACT;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,SAAS,CAAC;IACnF,8BAA8B;IAC9B,KAAK,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,wBAAwB,EAAE,MAAM,CAAC,CAAC,CAAC;CAC3D;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,2BAA2B;IAC1C,EAAE,EAAE,OAAO,CAAC;IACZ,UAAU,EAAE;QAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IAC3F,KAAK,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7D,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IAC5E,IAAI,EAAE,MAAM,CAAC;CACd;AAiDD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,qCAAqC,GAC1C,IAAI,CAkJN"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/healthcheck/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAChC,IAAI,GACJ,eAAe,GACf,qBAAqB;AACvB,0EAA0E;GACxE,iBAAiB;AACnB,8EAA8E;GAC5E,sBAAsB,GACtB,SAAS,GACT,MAAM,GACN,WAAW,GACX,SAAS,CAAC;AAEd,6EAA6E;AAC7E,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qCAAqC;IACpD;;;;;;OAMG;IACH,MAAM,EAAE,SAAS,CAAC;IAClB,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;OAWG;IACH,iBAAiB,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,CAAC;IAClD;;;;;;;;;OASG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC;;;;;;;;;;;;;;OAcG;IACH,cAAc,CAAC,EAAE,CACf,GAAG,EAAE,OAAO,KACT;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,SAAS,CAAC;IACnF,8BAA8B;IAC9B,KAAK,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,wBAAwB,EAAE,MAAM,CAAC,CAAC,CAAC;CAC3D;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,2BAA2B;IAC1C,EAAE,EAAE,OAAO,CAAC;IACZ,UAAU,EAAE;QAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IAC3F,KAAK,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7D,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IAC5E,IAAI,EAAE,MAAM,CAAC;CACd;AAuDD,mDAAmD;AACnD,MAAM,MAAM,qBAAqB,GAAG;IAAE,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CAAE,CAAC;AAElF,gFAAgF;AAChF,wBAAgB,gCAAgC,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,qCAAqC,GAC1C,OAAO,CAAC,qBAAqB,CAAC,CAiIhC;AAED;;;;GAIG;AACH,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,qCAAqC,GAC1C,IAAI,CAgBN;AAGD;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAE1C,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM;IAFzB,YACW,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EAIxB;CACF;AAED,gFAAgF;AAChF,qBAAa,cAAe,SAAQ,KAAK;IAErC,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM;IAFzB,YACW,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EAIxB;CACF;AAED,gEAAgE;AAChE,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,OAAO,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC;IACtC;;;;;;;;;OASG;IACH,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACrC,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,CAW7E;AAED,MAAM,WAAW,wBAAwB;IACvC,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC;IACpC,uDAAuD;IACvD,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC;IACpC,gFAAgF;IAChF,KAAK,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,iBAAiB,GAAG,sBAAsB,GAAG,qBAAqB,GAAG,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC9G;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,wBAAwB,GAC7B,CAAC,GAAG,EAAE,OAAO,KAAK;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CA0C/D"}

package/dist/healthcheck/index.js

@@ -11,6 +11,8 @@ const CREDENTIAL_ARMS = new Set([
     'ok',
     'no_credential',
     'credential_rejected',
+    'session_expired',
+    'verification_pending',
     'timeout',
     'http',
     'transport',
@@ -28,6 +30,10 @@ function credentialHint(arm, prefix, hostLabel, source) {
             return `No credential resolved. Nothing was available to authenticate with — sign in and reconnect the connector so ${prefix} receives a token, or set the documented environment variable.`;
         case 'credential_rejected':
             return `${hostLabel} rejected the credential from '${source}'. It is present but no longer valid — most often expired or revoked upstream. Re-authenticate and reconnect; retrying will not fix it.`;
+        case 'session_expired':
+            return `The credential from '${source}' is configured, but no session is live — ${hostLabel} served a sign-in page rather than the data. Sign in again; a cookie-session portal expires these on its own, so this recurs between uses.`;
+        case 'verification_pending':
+            return `${hostLabel} is holding the sign-in on a second factor rather than refusing it. Supply the verification code the ACCOUNT HOLDER received — the credential itself is not the problem, so changing it will not help.`;
         case 'timeout':
             return `The credential from '${source}' resolved, but ${hostLabel} did not answer in time. Usually transient — retry. If it persists, ${hostLabel} is slow or unreachable from here.`;
         case 'http':
@@ -38,28 +44,166 @@ function credentialHint(arm, prefix, hostLabel, source) {
             return `Unexpected failure — see error.message.`;
     }
 }
+/** The credential arm's one-line description, shared with the adaptive tool. */
+export function credentialHealthcheckDescription(hostLabel) {
+    return `Resolves the credential the way real tools do, then makes one authenticated request to ${hostLabel}. Reports which source supplied the credential, whether ${hostLabel} accepted it, the round-trip time, and a plain-English hint distinguishing 'no credential' from 'credential rejected' from 'a ${hostLabel}-side problem'. Read-only; never returns the credential itself.`;
+}
 /**
- * Register `${prefix}_healthcheck` for a connector whose health is about a
- * CREDENTIAL rather than a browser bridge — OAuth connectors, API-key
- * connectors, and the fetchproxy MCPs that only BOOTSTRAP a token and then
- * talk to an API directly.
+ * The credential healthcheck's whole body, without the registration: what a
+ * connector reports when its health is about a CREDENTIAL rather than a browser
+ * bridge — OAuth connectors, API-key connectors, and the fetchproxy MCPs that
+ * only BOOTSTRAP a token and then talk to an API directly.
  *
  * It exists because those three failures are indistinguishable today and have
  * different fixes: nothing minted a credential, something minted one the far
  * side rejects, and the far side is simply down. The bridge helper
- * (`registerBridgeHealthcheckTool`, in `../fetchproxy/`) answers the equivalent question for
- * MCPs where every request rides the bridge.
+ * ({@link runBridgeHealthcheck}, in `../fetchproxy/`) answers the equivalent
+ * question for MCPs where every request rides the bridge.
  *
  * The probe is SKIPPED when no credential resolved — probing without one
  * produces a 401 that reads like a rejected credential and points at the wrong
  * fix.
+ *
+ * Split out from the registration so ONE tool can serve a server with two
+ * transports and choose between the arms per call
+ * (`registerAdaptiveHealthcheckTool`, in `../fetchproxy/`, which is where the
+ * bridge arm's optional peer dependency already lives).
+ * `registerCredentialHealthcheckTool` is unchanged and still the right choice
+ * for a server with only this arm.
+ */
+export async function runCredentialHealthcheck(args) {
+    const { prefix, hostLabel, probePath, resolveCredential, probeFn, classifyThrown, hints } = args;
+    const probeUrl = probePath
+        ? `https://${hostLabel}${probePath.startsWith('/') ? '' : '/'}${probePath}`
+        : undefined;
+    // Timed from just BEFORE the probe, never from the top: resolving a
+    // credential can mint a token or drive the browser bridge, and folding
+    // that into `probe.elapsed_ms` reports it as far-side latency.
+    let probeStarted = 0;
+    let state;
+    try {
+        state = await resolveCredential();
+    }
+    catch (e) {
+        // A resolver can fail for reasons that are NOT "no credential": a
+        // browser bridge that is down, an upstream that rejected a password,
+        // a store that will not decrypt. Flattening those into
+        // `no_credential` hands out that arm's advice — set the variables —
+        // to someone whose variables are already set. So the consumer's
+        // classifier is consulted here as it already is for a probe failure;
+        // declining it (or not supplying one) keeps the old behaviour exactly.
+        const classified = classifyThrown?.(e);
+        const result = {
+            ok: false,
+            // Still false, and still no source: a classification explains WHY
+            // nothing resolved, it does not invent a credential that did.
+            credential: { source: null, resolved: false },
+            // No `url`: nothing was probed, and naming one implies it was tried.
+            probe: { elapsed_ms: 0 },
+            error: {
+                kind: classified?.kind ?? 'no_credential',
+                message: truncateErrorMessage(messageOf(e)),
+                ...(classified?.detail !== undefined ? { detail: classified.detail } : {}),
+            },
+            // The hint must follow the KIND beside it. Falling back to
+            // `no_credential`'s copy under a classified kind would state a cause
+            // the kind contradicts — the same disagreement this path exists to
+            // remove. So: an inline hint wins; else the classified arm's own
+            // copy (consumer override first); else, for a kind this module has
+            // no copy for, the neutral `unknown` text rather than one that
+            // asserts a cause; else the unclassified `no_credential` default.
+            hint: classified?.hint ??
+                (isArm(classified?.kind)
+                    ? (hints?.[classified.kind] ??
+                        credentialHint(classified.kind, prefix, hostLabel, null))
+                    : classified !== undefined
+                        ? credentialHint('unknown', prefix, hostLabel, null)
+                        : (hints?.no_credential ??
+                            credentialHint('no_credential', prefix, hostLabel, null))),
+        };
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+    const credential = {
+        source: state.source,
+        resolved: state.source !== null,
+        ...(state.detail !== undefined ? { detail: state.detail } : {}),
+    };
+    // No credential: answer without probing. A probe here 401s and reads as
+    // "rejected", which points at re-authenticating a credential that does
+    // not exist.
+    if (!credential.resolved) {
+        const result = {
+            ok: false,
+            credential,
+            probe: { elapsed_ms: 0 },
+            error: { kind: 'no_credential', message: 'no credential source resolved' },
+            hint: hints?.no_credential ?? credentialHint('no_credential', prefix, hostLabel, null),
+        };
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+    let arm = 'ok';
+    let error;
+    let status;
+    let customHint;
+    probeStarted = Date.now();
+    try {
+        await probeFn();
+    }
+    catch (e) {
+        status = statusOf(e);
+        // `AbortError` is matched on `err.name`, as src/http/index.ts does — a
+        // bare AbortController abort carries it there and NOT in the message,
+        // so matching the text alone classified those as 'unknown'.
+        const aborted = e instanceof Error && e.name === 'AbortError';
+        arm =
+            status === 401 || status === 403
+                ? 'credential_rejected'
+                : status !== undefined
+                    ? 'http'
+                    : aborted || /timeout|timed out|ETIMEDOUT/i.test(messageOf(e))
+                        ? 'timeout'
+                        : /fetch failed|ENOTFOUND|ECONNREFUSED|ECONNRESET|network/i.test(messageOf(e))
+                            ? 'transport'
+                            : 'unknown';
+        let kind = arm;
+        let detail;
+        const custom = classifyThrown?.(e);
+        if (custom) {
+            kind = custom.kind;
+            customHint = custom.hint;
+            detail = custom.detail;
+        }
+        error = {
+            kind,
+            // Redacted AND bounded before it reaches the result: an upstream
+            // failure routinely quotes what it was sent, and a healthcheck is
+            // the tool people paste into a chat when something is broken.
+            message: truncateErrorMessage(messageOf(e)),
+            ...(detail !== undefined ? { detail } : {}),
+        };
+    }
+    const result = {
+        ok: error === undefined,
+        credential,
+        probe: {
+            ...(probeUrl ? { url: probeUrl } : {}),
+            elapsed_ms: Date.now() - probeStarted,
+            ...(status !== undefined ? { status } : {}),
+        },
+        ...(error ? { error } : {}),
+        hint: customHint ?? hints?.[arm] ?? credentialHint(arm, prefix, hostLabel, state.source),
+    };
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+}
+/**
+ * Register `${prefix}_healthcheck` for a connector whose health is about a
+ * CREDENTIAL rather than a browser bridge. The body is
+ * {@link runCredentialHealthcheck}.
  */
 export function registerCredentialHealthcheckTool(args) {
-    const { server, prefix, hostLabel, probePath, resolveCredential, probeFn, classifyThrown, hints } = args;
-    const probeUrl = probePath ? `https://${hostLabel}${probePath}` : undefined;
-    server.registerTool(`${prefix}_healthcheck`, {
+    args.server.registerTool(`${args.prefix}_healthcheck`, {
         title: 'Verify credentials and upstream reachability',
-        description: `Resolves the credential the way real tools do, then makes one authenticated request to ${hostLabel}. Reports which source supplied the credential, whether ${hostLabel} accepted it, the round-trip time, and a plain-English hint distinguishing 'no credential' from 'credential rejected' from 'a ${hostLabel}-side problem'. Call this when a real tool fails and you want to know which hop broke. Read-only; never returns the credential itself.`,
+        description: `${credentialHealthcheckDescription(args.hostLabel)} Call this when a real tool fails and you want to know which hop broke.`,
         annotations: {
             title: 'Verify credentials and upstream reachability',
             readOnlyHint: true,
@@ -67,125 +211,121 @@ export function registerCredentialHealthcheckTool(args) {
             openWorldHint: true,
         },
         inputSchema: {},
-    }, async () => {
-        // Timed from just BEFORE the probe, never from the top: resolving a
-        // credential can mint a token or drive the browser bridge, and folding
-        // that into `probe.elapsed_ms` reports it as far-side latency.
-        let probeStarted = 0;
-        let state;
-        try {
-            state = await resolveCredential();
+    }, async () => runCredentialHealthcheck(args));
+}
+/**
+ * The probe reached the far side and it declined to serve the data — a login
+ * page, or a redirect to one. Its own class so a classifier can tell it apart
+ * from a network failure.
+ */
+export class SessionNotLiveError extends Error {
+    hostLabel;
+    detail;
+    constructor(hostLabel, detail) {
+        super(`${hostLabel} served a sign-in page rather than the data (${detail}).`);
+        this.hostLabel = hostLabel;
+        this.detail = detail;
+        this.name = 'SessionNotLiveError';
+    }
+}
+/** A non-2xx from the far side, carrying the status the healthcheck reports. */
+export class ProbeHttpError extends Error {
+    hostLabel;
+    status;
+    constructor(hostLabel, status) {
+        super(`${hostLabel} answered ${status}.`);
+        this.hostLabel = hostLabel;
+        this.status = status;
+        this.name = 'ProbeHttpError';
+    }
+}
+/**
+ * Build a `probeFn` that JUDGES its response instead of merely completing.
+ *
+ * `probeFn`'s contract is that it reports failure by throwing, so any probe
+ * that can resolve on a signed-out response silently reports healthy. Every
+ * connector whose probe rides a client that throws on non-2xx complies by
+ * accident — and that accident does not hold against a SOFT wall, where a dead
+ * session comes back 200 with a login page.
+ *
+ * The rules here are the generic ones:
+ *
+ *  - a 3xx is signed out, because under a manual-redirect fetch the bounce to
+ *    the login page arrives with no body to judge;
+ *  - any other non-2xx is an upstream error carrying its status;
+ *  - a 2xx is signed out if the consumer's closure says so.
+ *
+ * Pair with {@link sessionClassifier} to turn those into arms and remedies.
+ */
+export function sessionProbe(opts) {
+    const host = opts.hostLabel ?? 'the upstream';
+    return async () => {
+        const { status, body } = await opts.request();
+        if (status >= 300 && status < 400) {
+            throw new SessionNotLiveError(host, `redirected with ${status}`);
         }
-        catch (e) {
-            // A resolver can fail for reasons that are NOT "no credential": a
-            // browser bridge that is down, an upstream that rejected a password,
-            // a store that will not decrypt. Flattening those into
-            // `no_credential` hands out that arm's advice — set the variables —
-            // to someone whose variables are already set. So the consumer's
-            // classifier is consulted here as it already is for a probe failure;
-            // declining it (or not supplying one) keeps the old behaviour exactly.
-            const classified = classifyThrown?.(e);
-            const result = {
-                ok: false,
-                // Still false, and still no source: a classification explains WHY
-                // nothing resolved, it does not invent a credential that did.
-                credential: { source: null, resolved: false },
-                // No `url`: nothing was probed, and naming one implies it was tried.
-                probe: { elapsed_ms: 0 },
-                error: {
-                    kind: classified?.kind ?? 'no_credential',
-                    message: truncateErrorMessage(messageOf(e)),
-                    ...(classified?.detail !== undefined ? { detail: classified.detail } : {}),
-                },
-                // The hint must follow the KIND beside it. Falling back to
-                // `no_credential`'s copy under a classified kind would state a cause
-                // the kind contradicts — the same disagreement this path exists to
-                // remove. So: an inline hint wins; else the classified arm's own
-                // copy (consumer override first); else, for a kind this module has
-                // no copy for, the neutral `unknown` text rather than one that
-                // asserts a cause; else the unclassified `no_credential` default.
-                hint: classified?.hint ??
-                    (isArm(classified?.kind)
-                        ? (hints?.[classified.kind] ??
-                            credentialHint(classified.kind, prefix, hostLabel, null))
-                        : classified !== undefined
-                            ? credentialHint('unknown', prefix, hostLabel, null)
-                            : (hints?.no_credential ??
-                                credentialHint('no_credential', prefix, hostLabel, null))),
+        if (status < 200 || status >= 300)
+            throw new ProbeHttpError(host, status);
+        if (opts.signedOut(body))
+            throw new SessionNotLiveError(host, 'sign-in or verification page');
+        return body;
+    };
+}
+/**
+ * Build a `classifyThrown` that names WHICH signed-out state a
+ * {@link sessionProbe} failure is.
+ *
+ * All three arrive as the same login page and have three different remedies,
+ * so reporting them as one sends people to the wrong fix — telling somebody
+ * with an outstanding code to check their password sends them to change a
+ * credential that is already correct.
+ *
+ * **A refused credential outranks a pending verification.** Both flags can be
+ * set at once, and retrying a code against a password the far side refuses is
+ * futile. Two call sites in one repo disagreed about this order, which is the
+ * argument for the order living in exactly one place.
+ *
+ * Returns `undefined` for anything it does not recognise, so the built-in
+ * ladder still classifies a network failure rather than being shadowed.
+ */
+export function sessionClassifier(opts) {
+    const { prefix, hostLabel, hints } = opts;
+    return (err) => {
+        if (err instanceof ProbeHttpError) {
+            return {
+                kind: 'http',
+                hint: hints?.http ??
+                    `${hostLabel} answered ${err.status}. The credential was never judged — that is an ` +
+                        'upstream problem, so retry, and if it persists the far side is down.',
             };
-            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
         }
-        const credential = {
-            source: state.source,
-            resolved: state.source !== null,
-            ...(state.detail !== undefined ? { detail: state.detail } : {}),
-        };
-        // No credential: answer without probing. A probe here 401s and reads as
-        // "rejected", which points at re-authenticating a credential that does
-        // not exist.
-        if (!credential.resolved) {
-            const result = {
-                ok: false,
-                credential,
-                probe: { elapsed_ms: 0 },
-                error: { kind: 'no_credential', message: 'no credential source resolved' },
-                hint: hints?.no_credential ?? credentialHint('no_credential', prefix, hostLabel, null),
+        if (!(err instanceof SessionNotLiveError))
+            return undefined;
+        if (opts.credentialsRejected?.() === true) {
+            return {
+                kind: 'credential_rejected',
+                hint: hints?.credential_rejected ??
+                    `${hostLabel} refused this username and password. Correct them, then call ` +
+                        `${prefix}_sign_in. Nothing retries for you: repeated failures escalate to a ` +
+                        'captcha or a lockout.',
             };
-            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
         }
-        let arm = 'ok';
-        let error;
-        let status;
-        let customHint;
-        probeStarted = Date.now();
-        try {
-            await probeFn();
-        }
-        catch (e) {
-            status = statusOf(e);
-            // `AbortError` is matched on `err.name`, as src/http/index.ts does — a
-            // bare AbortController abort carries it there and NOT in the message,
-            // so matching the text alone classified those as 'unknown'.
-            const aborted = e instanceof Error && e.name === 'AbortError';
-            arm =
-                status === 401 || status === 403
-                    ? 'credential_rejected'
-                    : status !== undefined
-                        ? 'http'
-                        : aborted || /timeout|timed out|ETIMEDOUT/i.test(messageOf(e))
-                            ? 'timeout'
-                            : /fetch failed|ENOTFOUND|ECONNREFUSED|ECONNRESET|network/i.test(messageOf(e))
-                                ? 'transport'
-                                : 'unknown';
-            let kind = arm;
-            let detail;
-            const custom = classifyThrown?.(e);
-            if (custom) {
-                kind = custom.kind;
-                customHint = custom.hint;
-                detail = custom.detail;
-            }
-            error = {
-                kind,
-                // Redacted AND bounded before it reaches the result: an upstream
-                // failure routinely quotes what it was sent, and a healthcheck is
-                // the tool people paste into a chat when something is broken.
-                message: truncateErrorMessage(messageOf(e)),
-                ...(detail !== undefined ? { detail } : {}),
+        if (opts.verificationPending?.() === true) {
+            return {
+                kind: 'verification_pending',
+                hint: hints?.verification_pending ??
+                    `A verification code is outstanding, so ${hostLabel} is holding the sign-in rather ` +
+                        `than refusing it. Call ${prefix}_send_verification_code, then pass the code the ` +
+                        `ACCOUNT HOLDER receives to ${prefix}_verify_code.`,
             };
         }
-        const result = {
-            ok: error === undefined,
-            credential,
-            probe: {
-                ...(probeUrl ? { url: probeUrl } : {}),
-                elapsed_ms: Date.now() - probeStarted,
-                ...(status !== undefined ? { status } : {}),
-            },
-            ...(error ? { error } : {}),
-            hint: customHint ?? hints?.[arm] ?? credentialHint(arm, prefix, hostLabel, state.source),
+        return {
+            kind: 'session_expired',
+            hint: hints?.session_expired ??
+                `The credentials are configured but no session is live — ${hostLabel} sessions are ` +
+                    `short-lived, so this recurs between uses. Call ${prefix}_sign_in; expect a ` +
+                    'verification code, which goes to the account holder.',
         };
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
-    });
+    };
 }
 //# sourceMappingURL=index.js.map