@zackbart/connecta 0.7.1 → 0.7.4

package/src/connectors/remote-mcp.ts

@@ -5,7 +5,9 @@ import type {
   FetchLike,
   Transport,
 } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { ListToolsResultSchema } from "@modelcontextprotocol/sdk/types.js";
 import { CfWorkerJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/cfworker";
+import { z } from "zod";
 import { KvOAuthProvider } from "../auth/downstream-oauth.js";
 import { ConnectorCallError } from "../errors.js";
 import { CONNECTA_VERSION } from "../version.js";
@@ -73,15 +75,14 @@ export interface RemoteMcpOptions {
 
 /**
  * How long a downstream gets to answer the session-termination DELETE before
- * teardown stops waiting. Deliberately a fraction of the core's scope-close
- * budget (`closeConnectorScope`), so the whole teardown still lands inside the
- * window that budget makes safe on an edge runtime: whatever is still in flight
- * when this expires is aborted by the close that immediately follows. What that
- * costs is only the acknowledgement — the DELETE is headers-only and has long
- * since gone out — so a slow provider still usually ends the session; it just
- * does not get to tell us so.
+ * teardown stops waiting. This is a network round-trip budget, deliberately
+ * independent of the core's 100 ms caller-facing scope-close window: an
+ * already-established cross-internet connection avoids setup, but 50 ms is
+ * still too short for an ordinary round trip plus modest provider scheduling.
+ * The bounded tail is deferred on runtimes that can keep it alive after the
+ * response, while callers continue to wait at most 100 ms.
  */
-const TERMINATE_SESSION_BUDGET_MS = 50;
+const TERMINATE_SESSION_BUDGET_MS = 1_000;
 
 /**
  * Ceiling on the tools one catalog refresh will accumulate while walking
@@ -115,27 +116,33 @@ const MAX_TOOLS = 100_000;
  * is a definite loop, two consecutive pages that add no new tools are a server
  * going nowhere, and MAX_TOOLS caps what any of it can accumulate. This exists
  * only so the loop is finite even if a downstream somehow satisfies all three
- * forever, because the caller's probe deadline abandons the *caller*, not the
- * loop. Set high enough that no honest server reaches it.
+ * forever on a path with no discovery deadline. Set high enough that no honest
+ * server reaches it.
  */
 const MAX_TOOL_PAGES = 10_000;
 
 /** One entry of the SDK's `tools/list` result, before it becomes a ToolDef. */
 type ListedTool = Awaited<ReturnType<Client["listTools"]>>["tools"][number];
 
+/**
+ * Compatibility concession for hand-rolled servers that serialize
+ * end-of-pagination as `null`. Only the cursor is widened; every tool and every
+ * other result field still passes through the SDK's pinned schema.
+ */
+const CompatibleListToolsResultSchema = ListToolsResultSchema.extend({
+  nextCursor: z.string().nullable().optional(),
+});
+
 /**
  * Re-prime an SDK client's tool-metadata cache from the *full* walked catalog.
  *
- * `Client.listTools()` ends by calling its private `cacheToolMetadata`, which
- * **clears** the output-schema validators and the task-support sets before
- * repopulating them from the page it just received. Call it once per page —
- * which walking the chain necessarily does — and the request-scoped client is
- * left holding metadata for the *last* page alone. `callTool` then finds no
- * validator for every earlier-page tool and silently skips both the "declared
- * an outputSchema but returned no structuredContent" check and the
- * structured-content validation, and finds no task requirement so a
- * required-task tool is dispatched as a plain `tools/call`. Enforcement would
- * depend on which page a tool happened to land on, which is not enforcement.
+ * The SDK's `Client.listTools()` caches one page at a time and **clears** the
+ * output-schema validators and task-support sets before each replacement.
+ * This walk uses `Client.request()` so it can make the narrow null-cursor
+ * compatibility concession above, then primes the metadata exactly once from
+ * the complete chain. Otherwise `callTool` would find no validator or task
+ * requirement for earlier-page tools and enforcement would depend on where a
+ * tool happened to land, which is not enforcement.
  *
  * So hand the whole aggregated list back deliberately, once, at the end. The
  * SDK types the method `private`, hence the cast; the SDK version is pinned
@@ -154,9 +161,9 @@ function primeToolMetadata(client: Client, tools: ListedTool[]): void {
 }
 
 /**
- * True for a result-parse failure caused by the page's `nextCursor` itself —
- * in practice `nextCursor: null`, a very common JSON idiom for "no more pages"
- * that the MCP schema does not accept (the chain ends on an *absent* cursor).
+ * True for a result-parse failure caused by the page's `nextCursor` itself.
+ * `null` is accepted deliberately; other non-string values remain a named
+ * downstream nonconformance instead of surfacing as a raw validation dump.
  * Duck-typed rather than `instanceof ZodError`: the SDK may parse with its own
  * zod instance, and cross-instance `instanceof` is a coin flip.
  */
@@ -191,24 +198,62 @@ function msg(err: unknown): string {
  * (405 is a legal answer), errors, or never replies all fall through to the
  * close with the session left to age out as it did before.
  */
-async function terminateSession(transport: Transport): Promise<void> {
+async function terminateSession(
+  transport: Transport,
+  logger: Logger,
+  connectorId: string,
+): Promise<void> {
   const terminate = (
     transport as Transport & { terminateSession?: () => Promise<void> }
   ).terminateSession;
   if (typeof terminate !== "function") return;
   // The SDK issues no request at all when no `mcp-session-id` was captured, so
   // a stateless downstream never sees a spurious DELETE.
-  const done = (async () => terminate.call(transport))().catch(() => {
-    // The session is being abandoned either way; a refusal changes nothing.
-    // Caught here rather than at the await below so a late rejection — one
-    // arriving after the budget expired — is still consumed.
-  });
+  const done = Promise.resolve().then(() => terminate.call(transport));
   await new Promise<void>((resolve) => {
-    const timer = setTimeout(resolve, TERMINATE_SESSION_BUDGET_MS);
-    done.then(() => {
-      clearTimeout(timer);
+    let finished = false;
+    const warn = (message: string, error?: unknown) => {
+      try {
+        if (error === undefined) logger.warn(message);
+        else logger.warn(message, error);
+      } catch {
+        // A diagnostic sink cannot make best-effort teardown observable to the
+        // caller in the one way this contract forbids: by replacing its result.
+      }
+    };
+    const timer = setTimeout(() => {
+      if (finished) return;
+      finished = true;
+      warn(
+        `[connecta] connector "${connectorId}" session termination was not ` +
+          `acknowledged within ${TERMINATE_SESSION_BUDGET_MS} ms; the ` +
+          "downstream may still finish the headers-only DELETE, otherwise " +
+          "the session will remain until its provider timeout.",
+      );
       resolve();
-    });
+    }, TERMINATE_SESSION_BUDGET_MS);
+    done.then(
+      () => {
+        if (finished) return;
+        finished = true;
+        clearTimeout(timer);
+        resolve();
+      },
+      (error) => {
+        // The rejection handler stays attached after the timer wins, so an
+        // abort or other late failure is consumed without a duplicate warning.
+        if (finished) return;
+        finished = true;
+        clearTimeout(timer);
+        warn(
+          `[connecta] connector "${connectorId}" session termination was ` +
+            "refused or failed; the downstream session may remain until its " +
+            "provider timeout.",
+          error,
+        );
+        resolve();
+      },
+    );
   });
 }
 
@@ -372,6 +417,9 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
   // transport, response bodies, AbortSignals, or connection promise reachable
   // from the isolate singleton. Those are request-bound in Cloudflare Workers.
   const states = new WeakMap<object, ConnectionState>();
+  // Closing is terminal even after `states.delete`: a late or future lookup
+  // must not recreate an ownerless connection under the ended scope.
+  const closedScopes = new WeakSet<object>();
   const isOauth = opts.auth?.type === "oauth";
   const logger = opts.logger ?? console;
 
@@ -407,22 +455,33 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
     new Error(`Connector "${id}" scope ended during connection.`);
 
   /**
-   * One `tools/list` request. The only thing wrapped here is the diagnosis of a
-   * `nextCursor` the MCP result schema refuses — overwhelmingly `null`, which
-   * plenty of servers use to mean "no more pages" but the spec spells as an
-   * *absent* cursor. The SDK surfaces that as a raw validation dump about a
-   * field the operator never sees; say which server broke which rule instead.
-   * Accepting `null` as end-of-chain outright is issue #99.
+   * One `tools/list` request. The SDK schema is retained wholesale except for
+   * accepting `null` as the common, unambiguous end-of-chain spelling. Other
+   * cursor shapes still get a useful connector-level diagnosis.
    */
-  const listPage = async (client: Client, cursor: string | undefined) => {
+  const listPage = async (
+    client: Client,
+    cursor: string | undefined,
+    ctx: ConnectorContext,
+  ) => {
     try {
-      return await client.listTools(
-        cursor === undefined ? undefined : { cursor },
+      return await client.request(
+        {
+          method: "tools/list",
+          ...(cursor === undefined ? {} : { params: { cursor } }),
+        },
+        CompatibleListToolsResultSchema,
+        ctx.timeoutMs || ctx.signal
+          ? {
+              ...(ctx.timeoutMs ? { timeout: ctx.timeoutMs } : {}),
+              ...(ctx.signal ? { signal: ctx.signal } : {}),
+            }
+          : undefined,
       );
     } catch (err) {
       if (!isCursorShapeError(err)) throw err;
       throw new Error(
-        `Connector "${id}" returned a tools/list page whose nextCursor is neither a string nor absent (a null cursor is the usual culprit) — MCP ends pagination on an absent nextCursor, so this catalog cannot be walked.`,
+        `Connector "${id}" returned a tools/list page whose nextCursor is neither a string, null, nor absent — this catalog cannot be walked.`,
         { cause: err },
       );
     }
@@ -430,6 +489,7 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
 
   const stateFor = (ctx: ConnectorContext): ConnectionState => {
     const scope = ctx.requestScope ?? ctx;
+    if (closedScopes.has(scope)) throw scopeEndedError();
     let state = states.get(scope);
     if (!state) {
       state = {
@@ -495,6 +555,14 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
     ctx: ConnectorContext,
     state: ConnectionState,
   ): Promise<void> => {
+    // A 401 after connect is a verdict for the whole request scope, not merely
+    // for the one call that observed it. Do not let the still-cached client make
+    // a later status or call in the same scope report healthy.
+    if (state.authRequired) {
+      throw authRequiredError(
+        new UnauthorizedError("Downstream authorization is no longer valid."),
+      );
+    }
     // Cross-isolate force re-auth: another isolate bumped the KV generation and
     // wiped credentials. This request's cached client still speaks the old
     // token — drop it so the next connect runs against current state.
@@ -626,64 +694,76 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
       /** Consecutive pages that advertised a successor but added nothing. */
       let barren = 0;
       let complete = false;
-      for (let page = 0; page < MAX_TOOL_PAGES; page++) {
-        // The scope can end between pages (probe timeout, teardown). Stop
-        // rather than keep paging into a transport that is being closed.
-        if (state.closed) throw scopeEndedError();
-        // Page one sends no params at all, so a non-paginated server sees
-        // exactly the request it saw before pagination existed.
-        const res = await listPage(client, cursor);
-        let added = 0;
-        for (const t of res.tools) {
-          // First page wins. An unstable cursor can serve the same tool on two
-          // pages — a failure mode that did not exist while only page one was
-          // read — and a duplicate would inflate `toolCount`, double the tool's
-          // `search_tools` row, and churn the registry's catalog-changed
-          // comparison into a persistence write on every refresh.
-          if (names.has(t.name)) continue;
-          names.add(t.name);
-          listed.push(t);
-          added++;
-        }
-        // Pagination ends when `nextCursor` is ABSENT — not when it is falsy.
-        // An empty string is a legal cursor and means "keep going"; `if
-        // (!next)` here would silently truncate that server's catalog.
-        const next = res.nextCursor;
-        if (typeof next !== "string") {
-          complete = true;
-          break;
-        }
-        // A page that adds nothing and still claims a successor made no
-        // progress. Allow exactly one: the widespread idiom is to advertise a
-        // cursor whenever a page came back full and then serve one empty page
-        // to terminate, and that server is conformant. Two in a row is a
-        // downstream going nowhere, and this kills a "fresh cursor forever, no
-        // tools" adversary in a couple of round trips instead of thousands.
-        if (added === 0 && ++barren > 1) {
-          throw new Error(
-            `Connector "${id}" returned two consecutive tools/list pages that added no tools and still advertised another — the catalog is not advancing.`,
-          );
-        }
-        if (added > 0) barren = 0;
-        // A cursor handed back a second time is not a slow server, it is a
-        // loop. Fail now rather than walking it until a ceiling notices.
-        if (spent.has(next)) {
-          throw new Error(
-            `Connector "${id}" handed back a tools/list cursor it had already issued — the pagination chain loops.`,
-          );
+      try {
+        for (let page = 0; page < MAX_TOOL_PAGES; page++) {
+          // The scope can end between pages (probe timeout, teardown). Stop
+          // rather than keep paging into a transport that is being closed.
+          if (state.closed) throw scopeEndedError();
+          // A discovery deadline uses the same signal for the whole chain.
+          // Check it before issuing each page as well as passing it to the
+          // in-flight SDK request, so expiry never starts one more round trip.
+          if (ctx.signal?.aborted) {
+            throw ctx.signal.reason instanceof Error
+              ? ctx.signal.reason
+              : new Error(`Connector "${id}" catalog deadline expired.`);
+          }
+          // Page one sends no params at all, so a non-paginated server sees
+          // exactly the request it saw before pagination existed.
+          const res = await listPage(client, cursor, ctx);
+          let added = 0;
+          for (const t of res.tools) {
+            // First page wins. An unstable cursor can serve the same tool on
+            // two pages — a duplicate would inflate `toolCount`, double the
+            // `search_tools` row, and churn catalog persistence.
+            if (names.has(t.name)) continue;
+            names.add(t.name);
+            listed.push(t);
+            added++;
+          }
+          // Pagination ends when `nextCursor` is absent or null — never merely
+          // falsy. Empty string is present and means "keep going".
+          const next = res.nextCursor;
+          if (next === undefined || next === null) {
+            complete = true;
+            break;
+          }
+          // A page that adds nothing and still claims a successor made no
+          // progress. Allow exactly one: the widespread idiom is to advertise
+          // a cursor whenever a page came back full and then serve one empty
+          // page to terminate. Two in a row is a downstream going nowhere.
+          if (added === 0 && ++barren > 1) {
+            throw new Error(
+              `Connector "${id}" returned two consecutive tools/list pages that added no tools and still advertised another — the catalog is not advancing.`,
+            );
+          }
+          if (added > 0) barren = 0;
+          // A cursor handed back a second time is a loop, not a slow server.
+          if (spent.has(next)) {
+            throw new Error(
+              `Connector "${id}" handed back a tools/list cursor it had already issued — the pagination chain loops.`,
+            );
+          }
+          // Checked here rather than on arrival: this bounds what a *walk* may
+          // accumulate; a one-page server was always free to send its page.
+          if (listed.length > MAX_TOOLS) {
+            throw new Error(
+              `Connector "${id}" advertised further tools/list pages past ${listed.length} tools, over the ${MAX_TOOLS}-tool ceiling one catalog refresh will collect.`,
+            );
+          }
+          // Opaque by contract: handed straight back, never parsed, rewritten,
+          // or persisted.
+          spent.add(next);
+          cursor = next;
         }
-        // Checked here rather than on arrival: this bounds what a *walk* may
-        // accumulate, and a server that answers in one page was always free to
-        // send whatever it sends.
-        if (listed.length > MAX_TOOLS) {
-          throw new Error(
-            `Connector "${id}" advertised further tools/list pages past ${listed.length} tools, over the ${MAX_TOOLS}-tool ceiling one catalog refresh will collect.`,
-          );
+      } catch (err) {
+        // A grant can be revoked after connect and after any earlier page.
+        // Classify that exactly like connect-time and call-time authorization
+        // failures, and latch it for the rest of this request scope.
+        if (err instanceof UnauthorizedError) {
+          state.authRequired = true;
+          throw authRequiredError(err);
         }
-        // Opaque by contract: handed straight back, never parsed, rewritten,
-        // or persisted.
-        spent.add(next);
-        cursor = next;
+        throw err;
       }
       // Fail the refresh outright. Returning what we have would publish a
       // partial catalog that looks complete; throwing lets the registry keep
@@ -734,11 +814,13 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
 
     async closeScope(ctx) {
       const scope = ctx.requestScope ?? ctx;
+      // Tombstone before any lookup or await. This also makes close-before-use
+      // terminal rather than allowing the scope to spring into existence later.
+      closedScopes.add(scope);
       const state = states.get(scope);
       if (!state) return;
 
-      // Delete before awaiting: a duplicate teardown is a no-op, and no later
-      // lookup can reuse the state while its client is closing.
+      // Delete before awaiting: a duplicate teardown is a no-op.
       states.delete(scope);
       state.closed = true;
       const client = state.client;
@@ -752,7 +834,7 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
       // Ask the downstream to drop its session first — closing only aborts our
       // side, and the DELETE that frees the server's rides on the very
       // AbortSignal the close is about to trip.
-      if (transport) await terminateSession(transport);
+      if (transport) await terminateSession(transport, ctx.logger, id);
 
       // Client.close() owns its connected transport. During an unfinished or
       // failed connect there is no cached client yet, so close the transport

package/src/credential-health.ts

@@ -17,10 +17,14 @@
 
 import {
   credentialTestRule,
+  STORED_CREDENTIAL_SHAPE_MISMATCH_ERROR,
   storedCredentialShape,
 } from "./credentials.js";
 import type { CredentialVault } from "./credentials.js";
-import { closeConnectorScope } from "./connector-scope.js";
+import {
+  closeConnectorScope,
+  type DeferredWork,
+} from "./connector-scope.js";
 import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs, withTimeout } from "./timeout.js";
 import type {
   Connector,
@@ -333,8 +337,8 @@ export interface CredentialCheckOptions {
   /** Restrict the sweep to these connector ids. Default: every connector. */
   ids?: string[];
   /**
-   * Internal scope identity supplied by an existing owner. When omitted, the
-   * check creates and ends its own probe scope.
+   * @deprecated Ignored. Credential checks always create and close their own
+   * probe scope; no core path supplies an existing request scope.
    */
   requestScope?: object;
 }
@@ -535,6 +539,7 @@ export class CredentialHealthChecker {
   async check(
     baseUrl: string,
     opts: CredentialCheckOptions = {},
+    defer?: DeferredWork,
   ): Promise<CredentialCheckResult[]> {
     // An id naming no connector is reported, not dropped: a typo in a scheduled
     // check would otherwise return an empty list that looks exactly like a
@@ -545,7 +550,7 @@ export class CredentialHealthChecker {
     return mapWithConcurrency(targets, this.concurrency, (target) =>
       typeof target === "string"
         ? Promise.resolve({ connectorId: target, skipped: "not_found" as const })
-        : this.checkOne(target, baseUrl, opts),
+        : this.checkOne(target, baseUrl, opts, defer),
     );
   }
 
@@ -555,13 +560,16 @@ export class CredentialHealthChecker {
    * gate is armed BEFORE the sweep starts, so a burst of concurrent requests
    * produces one sweep.
    */
-  sweepIfDue(baseUrl: string): Promise<CredentialCheckResult[]> | undefined {
+  sweepIfDue(
+    baseUrl: string,
+    defer?: DeferredWork,
+  ): Promise<CredentialCheckResult[]> | undefined {
     if (!this.onRequest || this.sweeping) return undefined;
     const now = Date.now();
     if (now < this.nextSweepAt) return undefined;
     if (!this.hasCheckableConnectors()) return undefined;
     this.nextSweepAt = now + this.intervalMs;
-    const sweep = this.check(baseUrl).finally(() => {
+    const sweep = this.check(baseUrl, {}, defer).finally(() => {
       this.sweeping = undefined;
     });
     this.sweeping = sweep;
@@ -572,6 +580,7 @@ export class CredentialHealthChecker {
     connector: Connector,
     baseUrl: string,
     opts: CredentialCheckOptions,
+    defer?: DeferredWork,
   ): Promise<CredentialCheckResult> {
     const connectorId = connector.id;
     if (!isCheckableConnector(connector)) {
@@ -590,7 +599,7 @@ export class CredentialHealthChecker {
       connector,
       baseUrl,
       opts.force ?? false,
-      opts.requestScope,
+      defer,
     );
     this.inFlight.set(connectorId, run);
     try {
@@ -611,7 +620,7 @@ export class CredentialHealthChecker {
     connector: Connector,
     baseUrl: string,
     force: boolean,
-    requestScope?: object,
+    defer?: DeferredWork,
   ): Promise<CredentialCheckResult> {
     const connectorId = connector.id;
     const started = Date.now();
@@ -633,7 +642,7 @@ export class CredentialHealthChecker {
       }
       const shape = storedCredentialShape(connector.credential, values);
       if (shape.state === "mismatch") {
-        // Drift is a persistent operator-error state, not an event: left
+        // Drift is a persistent operator-reconfiguration state, not an event:
         // outside the freshness gate it would spend a write on every sweep in
         // every isolate, forever, against exactly the deployments this feature
         // is meant to help (and on Cloudflare KV those writes are metered).
@@ -646,7 +655,7 @@ export class CredentialHealthChecker {
           const current = await this.store.get(connectorId);
           if (
             current &&
-            current.state === "error" &&
+            current.state === "auth_required" &&
             current.message === shape.message &&
             Date.now() - Date.parse(current.checkedAt) < this.intervalMs
           ) {
@@ -654,7 +663,9 @@ export class CredentialHealthChecker {
           }
         }
         return this.settle(connectorId, started, generation, {
-          state: "error",
+          // Unlike a failed check, this is a completed static classification:
+          // the current declaration cannot consume what the vault holds.
+          state: "auth_required",
           checkedAt: new Date().toISOString(),
           message: shape.message,
         });
@@ -671,8 +682,9 @@ export class CredentialHealthChecker {
         return { connectorId, skipped: "fresh", record: current };
       }
     }
-    const ownsScope = requestScope === undefined;
-    const scope = requestScope ?? {};
+    // Credential checks are always probe owners. No caller may lend them an
+    // ordinary request scope and thereby suppress the teardown below.
+    const scope = {};
     const ctx = this.deps.contextFor(connectorId, baseUrl, scope);
     try {
       if (credentialReadError) {
@@ -713,7 +725,7 @@ export class CredentialHealthChecker {
         });
       }
     } finally {
-      if (ownsScope) await closeConnectorScope(connector, ctx);
+      await closeConnectorScope(connector, ctx, defer);
     }
   }
 
@@ -797,9 +809,12 @@ export class CredentialHealthChecker {
  *    blip. Error verdicts stay visible in `credentialCheck` (an operator wants
  *    to know checks are failing) but the status keeps coming from observed real
  *    calls, which is evidence.
- * 2. **A successful real call retires the verdict.** Traffic beats a background
- *    probe, so a `lastSuccessAt` at or after `checkedAt` means the credential
- *    demonstrably works whatever the check concluded. The next check re-decides.
+ * 2. **A successful real call retires the verdict, except static shape drift.**
+ *    Traffic beats a background probe, so a `lastSuccessAt` at or after
+ *    `checkedAt` normally means the credential demonstrably works. Stored-shape
+ *    drift is different: a credential-independent tool can succeed without
+ *    making a missing declared field appear, so only replacement/removal clears
+ *    that verdict.
  *
  * `auth_required` deliberately outranks an observed real-call *failure*: both
  * say something is wrong, and only one of them carries the URL that fixes it.
@@ -810,6 +825,7 @@ export function credentialVerdictApplies(
   lastSuccessAt: string | undefined,
 ): boolean {
   if (!record || record.state !== "auth_required") return false;
+  if (record.message === STORED_CREDENTIAL_SHAPE_MISMATCH_ERROR) return true;
   if (!lastSuccessAt) return true;
   const success = Date.parse(lastSuccessAt);
   return Number.isNaN(success) || success < Date.parse(record.checkedAt);