@openrouter/agent 0.9.0 → 0.11.0

package/esm/mcp/mcp-sdk.js

@@ -0,0 +1,37 @@
+import { MCPMissingPeerDependencyError } from './errors.js';
+let sdkPromise;
+function isMissingSdk(error) {
+    let current = error;
+    while (current instanceof Error) {
+        const code = 'code' in current ? current.code : undefined;
+        const specifier = /Cannot find (?:package|module) '([^']+)'/.exec(current.message)?.[1];
+        if ((code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND') &&
+            (specifier === '@modelcontextprotocol/client' ||
+                specifier?.startsWith('@modelcontextprotocol/client/') === true)) {
+            return true;
+        }
+        current = current.cause;
+    }
+    return false;
+}
+/** Load the optional MCP client only when a connection is actually requested. */
+export function loadMcpSdk() {
+    sdkPromise ?? (sdkPromise = import('@modelcontextprotocol/client')
+        .then((client) => ({
+        Client: client.Client,
+        SSEClientTransport: client.SSEClientTransport,
+        StreamableHTTPClientTransport: client.StreamableHTTPClientTransport,
+        UnauthorizedError: client.UnauthorizedError,
+    }))
+        .catch((cause) => {
+        sdkPromise = undefined;
+        if (isMissingSdk(cause)) {
+            throw new MCPMissingPeerDependencyError({
+                cause,
+            });
+        }
+        throw cause;
+    }));
+    return sdkPromise;
+}
+//# sourceMappingURL=mcp-sdk.js.map

package/esm/mcp/mcp-sdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-sdk.js","sourceRoot":"","sources":["../../src/mcp/mcp-sdk.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,6BAA6B,EAAE,MAAM,aAAa,CAAC;AAS5D,IAAI,UAAuC,CAAC;AAE5C,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,OAAO,OAAO,YAAY,KAAK,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;QAC1D,MAAM,SAAS,GAAG,0CAA0C,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACxF,IACE,CAAC,IAAI,KAAK,sBAAsB,IAAI,IAAI,KAAK,kBAAkB,CAAC;YAChE,CAAC,SAAS,KAAK,8BAA8B;gBAC3C,SAAS,EAAE,UAAU,CAAC,+BAA+B,CAAC,KAAK,IAAI,CAAC,EAClE,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC;IAC1B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,UAAU;IACxB,UAAU,KAAV,UAAU,GAAK,MAAM,CAAC,8BAA8B,CAAC;SAClD,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,kBAAkB,EAAE,MAAM,CAAC,kBAAkB;QAC7C,6BAA6B,EAAE,MAAM,CAAC,6BAA6B;QACnE,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;KAC5C,CAAC,CAAC;SACF,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QACxB,UAAU,GAAG,SAAS,CAAC;QACvB,IAAI,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,6BAA6B,CAAC;gBACtC,KAAK;aACN,CAAC,CAAC;QACL,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC,CAAC,EAAC;IACL,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/esm/mcp/rehydrate.d.ts

@@ -0,0 +1,76 @@
+import type { MCPAuth } from './auth/auth-types.js';
+import type { MCPCacheStore } from './cache/cache-store.js';
+import type { SerializedMCPServer } from './cache/cache-types.js';
+import type { UnconvertibleSchemaMode } from './schema/json-schema-to-zod.js';
+import type { CreateMCPToolsOptions, ElicitationHandler, MCPProtocolNegotiation, MCPToolsHandle, ResourcesOption } from './types.js';
+export interface RehydrateMCPToolsOptions {
+    snapshot: SerializedMCPServer;
+    /** Required when the snapshot carries no cached credentials. */
+    auth?: MCPAuth;
+    fetch?: typeof fetch;
+    onUnconvertibleSchema?: UnconvertibleSchemaMode;
+    onElicitation?: ElicitationHandler;
+    signal?: AbortSignal;
+    /** Protocol-revision negotiation policy; defaults to `'auto'`. */
+    protocolNegotiation?: MCPProtocolNegotiation;
+    /** Ceiling on the `server/discover` probe, in ms; defaults to 30000. */
+    probeTimeoutMs?: number;
+    /** Re-list tools instead of replaying a snapshot older than this. */
+    staleness?: {
+        maxAgeMs?: number;
+    };
+    /**
+     * Cache to refresh on reconnect/fallback.
+     *
+     * A successful replay does **not** write here — the snapshot it would write is
+     * the one you passed in, so the write is skipped as a no-op. The store is
+     * written when something genuinely new exists: a `refresh()`, a
+     * `tools/list_changed` auto-refresh, or the fresh-connect fallback. To seed a
+     * store from a snapshot obtained elsewhere, write it yourself
+     * (`store.set(key, snapshot)`) or call `handle.refresh()` after rehydrating.
+     */
+    cache?: {
+        store: MCPCacheStore;
+        key?: string;
+    };
+    /**
+     * On expired cached tokens, missing credentials, an over-age snapshot
+     * (`staleness.maxAgeMs`), or a replay connection failure, transparently fall
+     * back to a full fresh connect. Default true.
+     *
+     * The fallback is skipped when the replay's connect ended in a credential
+     * rejection (the SDK's `UnauthorizedError`, or a 401 status when an OAuth
+     * provider is configured): the fallback reuses the same auth, so retrying
+     * cannot succeed and would re-drive an OAuth authorization flow. Those
+     * failures reject with `MCPCacheError` instead. A 403 does not skip it — the
+     * SDK's OAuth side effects only occur on 401, and gateways commonly answer
+     * unknown methods with 403.
+     */
+    reconnectOnExpiry?: boolean;
+    toolNamePrefix?: string;
+    includeTools?: readonly string[];
+    excludeTools?: readonly string[];
+    resources?: ResourcesOption;
+    emitProgress?: boolean;
+    /** Doom-loop identities for wrapped tools, keyed by unprefixed MCP name. */
+    loopKeys?: CreateMCPToolsOptions['loopKeys'];
+    autoRefreshOnListChanged?: boolean;
+    cacheCredentials?: boolean;
+    clientInfo?: {
+        name: string;
+        version: string;
+    };
+}
+/**
+ * Rebuild an {@link MCPToolsHandle} from a cached snapshot. On the happy path we
+ * reconnect the transport and rebuild tools directly from the snapshot —
+ * skipping `listTools()`. If cached tokens are expired, credentials are missing,
+ * the snapshot is older than `staleness.maxAgeMs`, or the replay connection
+ * fails, we transparently fall back to a fresh connect (unless
+ * `reconnectOnExpiry` is false) — with one exception: a credential rejection is
+ * not retried, because the fallback reuses the same auth and re-attempting
+ * would re-drive an OAuth authorization flow. See {@link
+ * RehydrateMCPToolsOptions.reconnectOnExpiry}.
+ */
+export declare function rehydrateMCPTools(options: RehydrateMCPToolsOptions): Promise<MCPToolsHandle>;
+//# sourceMappingURL=rehydrate.d.ts.map

package/esm/mcp/rehydrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rehydrate.d.ts","sourceRoot":"","sources":["../../src/mcp/rehydrate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAE5D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAQlE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAE9E,OAAO,KAAK,EACV,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,EACtB,cAAc,EACd,eAAe,EAChB,MAAM,YAAY,CAAC;AAKpB,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,gEAAgE;IAChE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,qBAAqB,CAAC,EAAE,uBAAuB,CAAC;IAChD,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,kEAAkE;IAClE,mBAAmB,CAAC,EAAE,sBAAsB,CAAC;IAC7C,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,SAAS,CAAC,EAAE;QACV,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE;QACN,KAAK,EAAE,aAAa,CAAC;QACrB,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,CAAC;IACF;;;;;;;;;;;;OAYG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAG5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,qBAAqB,CAAC,UAAU,CAAC,CAAC;IAC7C,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,UAAU,CAAC,EAAE;QACX,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAoaD;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,cAAc,CAAC,CAqHzB"}

package/esm/mcp/rehydrate.js

@@ -0,0 +1,505 @@
+import { resolveAuth } from './auth/auth-resolver.js';
+import { isOAuthAuth } from './auth/auth-types.js';
+import { defaultCacheKey } from './cache/cache-store.js';
+import { isSerializedMCPServer } from './cache/cache-types.js';
+import { closeQuietly } from './close-quietly.js';
+import { MCPCacheError, MCPCacheWriteError, MCPStaleSnapshotError } from './errors.js';
+import { freshConnect, makeHandle } from './handle.js';
+import { connect, isAuthFailure } from './mcp-connection.js';
+import { loadMcpSdk } from './mcp-sdk.js';
+/** Clock skew (ms) treated as "already expired" when checking cached tokens. */
+const EXPIRY_SKEW_MS = 30000;
+function snapshotToToolDefs(snapshot) {
+    return snapshot.tools.map((t) => ({
+        name: t.name,
+        ...(t.description !== undefined && {
+            description: t.description,
+        }),
+        inputSchema: {
+            ...t.inputSchema,
+        },
+        ...(t.outputSchema !== undefined && {
+            outputSchema: {
+                ...t.outputSchema,
+            },
+        }),
+        ...(t.loopKey !== undefined && {
+            loopKey: t.loopKey,
+        }),
+    }));
+}
+/** A snapshot older than `maxAgeMs` should be re-listed rather than replayed. */
+function snapshotIsStale(snapshot, maxAgeMs) {
+    if (maxAgeMs === undefined) {
+        return false;
+    }
+    return Date.now() - snapshot.cachedAt > maxAgeMs;
+}
+/** Cached tokens are unusable if they have a known expiry within the skew window. */
+function tokensExpired(snapshot) {
+    const expiresAt = snapshot.auth?.tokens?.expiresAt;
+    if (expiresAt === undefined) {
+        return false;
+    }
+    return expiresAt - Date.now() <= EXPIRY_SKEW_MS;
+}
+/**
+ * Reconstruct an {@link MCPAuth} from credentials persisted in a snapshot (only
+ * present when it was serialized with `cacheCredentials: true`). Prefer static
+ * headers when present; otherwise fall back to the OAuth/bearer access token.
+ * Returns undefined when the snapshot carries no usable credentials.
+ */
+function authFromSnapshot(snapshot) {
+    const auth = snapshot.auth;
+    if (auth === undefined) {
+        return undefined;
+    }
+    if (auth.headers !== undefined && Object.keys(auth.headers).length > 0) {
+        return {
+            kind: 'headers',
+            headers: auth.headers,
+        };
+    }
+    if (auth.tokens?.accessToken !== undefined) {
+        return {
+            kind: 'bearer',
+            token: auth.tokens.accessToken,
+        };
+    }
+    return undefined;
+}
+/**
+ * Options copied straight from a rehydrate call onto the `createMCPTools`
+ * options used for the fresh-connect fallback. `satisfies` keeps this honest:
+ * a key that isn't on both types fails to compile rather than silently
+ * dropping.
+ *
+ * `staleness` is deliberately absent — it compares a snapshot's age, and the
+ * fallback path has no snapshot to compare.
+ */
+const PASS_THROUGH_CREATE_KEYS = [
+    'fetch',
+    'onUnconvertibleSchema',
+    'onElicitation',
+    'protocolNegotiation',
+    'probeTimeoutMs',
+    'signal',
+    'clientInfo',
+    'toolNamePrefix',
+    'includeTools',
+    'excludeTools',
+    'resources',
+    'emitProgress',
+    'loopKeys',
+    'autoRefreshOnListChanged',
+    'cacheCredentials',
+    'cache',
+];
+function toCreateOptions(options, snapshot, effectiveAuth) {
+    const out = {
+        url: snapshot.url,
+        transport: snapshot.transport,
+        ...(effectiveAuth !== undefined && {
+            auth: effectiveAuth,
+        }),
+    };
+    // Copy every defined pass-through key in one pass. Written as a loop rather
+    // than a spread per key so adding an option doesn't push this function's
+    // cyclomatic complexity past the structural gate's ceiling; it also mirrors
+    // `forwardedRehydrateOptions` in create-mcp-tools.ts, which forwards the same
+    // set in the opposite direction.
+    for (const key of PASS_THROUGH_CREATE_KEYS) {
+        const value = options[key];
+        if (value !== undefined) {
+            Object.assign(out, {
+                [key]: value,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Connect options for the snapshot-replay path.
+ *
+ * Distinct from {@link toCreateOptions}, which builds the *fallback*
+ * `createMCPTools` options: this one carries the snapshot's own `transport` and
+ * `sessionId` because the point is to re-establish the connection the snapshot
+ * describes, and it deliberately omits the tool-shaping keys, which are applied
+ * by `makeHandle` rather than at connect time.
+ */
+function toReplayConnectOptions(args) {
+    const { options, snapshot, url, effectiveAuth } = args;
+    return {
+        url,
+        transport: snapshot.transport,
+        ...(effectiveAuth !== undefined && {
+            auth: effectiveAuth,
+        }),
+        ...(options.fetch !== undefined && {
+            fetch: options.fetch,
+        }),
+        ...(options.clientInfo !== undefined && {
+            clientInfo: options.clientInfo,
+        }),
+        // `sessionId` is deliberately NOT forwarded. When a transport reports one,
+        // SDK v2 skips negotiation entirely — no `server/discover` probe and no
+        // `initialize` — and returns with `getProtocolEra()`,
+        // `getServerCapabilities()` and `getServerVersion()` all left undefined. It
+        // does not error, which is what makes it dangerous: `serverHasResources()`
+        // reads those capabilities, so a snapshot carrying a `sessionId` would
+        // silently replay with resource tools missing and no server info. Sessions
+        // are also removed outright in 2026-07-28 (SEP-2567), so a fresh handshake
+        // is both correct and cheap — one round trip on a path that already opens a
+        // connection.
+        ...(options.onElicitation !== undefined && {
+            onElicitation: options.onElicitation,
+        }),
+        ...(options.protocolNegotiation !== undefined && {
+            protocolNegotiation: options.protocolNegotiation,
+        }),
+        ...(options.probeTimeoutMs !== undefined && {
+            probeTimeoutMs: options.probeTimeoutMs,
+        }),
+        ...(options.signal !== undefined && {
+            signal: options.signal,
+        }),
+    };
+}
+/**
+ * Re-list tools on a handle built from a snapshot older than the caller's
+ * `staleness.maxAgeMs`.
+ *
+ * Reached only when `reconnectOnExpiry` is false — otherwise a stale snapshot
+ * has already gone to `freshConnect`. Re-listing over the connection just opened
+ * honours `maxAgeMs` without the reconnect the caller declined: "stale" means the
+ * tool set needs re-reading, not that the transport needs rebuilding.
+ * `refresh()` also clears the carried `cachedAt`, so the write-back records the
+ * new age rather than carrying the snapshot's forward.
+ */
+async function refreshStaleReplay(handle) {
+    // `refresh()` swaps `handle.tools` to a fresh array exactly when the re-list
+    // succeeded, before it persists — so the reference tells re-list failure
+    // apart from persistence failure. Keying on that rather than on
+    // `MCPCacheWriteError` matters because persistence can fail OUTSIDE the
+    // store op too (the caller's OAuth provider rejecting inside `snapshot()`),
+    // and that failure must not masquerade as "re-listing tools failed".
+    const before = handle.tools;
+    try {
+        await handle.refresh();
+    }
+    catch (refreshErr) {
+        // Tools adopted: the re-list succeeded and only the persistence after it
+        // broke. Survivable, and must not fail the call — the tools ARE current;
+        // only the cache entry is stale, and the next rehydrate re-reads it.
+        // (A transient store outage here used to discard a connection whose tools
+        // had just been read successfully.)
+        if (handle.tools !== before || refreshErr instanceof MCPCacheWriteError) {
+            return;
+        }
+        // A failed re-list is not. The connection is live and the snapshot's tools
+        // would work, but they are older than the caller's own `maxAgeMs` — serving
+        // them anyway is exactly the unbounded-age bug that check exists to prevent.
+        await closeQuietly(handle);
+        throw new MCPStaleSnapshotError('Snapshot is older than staleness.maxAgeMs and re-listing tools failed', {
+            cause: refreshErr,
+        });
+    }
+}
+/**
+ * The cases where a successful replay still writes to the cache store.
+ *
+ * The replay write-back is normally skipped as a no-op — the snapshot it would
+ * persist is the one just read. Three exceptions where the write genuinely does
+ * something, all best-effort:
+ *
+ * 1. **OAuth token rotation.** With `cacheCredentials: true` and an OAuth
+ *    provider, the old per-hit write re-serialized the provider's *current*
+ *    tokens; without it the stored entry keeps cold-connect-time tokens, and
+ *    once those pass `expiresAt` every rehydrate takes the fresh-connect
+ *    detour even though the provider holds a valid refreshed token.
+ * 2. **Static credential rotation.** Same story for `bearer`/`headers` auth:
+ *    the old per-hit write kept the stored `auth.headers` in sync with the
+ *    caller's live `auth`, so a rotated API key propagated on the next warm
+ *    hit. When the caller passes static auth under `cacheCredentials: true`
+ *    and the resolved headers differ from the stored ones, the stored entry's
+ *    header block is updated — otherwise a later credential-bearing rehydrate
+ *    (`authFromSnapshot`) would dial with the superseded secret.
+ * 3. **Legacy `sessionId` scrub.** Entries written by earlier versions can
+ *    carry a bearer-equivalent `Mcp-Session-Id` under `cacheCredentials`; with
+ *    the warm path never rewriting, that credential-grade value would sit in
+ *    the external store indefinitely. One write — the entry copied without the
+ *    field — removes it.
+ *
+ * All three share one invariant: they only ever REWRITE an entry the store
+ * already holds, read back first. The credential grafts move only their block
+ * onto the stored entry rather than re-serializing this call's live state — a
+ * direct `rehydrateMCPTools` may have loaded its snapshot from a file or
+ * another key, and writing that snapshot's (older) tool set and `cachedAt`
+ * over the store's entry would roll back a newer entry written by a concurrent
+ * `refresh()`. Copying the stored entry also cannot strip or introduce
+ * credentials the way a re-serialize under this call's options could (the
+ * DEV-766 hazard): each block is only updated where the stored entry already
+ * carries that block.
+ */
+/**
+ * Graft the provider's current tokens onto the STORED entry — never the other
+ * way round.
+ *
+ * Only the token block moves; the stored entry's tool set and `cachedAt` stay
+ * untouched, so a direct rehydrate whose input snapshot is older than the
+ * store's entry (a concurrent `refresh()` having written since) cannot roll the
+ * entry back. Returns undefined — no write — when the stored entry carries no
+ * tokens (grafting would introduce credentials into an entry that never held
+ * them) or the fresh serialize produced none.
+ *
+ * An UNROTATED token — same access token as stored — grafts nothing at all,
+ * for three reasons that all point the same way. No per-replay write (the
+ * documented warm-path economy, and no re-touching TTL-extending stores). No
+ * expiry ratchet: `serializeServer` stamps `expiresAt` as `Date.now() +
+ * expires_in * 1000`, but `expires_in` is relative to *issuance* (RFC 6749
+ * §5.1), so re-persisting the same token would push the recorded expiry
+ * forward each replay and `tokensExpired()` would never trip. And no field
+ * loss: a wholesale replace would drop stored fields the provider's `tokens()`
+ * no longer reports (a `refreshToken` held elsewhere, say) without any actual
+ * rotation. A rotated token replaces the block, fresh restamp included — the
+ * SDK just obtained it, so its relative `expires_in` genuinely is from ~now.
+ */
+function graftRotatedTokens(stored, serialized) {
+    const prev = stored.auth?.tokens;
+    const next = serialized.auth?.tokens;
+    if (prev === undefined || next === undefined) {
+        return undefined;
+    }
+    if (next.accessToken === prev.accessToken) {
+        return undefined;
+    }
+    return {
+        ...stored,
+        auth: {
+            ...stored.auth,
+            tokens: {
+                ...next,
+            },
+        },
+    };
+}
+function headersEqual(a, b) {
+    const aKeys = Object.keys(a);
+    return aKeys.length === Object.keys(b).length && aKeys.every((k) => a[k] === b[k]);
+}
+/**
+ * Graft the caller's current static headers onto the STORED entry — the
+ * `bearer`/`headers` counterpart of {@link graftRotatedTokens}, under the same
+ * invariants: only the header block moves, and only where the stored entry
+ * already carries headers (never introducing credentials into an entry that
+ * had none). Returns undefined — no write — when there is nothing to update.
+ */
+function graftStaticHeaders(stored, headers) {
+    const prev = stored.auth?.headers;
+    if (prev === undefined || Object.keys(prev).length === 0 || Object.keys(headers).length === 0) {
+        return undefined;
+    }
+    if (headersEqual(prev, headers)) {
+        return undefined;
+    }
+    return {
+        ...stored,
+        auth: {
+            ...stored.auth,
+            headers,
+        },
+    };
+}
+/**
+ * Compute the maintenance rewrite for a stored entry, if any: an OAuth token
+ * graft, a static-header graft, or nothing. Split from
+ * {@link maintainReplayedEntry} to keep each piece readable.
+ */
+async function graftForReplay(args) {
+    const { options, handle, stored, effectiveAuth } = args;
+    if (options.cacheCredentials !== true) {
+        return undefined;
+    }
+    if (isOAuthAuth(effectiveAuth)) {
+        return graftRotatedTokens(stored, await handle.serialize());
+    }
+    // Static graft keys on the CALLER's auth, not `effectiveAuth`: auth derived
+    // from the input snapshot is by definition not a rotation.
+    if (options.auth !== undefined) {
+        return graftStaticHeaders(stored, resolveAuth(options.auth).headers);
+    }
+    return undefined;
+}
+async function maintainReplayedEntry(args) {
+    const { options, handle, cacheKey, effectiveAuth } = args;
+    const store = options.cache?.store;
+    if (store === undefined) {
+        return;
+    }
+    try {
+        // Cheap gates first, so a warm hit with nothing to maintain performs ZERO
+        // store operations. Credential grafts can only apply under
+        // `cacheCredentials: true`; the scrub can only be needed when the *input*
+        // snapshot carries a legacy `sessionId` (on the warm `createMCPTools` path
+        // the input IS the store's entry, so a sessionId-free input — every entry
+        // this version writes — means a sessionId-free store).
+        const mayGraft = options.cacheCredentials === true &&
+            (isOAuthAuth(effectiveAuth) || options.auth !== undefined);
+        if (!mayGraft && args.snapshot.sessionId === undefined) {
+            return;
+        }
+        // Read back before writing: every maintenance write is a rewrite of what
+        // THIS store currently holds, never a serialize of this call's state — a
+        // direct rehydrate's input snapshot may be older than the store's entry (a
+        // concurrent refresh() having written since), and its auth may belong to a
+        // store that never held credentials. One read per maintained replay is the
+        // price.
+        const stored = await store.get(cacheKey);
+        if (stored === null || stored === undefined || !isSerializedMCPServer(stored)) {
+            return;
+        }
+        const grafted = mayGraft
+            ? await graftForReplay({
+                options,
+                handle,
+                stored,
+                effectiveAuth,
+            })
+            : undefined;
+        // Nothing to graft and nothing to scrub — no write. A legacy sessionId in
+        // the stored entry composes with either graft into one write.
+        if (grafted === undefined && stored.sessionId === undefined) {
+            return;
+        }
+        const next = {
+            ...(grafted ?? stored),
+        };
+        delete next.sessionId;
+        await store.set(cacheKey, next);
+    }
+    catch {
+        // Best-effort, like every other store write: a cache outage never fails a
+        // working replay.
+    }
+}
+/**
+ * Rebuild an {@link MCPToolsHandle} from a cached snapshot. On the happy path we
+ * reconnect the transport and rebuild tools directly from the snapshot —
+ * skipping `listTools()`. If cached tokens are expired, credentials are missing,
+ * the snapshot is older than `staleness.maxAgeMs`, or the replay connection
+ * fails, we transparently fall back to a fresh connect (unless
+ * `reconnectOnExpiry` is false) — with one exception: a credential rejection is
+ * not retried, because the fallback reuses the same auth and re-attempting
+ * would re-drive an OAuth authorization flow. See {@link
+ * RehydrateMCPToolsOptions.reconnectOnExpiry}.
+ */
+export async function rehydrateMCPTools(options) {
+    const { snapshot } = options;
+    if (!isSerializedMCPServer(snapshot)) {
+        throw new MCPCacheError('Invalid MCP snapshot: failed structural validation');
+    }
+    const reconnectOnExpiry = options.reconnectOnExpiry ?? true;
+    const url = new URL(snapshot.url);
+    const cacheKey = options.cache?.key ?? defaultCacheKey(url.href);
+    // Fall back to credentials cached in the snapshot when the caller didn't pass
+    // any — otherwise a credential-bearing snapshot would reconnect unauthenticated.
+    const effectiveAuth = options.auth ?? authFromSnapshot(snapshot);
+    const hasCredentials = effectiveAuth !== undefined;
+    // Route the fallback through `freshConnect`, NOT `createMCPTools`: the latter
+    // would re-read this same snapshot and re-enter rehydrate, recursing without
+    // bound on any no-credential / expired-token snapshot. `freshConnect` still
+    // writes the refreshed result back to the cache via `makeHandle`.
+    const createOptions = toCreateOptions(options, snapshot, effectiveAuth);
+    // Staleness is checked here as well as in `createMCPTools`'s cache-hit path,
+    // so a direct `rehydrateMCPTools()` call honours `staleness.maxAgeMs` too.
+    // Previously only the `createMCPTools` route checked it, meaning callers who
+    // held their own snapshot silently got unbounded-age tools.
+    const staleSnapshot = snapshotIsStale(snapshot, options.staleness?.maxAgeMs);
+    if ((tokensExpired(snapshot) || !hasCredentials || staleSnapshot) && reconnectOnExpiry) {
+        return freshConnect(createOptions, url, cacheKey);
+    }
+    // Held outside the `try` so the `catch` can tear it down. `connect()` releases
+    // its own client when it fails, so this stays undefined on that path and only
+    // a post-connect failure has something to close.
+    let connection;
+    try {
+        connection = await connect(toReplayConnectOptions({
+            options,
+            snapshot,
+            url,
+            effectiveAuth,
+        }));
+        // Rebuild tools from the snapshot — no listTools() round-trip.
+        const handle = await makeHandle({
+            connection,
+            options: createOptions,
+            context: {
+                url,
+                transport: connection.transport,
+                cacheKey,
+            },
+            initialToolDefs: snapshotToToolDefs(snapshot),
+            // Replay, not a listTools() — keep the snapshot's original age so
+            // staleness.maxAgeMs stays measurable across repeated rehydrates.
+            replayedCachedAt: snapshot.cachedAt,
+        });
+        if (staleSnapshot) {
+            // `refresh()` re-listed and wrote the entry through `serialize` — which
+            // carries the provider's current tokens and omits `sessionId` — so every
+            // maintenance concern below is already satisfied. Running the scrub here
+            // would clobber the just-refreshed entry with the caller's older input
+            // snapshot.
+            await refreshStaleReplay(handle);
+        }
+        else {
+            await maintainReplayedEntry({
+                options,
+                snapshot,
+                handle,
+                cacheKey,
+                effectiveAuth,
+            });
+        }
+        return handle;
+    }
+    catch (err) {
+        // The stale re-list above already closed and reported; let its verdict stand
+        // rather than re-wrapping it as a generic rehydrate failure (and
+        // double-closing). It is a deliberate refusal, not a rehydrate that broke.
+        if (err instanceof MCPStaleSnapshotError) {
+            throw err;
+        }
+        // Tear down the replay connection before leaving this path, mirroring
+        // `freshConnect`'s guarantee in handle.ts. Whether we fall back (which opens
+        // its own connection) or rethrow, nothing else holds a reference to this
+        // one, so without the close its transport leaks. Reachable via `buildTools`
+        // rejecting on a duplicate tool name, or a caller's `cache.store.set`
+        // throwing during the initial write.
+        if (connection !== undefined) {
+            await closeQuietly(connection);
+        }
+        // The fallback is a third reconnect layer, and it reuses the same auth. If
+        // the replay's connect ended in a credential rejection, `freshConnect` would
+        // re-drive the OAuth flow — a third `redirectToAuthorization` behind the two
+        // layers below that already guard against exactly this. Rejected credentials
+        // are not something a fresh connection fixes.
+        // An aborted caller gets no fallback either — the third reconnect layer,
+        // matching the guards on the SSE fallback and the legacy retry. Dialling a
+        // fresh connection after the caller cancelled would both waste the dial and
+        // bury the cancellation under a "failed to connect" it didn't cause.
+        const { UnauthorizedError } = await loadMcpSdk();
+        if (reconnectOnExpiry &&
+            options.signal?.aborted !== true &&
+            !isAuthFailure({
+                err,
+                auth: effectiveAuth,
+                UnauthorizedErrorType: UnauthorizedError,
+            })) {
+            return freshConnect(createOptions, url, cacheKey);
+        }
+        throw new MCPCacheError('Failed to rehydrate MCP connection from snapshot', {
+            cause: err,
+        });
+    }
+}
+//# sourceMappingURL=rehydrate.js.map

package/esm/mcp/rehydrate.js.map

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

package/esm/mcp/resource-tools.d.ts

@@ -0,0 +1,17 @@
+import type { Client } from '@modelcontextprotocol/client';
+import type { McpBranded } from '../lib/tool-types.js';
+export interface ResourceToolsOptions {
+    client: Client;
+    namePrefix?: string;
+    signal?: AbortSignal;
+}
+/**
+ * Build synthetic tools that let the model browse and read MCP resources
+ * through the normal tool loop:
+ * - `list_resources`: concrete resources plus resource templates.
+ * - `read_resource`: fetch a resource's contents by URI.
+ *
+ * Only call this when the server advertises the `resources` capability.
+ */
+export declare function buildResourceTools(options: ResourceToolsOptions): McpBranded[];
+//# sourceMappingURL=resource-tools.d.ts.map

package/esm/mcp/resource-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-tools.d.ts","sourceRoot":"","sources":["../../src/mcp/resource-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,8BAA8B,CAAC;AAG3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAgFD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,oBAAoB,GAAG,UAAU,EAAE,CAwH9E"}