@zackbart/connecta 0.7.1 → 0.7.3

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";
@@ -115,27 +117,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 +162,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.
  */
@@ -372,6 +380,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 +418,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 +452,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 +518,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 +657,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 +777,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;

package/src/credential-health.ts

@@ -17,6 +17,7 @@
 
 import {
   credentialTestRule,
+  STORED_CREDENTIAL_SHAPE_MISMATCH_ERROR,
   storedCredentialShape,
 } from "./credentials.js";
 import type { CredentialVault } from "./credentials.js";
@@ -333,8 +334,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;
 }
@@ -586,12 +587,7 @@ export class CredentialHealthChecker {
         ...(await this.recordOrNothing(connectorId)),
       };
     }
-    const run = this.runCheck(
-      connector,
-      baseUrl,
-      opts.force ?? false,
-      opts.requestScope,
-    );
+    const run = this.runCheck(connector, baseUrl, opts.force ?? false);
     this.inFlight.set(connectorId, run);
     try {
       return await run;
@@ -611,7 +607,6 @@ export class CredentialHealthChecker {
     connector: Connector,
     baseUrl: string,
     force: boolean,
-    requestScope?: object,
   ): Promise<CredentialCheckResult> {
     const connectorId = connector.id;
     const started = Date.now();
@@ -633,7 +628,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 +641,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 +649,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 +668,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 +711,7 @@ export class CredentialHealthChecker {
         });
       }
     } finally {
-      if (ownsScope) await closeConnectorScope(connector, ctx);
+      await closeConnectorScope(connector, ctx);
     }
   }
 
@@ -797,9 +795,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 +811,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);

package/src/executors/quickjs.ts

@@ -40,11 +40,39 @@ const MAX_LOG_ENTRIES = 200;
 // keeps the worst case — 200 maxed-out entries — bounded well under a MiB.
 const MAX_LOG_ENTRY_CHARS = 8_000;
 const MAX_LOG_TOTAL_CHARS = 256_000;
+// Keep one host result below the range where quickjs-emscripten@0.32.0 can
+// nondeterministically fail during runtime disposal under concurrent load.
+// This still lets guest code reduce data more than ten times larger than
+// connecta's final response budget.
+const MAX_HOST_RESULT_BYTES = 256 * 1024;
 
 function msg(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
+function exceedsUtf8ByteLimit(value: string, limit: number): boolean {
+  let bytes = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code <= 0x7f) bytes += 1;
+    else if (code <= 0x7ff) bytes += 2;
+    else if (
+      code >= 0xd800 &&
+      code <= 0xdbff &&
+      index + 1 < value.length &&
+      value.charCodeAt(index + 1) >= 0xdc00 &&
+      value.charCodeAt(index + 1) <= 0xdfff
+    ) {
+      bytes += 4;
+      index += 1;
+    } else {
+      bytes += 3;
+    }
+    if (bytes > limit) return true;
+  }
+  return false;
+}
+
 /** Normalize model output into an async-arrow expression: strip markdown fences, wrap bare bodies. */
 export function normalizeCode(code: string): string {
   let c = code.trim();
@@ -118,6 +146,25 @@ function armWake(bridge: HostBridge): void {
   });
 }
 
+function waitForHostOrDeadline(
+  waitForSettle: Promise<void>,
+  remainingMs: number,
+): Promise<boolean> {
+  return new Promise((resolve) => {
+    let done = false;
+    const timer = setTimeout(() => {
+      done = true;
+      resolve(false);
+    }, remainingMs);
+    void waitForSettle.then(() => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      resolve(true);
+    });
+  });
+}
+
 function installBridge(
   ctx: QuickJSContext,
   providers: ExecutorProvider[],
@@ -176,7 +223,20 @@ function installBridge(
       if (!f) throw new Error(`Unknown function ${ns}.${fn}`);
       const args = JSON.parse(argsJson) as unknown[];
       const value = await f(...args);
-      return JSON.stringify({ ok: true, value });
+      let json: string;
+      try {
+        json = JSON.stringify({ ok: true, value });
+      } catch (err) {
+        throw new Error(
+          `Host result from ${ns}.${fn} could not be serialized: ${msg(err)}`,
+        );
+      }
+      if (exceedsUtf8ByteLimit(json, MAX_HOST_RESULT_BYTES)) {
+        throw new Error(
+          `Host result from ${ns}.${fn} exceeds the ${MAX_HOST_RESULT_BYTES}-byte serialized bridge limit.`,
+        );
+      }
+      return json;
     } catch (err) {
       return JSON.stringify({ ok: false, error: msg(err) });
     }
@@ -326,10 +386,10 @@ export function quickJsExecutor(
           if (remaining <= 0) {
             return { result: undefined, error: timeoutError };
           }
-          const settled = await Promise.race([
-            bridge.waitForSettle.then(() => true),
-            new Promise<boolean>((r) => setTimeout(() => r(false), remaining)),
-          ]);
+          const settled = await waitForHostOrDeadline(
+            bridge.waitForSettle,
+            remaining,
+          );
           if (settled) armWake(bridge);
           else {
             return { result: undefined, error: timeoutError };

package/src/index.ts

@@ -82,7 +82,8 @@ export interface ConnectaDiscoveryConfig {
    * Deadline (ms) for each downstream probe/catalog call fanned out by
    * `list_connectors`, `search_tools`, and `describe_tools`. Defaults to
    * 30_000. A timed-out connector degrades independently; this does not apply
-   * to tool calls or currently abort the underlying fetch.
+   * to tool calls. Catalog walks receive the same cancellation signal, which
+   * aborts an in-flight page where supported and prevents another from starting.
    */
   probeTimeoutMs?: number;
 }