@openrouter/mcp 0.0.1 → 1.0.0

package/esm/errors.d.ts

@@ -24,12 +24,59 @@ export declare class MCPCacheError extends MCPError {
         cause?: unknown;
     });
 }
+/**
+ * Raised when the tool list was read successfully but writing the snapshot back
+ * to the caller's `MCPCacheStore` failed.
+ *
+ * Distinct from the read failing, because the consequences differ completely: the
+ * connection is live and its tools are current, so the only thing lost is a cache
+ * entry. Callers who treat a store outage as fatal can catch this; callers who
+ * would rather keep working with a warm handle can ignore it.
+ *
+ * Subclasses {@link MCPCacheError}, so existing catch sites keep working.
+ */
+export declare class MCPCacheWriteError extends MCPCacheError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Raised when a snapshot is older than `staleness.maxAgeMs` and the re-list that
+ * would have refreshed it failed — so the only tools available are ones the
+ * caller declared too old to use.
+ *
+ * Subclasses {@link MCPCacheError}, so existing `catch (e instanceof
+ * MCPCacheError)` sites keep working. Catch this specifically to fall back to
+ * stale-but-usable tools instead of failing.
+ */
+export declare class MCPStaleSnapshotError extends MCPCacheError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
 /**
  * Raised when connecting to the MCP server fails across all attempted transports.
  */
 export declare class MCPConnectionError extends MCPError {
+    /**
+     * Every failure behind this one, in attempt order.
+     *
+     * `cause` holds only the last attempt, which loses information: an
+     * `UnauthorizedError` from the Streamable HTTP attempt matters even when the
+     * SSE fallback then failed for an unrelated reason (a URL that simply isn't an
+     * SSE endpoint answering 404). Named `errors` to match `AggregateError`, so it
+     * reads the way callers expect rather than as a bespoke field.
+     *
+     * Always populated: a single-attempt failure contributes its one underlying
+     * error, so `errors[errors.length - 1]` and `cause` agree and a caller can
+     * iterate `errors` alone without special-casing the single-attempt shape —
+     * which matters most on the auth short-circuit, where exactly one attempt was
+     * made and its rejection is the thing worth finding.
+     */
+    readonly errors: readonly unknown[];
     constructor(message: string, options?: {
         cause?: unknown;
+        errors?: readonly unknown[];
     });
 }
 //# sourceMappingURL=errors.d.ts.map

package/esm/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;gBAE/B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CAKJ;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,QAAQ;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAGxB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CAMJ;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,QAAQ;gBAEvC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CAKJ;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,QAAQ;gBAE5C,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CAKJ"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;gBAE/B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CAKJ;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,QAAQ;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAGxB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CAMJ;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,QAAQ;gBAEvC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CAKJ;AAED;;;;;;;;;;GAUG;AACH,qBAAa,kBAAmB,SAAQ,aAAa;gBAEjD,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CAKJ;AAED;;;;;;;;GAQG;AACH,qBAAa,qBAAsB,SAAQ,aAAa;gBAEpD,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CAKJ;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,QAAQ;IAC9C;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAC;gBAGlC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;KAC7B;CAcJ"}

package/esm/errors.js

@@ -27,6 +27,38 @@ export class MCPCacheError extends MCPError {
         this.name = 'MCPCacheError';
     }
 }
+/**
+ * Raised when the tool list was read successfully but writing the snapshot back
+ * to the caller's `MCPCacheStore` failed.
+ *
+ * Distinct from the read failing, because the consequences differ completely: the
+ * connection is live and its tools are current, so the only thing lost is a cache
+ * entry. Callers who treat a store outage as fatal can catch this; callers who
+ * would rather keep working with a warm handle can ignore it.
+ *
+ * Subclasses {@link MCPCacheError}, so existing catch sites keep working.
+ */
+export class MCPCacheWriteError extends MCPCacheError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'MCPCacheWriteError';
+    }
+}
+/**
+ * Raised when a snapshot is older than `staleness.maxAgeMs` and the re-list that
+ * would have refreshed it failed — so the only tools available are ones the
+ * caller declared too old to use.
+ *
+ * Subclasses {@link MCPCacheError}, so existing `catch (e instanceof
+ * MCPCacheError)` sites keep working. Catch this specifically to fall back to
+ * stale-but-usable tools instead of failing.
+ */
+export class MCPStaleSnapshotError extends MCPCacheError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'MCPStaleSnapshotError';
+    }
+}
 /**
  * Raised when connecting to the MCP server fails across all attempted transports.
  */
@@ -34,6 +66,15 @@ export class MCPConnectionError extends MCPError {
     constructor(message, options) {
         super(message, options);
         this.name = 'MCPConnectionError';
+        // Default a single-attempt failure to its own cause, so `errors` is a
+        // uniform "every attempt" list rather than empty-unless-multi.
+        this.errors =
+            options?.errors ??
+                (options?.cause !== undefined
+                    ? [
+                        options.cause,
+                    ]
+                    : []);
     }
 }
 //# sourceMappingURL=errors.js.map

package/esm/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACjC,YACE,OAAe,EACf,OAEC;QAED,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;IACzB,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,gBAAiB,SAAQ,QAAQ;IAG5C,YACE,QAAgB,EAChB,OAAe,EACf,OAEC;QAED,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,aAAc,SAAQ,QAAQ;IACzC,YACE,OAAe,EACf,OAEC;QAED,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,kBAAmB,SAAQ,QAAQ;IAC9C,YACE,OAAe,EACf,OAEC;QAED,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACjC,YACE,OAAe,EACf,OAEC;QAED,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;IACzB,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,gBAAiB,SAAQ,QAAQ;IAG5C,YACE,QAAgB,EAChB,OAAe,EACf,OAEC;QAED,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,aAAc,SAAQ,QAAQ;IACzC,YACE,OAAe,EACf,OAEC;QAED,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,OAAO,kBAAmB,SAAQ,aAAa;IACnD,YACE,OAAe,EACf,OAEC;QAED,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,qBAAsB,SAAQ,aAAa;IACtD,YACE,OAAe,EACf,OAEC;QAED,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,kBAAmB,SAAQ,QAAQ;IAkB9C,YACE,OAAe,EACf,OAGC;QAED,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,sEAAsE;QACtE,+DAA+D;QAC/D,IAAI,CAAC,MAAM;YACT,OAAO,EAAE,MAAM;gBACf,CAAC,OAAO,EAAE,KAAK,KAAK,SAAS;oBAC3B,CAAC,CAAC;wBACE,OAAO,CAAC,KAAK;qBACd;oBACH,CAAC,CAAC,EAAE,CAAC,CAAC;IACZ,CAAC;CACF"}

package/esm/handle.d.ts

@@ -9,6 +9,18 @@ export declare function normalizeUrl(url: string | URL): URL;
  * `tools/list` is paginated: each response may carry a `nextCursor` that must be
  * passed back as `{ cursor }` to fetch the next page. We accumulate every page so
  * servers that paginate their tool list aren't silently truncated.
+ *
+ * Always `cacheMode: 'refresh'`. SDK v2 keeps a per-client response cache
+ * honouring the server's `ttlMs` on `tools/list` (up to 24h), so the default
+ * `'use'` would serve a still-fresh cached list without a round trip. That is
+ * fine for an opportunistic read but wrong for every caller here: `refresh()`
+ * documents a forced re-read, `freshConnect` is establishing the tool set for the
+ * first time, and the stale-replay path exists precisely because the age of the
+ * cached list is no longer acceptable. `'refresh'` fetches and re-stores, so the
+ * cache stays warm for the SDK's own readers.
+ *
+ * `'refresh'` rather than `'bypass'` deliberately — bypass would skip the write
+ * too, leaving a stale entry behind for anything that later reads with `'use'`.
  */
 export declare function listToolDefs(connection: MCPConnection, signal: AbortSignal | undefined): Promise<McpToolDef[]>;
 interface HandleContext {
@@ -21,6 +33,19 @@ export interface MakeHandleArgs {
     options: CreateMCPToolsOptions;
     context: HandleContext;
     initialToolDefs: McpToolDef[];
+    /**
+     * `cachedAt` to carry forward when `initialToolDefs` came from a snapshot
+     * rather than a live `listTools()`. Omit on a cold connect so the write
+     * stamps now.
+     *
+     * Without this a replay would restamp `cachedAt` on the write-back below,
+     * resetting the staleness clock on a tool set that was never re-listed —
+     * so `staleness.maxAgeMs` could never fire on a repeatedly-rehydrated
+     * snapshot. Age tracks when the tools were last actually discovered, not
+     * when they were last replayed. `refresh()` clears it, because that path
+     * does re-list.
+     */
+    replayedCachedAt?: number;
 }
 /**
  * Connect, discover tools via `listTools()`, and build a handle WITHOUT

package/esm/handle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../src/handle.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAExE,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,GAAG,CAEnD;AAcD;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,aAAa,EACzB,MAAM,EAAE,WAAW,GAAG,SAAS,GAC9B,OAAO,CAAC,UAAU,EAAE,CAAC,CAsCvB;AAOD,UAAU,aAAa;IACrB,GAAG,EAAE,GAAG,CAAC;IACT,SAAS,EAAE,gBAAgB,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,aAAa,CAAC;IAC1B,OAAO,EAAE,qBAAqB,CAAC;IAC/B,OAAO,EAAE,aAAa,CAAC;IACvB,eAAe,EAAE,UAAU,EAAE,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,qBAAqB,EAC9B,GAAG,EAAE,GAAG,EACR,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,cAAc,CAAC,CAsCzB;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAmE9E"}
+{"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../src/handle.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAExE,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,GAAG,CAEnD;AAiCD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,aAAa,EACzB,MAAM,EAAE,WAAW,GAAG,SAAS,GAC9B,OAAO,CAAC,UAAU,EAAE,CAAC,CA0CvB;AAOD,UAAU,aAAa;IACrB,GAAG,EAAE,GAAG,CAAC;IACT,SAAS,EAAE,gBAAgB,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,aAAa,CAAC;IAC1B,OAAO,EAAE,qBAAqB,CAAC;IAC/B,OAAO,EAAE,aAAa,CAAC;IACvB,eAAe,EAAE,UAAU,EAAE,CAAC;IAC9B;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,qBAAqB,EAC9B,GAAG,EAAE,GAAG,EACR,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,cAAc,CAAC,CA+CzB;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CA4H9E"}

package/esm/handle.js

@@ -1,5 +1,7 @@
 import { buildTools } from './build-tools.js';
 import { serializeServer } from './cache/serialize.js';
+import { closeQuietly } from './close-quietly.js';
+import { MCPCacheWriteError } from './errors.js';
 import { connect } from './mcp-connection.js';
 export function normalizeUrl(url) {
     return url instanceof URL ? url : new URL(url);
@@ -14,19 +16,48 @@ const MAX_LIST_PAGES = 1000;
 function nextCursorOrUndefined(value) {
     return typeof value === 'string' && value.length > 0 ? value : undefined;
 }
+/**
+ * Parse a server-advertised doom-loop identity from a tool definition's
+ * `_meta['openrouter/loopKey']`: a field-name array (the declarative subset
+ * of arguments identifying a call) or `false` (tool exempt). Data-only by
+ * design — functions can't cross the wire; any other shape is ignored.
+ */
+function advertisedLoopKey(meta) {
+    const advertised = meta?.['openrouter/loopKey'];
+    if (advertised === false) {
+        return false;
+    }
+    if (Array.isArray(advertised) && advertised.every((f) => typeof f === 'string')) {
+        return advertised;
+    }
+    return undefined;
+}
 /**
  * Read the discovered tools off the live connection into our internal shape.
  *
  * `tools/list` is paginated: each response may carry a `nextCursor` that must be
  * passed back as `{ cursor }` to fetch the next page. We accumulate every page so
  * servers that paginate their tool list aren't silently truncated.
+ *
+ * Always `cacheMode: 'refresh'`. SDK v2 keeps a per-client response cache
+ * honouring the server's `ttlMs` on `tools/list` (up to 24h), so the default
+ * `'use'` would serve a still-fresh cached list without a round trip. That is
+ * fine for an opportunistic read but wrong for every caller here: `refresh()`
+ * documents a forced re-read, `freshConnect` is establishing the tool set for the
+ * first time, and the stale-replay path exists precisely because the age of the
+ * cached list is no longer acceptable. `'refresh'` fetches and re-stores, so the
+ * cache stays warm for the SDK's own readers.
+ *
+ * `'refresh'` rather than `'bypass'` deliberately — bypass would skip the write
+ * too, leaving a stale entry behind for anything that later reads with `'use'`.
  */
 export async function listToolDefs(connection, signal) {
-    const requestOptions = signal !== undefined
-        ? {
+    const requestOptions = {
+        cacheMode: 'refresh',
+        ...(signal !== undefined && {
             signal,
-        }
-        : undefined;
+        }),
+    };
     const collected = [];
     let cursor;
     for (let page = 0; page < MAX_LIST_PAGES; page += 1) {
@@ -37,6 +68,7 @@ export async function listToolDefs(connection, signal) {
             : undefined;
         const { tools, nextCursor } = await connection.client.listTools(params, requestOptions);
         for (const t of tools) {
+            const loopKey = advertisedLoopKey(t._meta);
             collected.push({
                 name: t.name,
                 ...(t.description !== undefined && {
@@ -46,6 +78,9 @@ export async function listToolDefs(connection, signal) {
                 ...(t.outputSchema !== undefined && {
                     outputSchema: t.outputSchema,
                 }),
+                ...(loopKey !== undefined && {
+                    loopKey,
+                }),
             });
         }
         const next = nextCursorOrUndefined(nextCursor);
@@ -89,6 +124,15 @@ export async function freshConnect(options, url, cacheKey) {
         ...(options.onElicitation !== undefined && {
             onElicitation: options.onElicitation,
         }),
+        ...(options.protocolNegotiation !== undefined && {
+            protocolNegotiation: options.protocolNegotiation,
+        }),
+        ...(options.probeTimeoutMs !== undefined && {
+            probeTimeoutMs: options.probeTimeoutMs,
+        }),
+        ...(options.signal !== undefined && {
+            signal: options.signal,
+        }),
     });
     // Tear the connection down if discovery or the initial cache write throws —
     // otherwise the open transport (HTTP keep-alive / SSE stream) leaks.
@@ -106,7 +150,7 @@ export async function freshConnect(options, url, cacheKey) {
         });
     }
     catch (err) {
-        await connection.close().catch(() => { });
+        await closeQuietly(connection);
         throw err;
     }
 }
@@ -118,6 +162,8 @@ export async function makeHandle(args) {
     const { connection, options, context, initialToolDefs } = args;
     const listeners = new Set();
     let toolDefs = initialToolDefs;
+    // Cleared by refresh(): once we have re-listed, age is measured from now.
+    let replayedCachedAt = args.replayedCachedAt;
     const serverInfo = connection.client.getServerVersion();
     const rebuild = () => buildTools(buildToolsArgs(connection, toolDefs, options));
     let tools = rebuild();
@@ -127,16 +173,47 @@ export async function makeHandle(args) {
         toolDefs,
         serverInfo,
         options,
+        ...(replayedCachedAt !== undefined && {
+            cachedAt: replayedCachedAt,
+        }),
     }));
     const writeCache = async () => {
         const store = options.cache?.store;
         if (store === undefined) {
             return;
         }
-        await store.set(context.cacheKey, await snapshot());
+        // Built OUTSIDE the try: `snapshot()` can reject from the caller's own
+        // OAuth provider (`provider.tokens()`), and relabelling that as a cache
+        // write failure would send it down every "store outages are harmless"
+        // path — swallowed by the list_changed handler, ignored by
+        // `refreshStaleReplay`, and dismissed by callers following the documented
+        // `MCPCacheWriteError` pattern. Only the store op earns the tag.
+        const payload = await snapshot();
+        try {
+            await store.set(context.cacheKey, payload);
+        }
+        catch (writeErr) {
+            // Tagged so callers can tell a store outage from a failed read. The two
+            // look identical coming out of `refresh()` but mean opposite things: a
+            // failed read leaves the tool set unknown, while a failed write leaves a
+            // live connection with current tools and only a stale cache entry.
+            throw new MCPCacheWriteError('Failed to write the MCP snapshot to the cache store', {
+                cause: writeErr,
+            });
+        }
     };
+    // INVARIANT internal callers rely on: `refresh()` swaps `tools` to a fresh
+    // array (rebuild() always allocates) exactly when the re-list succeeded, and
+    // it does so BEFORE attempting to persist. A caller that captured the old
+    // reference can therefore tell "the re-list failed" (reference unchanged)
+    // from "only something after the re-list failed" (reference changed) without
+    // inspecting the error — which no error-class check can do reliably, since
+    // persistence can fail outside the store op too (the caller's own OAuth
+    // provider rejecting inside `snapshot()`).
     const refresh = async () => {
         toolDefs = await listToolDefs(connection, options.signal);
+        // Re-listed, so the snapshot is genuinely current from here on.
+        replayedCachedAt = undefined;
         tools = rebuild();
         await writeCache();
         return tools;
@@ -144,17 +221,42 @@ export async function makeHandle(args) {
     if (options.autoRefreshOnListChanged ?? true) {
         connection.setToolListChangedHandler(() => {
             // Fire-and-forget, but never let a failed refresh escape as an unhandled
-            // rejection. On failure listeners keep the last good tool set.
+            // rejection. Whether to announce is keyed on ADOPTION (the reference
+            // swap above), not on error class: once `refresh()` has swapped `tools`,
+            // skipping the announcement would leave subscribers permanently out of
+            // sync with `handle.tools`, no matter what broke afterwards — a store
+            // outage and an OAuth provider failing during serialize gate it equally
+            // little. On a failed re-list the reference is untouched and subscribers
+            // correctly keep the last good set.
+            const before = tools;
             void refresh()
-                .then((next) => {
+                .catch(() => undefined)
+                .then(() => {
+                if (tools === before) {
+                    return;
+                }
                 for (const listener of listeners) {
-                    listener(next);
+                    listener(tools);
                 }
             })
                 .catch(() => { });
         });
     }
-    await writeCache();
+    // Skipped entirely on a replay: with `replayedCachedAt` carried forward the
+    // snapshot we would write is the one just read — same tool defs, same
+    // `cachedAt` — so the write is an external store round-trip per rehydrate
+    // buying nothing. (It also cannot *refresh* anything: preserving the age is
+    // the point.) A cold connect writes; `refresh()` clears `replayedCachedAt`
+    // and writes. Skipping here additionally narrows DEV-766's surface — one
+    // fewer path that can rewrite a credentialed entry under different options.
+    //
+    // Best-effort when it does run: the handle is fully usable without its cache
+    // entry, so a store outage should not stop a connection that already
+    // succeeded. `refresh()` reports write failures as `MCPCacheWriteError` for
+    // callers that do care.
+    if (args.replayedCachedAt === undefined) {
+        await writeCache().catch(() => { });
+    }
     return {
         get tools() {
             return tools;
@@ -193,6 +295,9 @@ function buildToolsArgs(connection, toolDefs, options) {
         ...(options.signal !== undefined && {
             signal: options.signal,
         }),
+        ...(options.loopKeys !== undefined && {
+            loopKeys: options.loopKeys,
+        }),
         ...(options.resources !== undefined && {
             resources: options.resources,
         }),
@@ -206,13 +311,10 @@ function serializeArgs(args) {
         transport: connection.transport,
         toolDefs,
         cacheCredentials: options.cacheCredentials ?? false,
-        cachedAt: Date.now(),
+        cachedAt: args.cachedAt ?? Date.now(),
         ...(serverInfo !== undefined && {
             serverInfo,
         }),
-        ...(connection.sessionId !== undefined && {
-            sessionId: connection.sessionId,
-        }),
         ...(options.auth !== undefined && {
             auth: options.auth,
         }),

package/esm/handle.js.map

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

package/esm/index.d.ts

@@ -1,13 +1,13 @@
-export type { MCPAuth } from './auth/auth-types.js';
+export type { MCPAuth, MCPOAuthClientProvider } from './auth/auth-types.js';
 export type { MCPCacheStore } from './cache/cache-store.js';
 export { defaultCacheKey, InMemoryMCPCacheStore } from './cache/cache-store.js';
 export type { SerializedMCPServer, SerializedMCPToolDef, SerializedTokenSet, } from './cache/cache-types.js';
 export { isSerializedMCPServer } from './cache/cache-types.js';
 export { createMCPTools } from './create-mcp-tools.js';
-export { MCPCacheError, MCPConnectionError, MCPError, MCPToolCallError, } from './errors.js';
+export { MCPCacheError, MCPCacheWriteError, MCPConnectionError, MCPError, MCPStaleSnapshotError, MCPToolCallError, } from './errors.js';
 export type { RehydrateMCPToolsOptions } from './rehydrate.js';
 export { rehydrateMCPTools } from './rehydrate.js';
 export type { UnconvertibleSchemaMode } from './schema/json-schema-to-zod.js';
 export { convertMcpInputSchema } from './schema/json-schema-to-zod.js';
-export type { CreateMCPToolsOptions, ElicitationHandler, ElicitationResponse, MCPToolsHandle, MCPTransportKind, ResourcesOption, } from './types.js';
+export type { CreateMCPToolsOptions, ElicitationHandler, ElicitationResponse, MCPProtocolNegotiation, MCPProtocolRevision, MCPToolsHandle, MCPTransportKind, ResourcesOption, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,YAAY,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACpD,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAE5D,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAChF,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,QAAQ,EACR,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,YAAY,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAE9E,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAEvE,YAAY,EACV,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,eAAe,GAChB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,YAAY,EAAE,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC5E,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAE5D,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAChF,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,QAAQ,EACR,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,YAAY,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAE9E,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAEvE,YAAY,EACV,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,eAAe,GAChB,MAAM,YAAY,CAAC"}

package/esm/index.js

@@ -4,7 +4,7 @@ export { defaultCacheKey, InMemoryMCPCacheStore } from './cache/cache-store.js';
 export { isSerializedMCPServer } from './cache/cache-types.js';
 export { createMCPTools } from './create-mcp-tools.js';
 // Errors
-export { MCPCacheError, MCPConnectionError, MCPError, MCPToolCallError, } from './errors.js';
+export { MCPCacheError, MCPCacheWriteError, MCPConnectionError, MCPError, MCPStaleSnapshotError, MCPToolCallError, } from './errors.js';
 export { rehydrateMCPTools } from './rehydrate.js';
 // Schema conversion (exported for testing/reuse)
 export { convertMcpInputSchema } from './schema/json-schema-to-zod.js';

package/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6BAA6B;AAK7B,QAAQ;AACR,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAMhF,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,SAAS;AACT,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,QAAQ,EACR,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnD,iDAAiD;AACjD,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6BAA6B;AAK7B,QAAQ;AACR,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAMhF,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,SAAS;AACT,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,QAAQ,EACR,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnD,iDAAiD;AACjD,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC"}

package/esm/mcp-connection.d.ts

@@ -1,6 +1,7 @@
-import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { Client } from '@modelcontextprotocol/client';
 import type { MCPAuth } from './auth/auth-types.js';
-import type { ElicitationHandler, MCPTransportKind } from './types.js';
+import type { MCPProtocolNegotiation, MCPTransportKind } from './transport-types.js';
+import type { ElicitationHandler } from './types.js';
 export interface ConnectOptions {
     url: URL;
     transport?: MCPTransportKind;
@@ -10,12 +11,41 @@ export interface ConnectOptions {
         name: string;
         version: string;
     };
+    /**
+     * Streamable HTTP session id to resume.
+     *
+     * @deprecated Ignored by 2026-07-28 servers — protocol-level sessions are
+     * removed (SEP-2567). Still honoured on 2025-era connections.
+     */
     sessionId?: string;
     onElicitation?: ElicitationHandler;
+    protocolNegotiation?: MCPProtocolNegotiation;
+    /**
+     * Aborts the connect — every transport attempt, the negotiation probe, and
+     * the implicit legacy retry. Without this a caller with its own deadline has
+     * no way to bound the ladder, whose worst case is minutes (see
+     * {@link DEFAULT_PROBE_TIMEOUT_MS}).
+     */
+    signal?: AbortSignal;
+    /**
+     * Ceiling on the `server/discover` probe, in ms. Defaults to
+     * `DEFAULT_PROBE_TIMEOUT_MS` (30000).
+     *
+     * Raise it for a server that is slow to answer its first request; the SDK's own
+     * default is the full request timeout, which makes a hanging gateway far slower
+     * to fail than it needs to be.
+     */
+    probeTimeoutMs?: number;
 }
 export interface MCPConnection {
     client: Client;
     transport: MCPTransportKind;
+    /**
+     * Session id reported by the transport, when there is one.
+     *
+     * @deprecated `undefined` on 2026-07-28 connections (SEP-2567) and on SSE,
+     * which never had a protocol-level session.
+     */
     sessionId?: string;
     /**
      * Register a callback for `tools/list_changed`. Settable after connect so the
@@ -25,11 +55,88 @@ export interface MCPConnection {
     close(): Promise<void>;
 }
 /**
- * Connect a `Client` to the MCP server. Defaults to Streamable HTTP and falls
- * back to SSE on connection failure (legacy servers), unless a transport is
- * pinned explicitly. Auth, the elicitation handler, and the list_changed
- * subscription are wired into the single connected client so they apply to
- * discovery and every tool call.
+ * Build the configured `Client` — negotiation mode, elicitation handler, and the
+ * `tools/list_changed` subscription — without connecting it.
+ *
+ * Exported for tests only, and deliberately not re-exported from the package
+ * entrypoint. It is the seam that lets a test drive the real handler wiring over
+ * `InMemoryTransport`: the notification method name is compile-checked (it is a
+ * `NotificationMethod` literal union, so a typo fails `tsc`), but the *dispatch*
+ * — that an inbound notification actually reaches `setToolListChangedHandler`'s
+ * callback — is only observable end to end. Without this seam, default-on
+ * `autoRefreshOnListChanged` could be silently dead with every test green.
+ *
+ * @internal
+ */
+export declare function makeClientForTest(options: ConnectOptions, onListChanged: () => void): Client;
+/**
+ * Did any attempt behind this failure end in the server rejecting our
+ * credentials?
+ *
+ * Searches the whole tree rather than the `cause` spine, because a single
+ * `connect()` can fail more than once: `connectWithNegotiation` wraps transport
+ * errors in `MCPConnectionError`, and on the two-transport path it records both
+ * attempts in `errors`. Checking only `cause` would miss an `UnauthorizedError`
+ * from the Streamable HTTP attempt whenever the SSE fallback then failed for an
+ * unrelated reason — a URL that isn't an SSE endpoint answering 404 never
+ * reaches the auth path — and the retry would re-drive the OAuth flow anyway.
+ *
+ * Depth-capped: a cyclic `cause` would otherwise hang, and real chains here are
+ * two or three links.
+ *
+ * Exported for `rehydrateMCPTools`, whose fallback-to-`freshConnect` is a third
+ * reconnect layer with the same duplicated-OAuth hazard; deliberately not
+ * re-exported from the package entrypoint.
+ */
+export declare function isAuthFailure(err: unknown, auth: MCPAuth | undefined, depth?: number): boolean;
+/**
+ * Connect a `Client` to the MCP server, degrading to the 2025-era handshake if
+ * protocol negotiation gets in the way.
+ *
+ * We default `protocolNegotiation` to `'auto'` where the SDK defaults to
+ * `'legacy'`, so every connection's first request is a `server/discover` probe.
+ * On its own that would be a connectivity regression: a proxy, WAF, or strict
+ * gateway that hangs or 5xx's on an unknown method takes a server from working
+ * to failing, and the SSE fallback re-probes and fails identically — so the
+ * two-transport fallback, which looks like defense in depth, collapses to a
+ * single point of failure against exactly the infrastructure it should rescue.
+ *
+ * So when the caller left `protocolNegotiation` unset, a failed connect is
+ * retried once with `'legacy'`. That makes `'auto'` strictly additive: modern
+ * servers get the new revision, everything else lands exactly where it did
+ * before this package started probing. The cost is one extra attempt on a path
+ * that is already failing, which is where latency matters least.
+ *
+ * The retry fires on **any** failure rather than only on ones that look like
+ * probe timeouts. Inspecting the cause would avoid a wasted attempt against a
+ * genuinely dead server, but it would couple this to SDK error codes — and a
+ * reshaped error would silently disable the degradation, which is the failure
+ * mode this package keeps getting bitten by.
+ *
+ * Two bounds keep the retry from making a bad situation worse:
+ *
+ * 1. **It is skipped on an auth failure.** `UnauthorizedError` means the
+ *    transport reached the server and the credentials were rejected — nothing a
+ *    different protocol revision changes. Retrying would re-drive the OAuth
+ *    provider's authorization flow: a second `redirectToAuthorization`, a second
+ *    saved PKCE verifier overwriting the first. Replaying a failure that had
+ *    side effects is worse than not retrying.
+ * 2. **It re-walks the same transport ladder the first pass did.** An earlier
+ *    revision pinned Streamable HTTP to cap the attempt count, which broke the
+ *    case this whole mechanism exists for: a legacy server reachable *only* over
+ *    SSE, behind infrastructure that chokes on the probe, would fail under
+ *    `'auto'` and then never be offered SSE again. Correctness wins over the
+ *    attempt count here — a server that used to connect must still connect.
+ *
+ * So the worst case for a genuinely unreachable server is four `connect()`
+ * calls, two per negotiation mode. That is the honest cost of guaranteeing no
+ * working setup regresses, and it is paid only on a path that was already going
+ * to fail. The bound that matters is that it is a fixed multiple rather than a
+ * retry loop.
+ *
+ * An **explicit** `protocolNegotiation` is honoured exactly, including
+ * `'auto'`: asking for a mode means asking for its failures too, and silently
+ * ignoring a caller's `{ pin }` would defeat the point of pinning.
  */
 export declare function connect(options: ConnectOptions): Promise<MCPConnection>;
 //# sourceMappingURL=mcp-connection.d.ts.map

package/esm/mcp-connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-connection.d.ts","sourceRoot":"","sources":["../src/mcp-connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAWnE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAGpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAOvE,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,GAAG,CAAC;IACT,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,UAAU,CAAC,EAAE;QACX,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,kBAAkB,CAAC;CACpC;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,gBAAgB,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,yBAAyB,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IACrD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAmFD;;;;;;GAMG;AACH,wBAAsB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAkD7E"}
+{"version":3,"file":"mcp-connection.d.ts","sourceRoot":"","sources":["../src/mcp-connection.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,MAAM,EAIP,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAKpD,OAAO,KAAK,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACrF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AA0CrD,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,GAAG,CAAC;IACT,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,UAAU,CAAC,EAAE;QACX,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,mBAAmB,CAAC,EAAE,sBAAsB,CAAC;IAC7C;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,gBAAgB,CAAC;IAC5B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,yBAAyB,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IACrD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAoDD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,IAAI,GAAG,MAAM,CAI5F;AA4ND;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,SAAS,EAAE,KAAK,SAAI,GAAG,OAAO,CAuCzF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAsB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CA0C7E"}