@zackbart/connecta 0.7.5 → 0.7.7

package/src/connectors/remote-mcp.ts

@@ -393,7 +393,7 @@ interface ConnectionState {
   connecting: Promise<void> | null;
   authRequired: boolean;
   provider: KvOAuthProvider | null;
-  connectedGeneration: number | null;
+  connectedGeneration: string | null;
   /**
    * One-way latch: set by closeScope and never cleared, so neither a late
    * connect nor a `reset()` can cache a client into a scope that is already
@@ -451,6 +451,16 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
       { cause },
     );
 
+  class OperatorDisconnectedError extends ConnectorCallError {
+    constructor() {
+      super(
+        "auth_required",
+        `Connector "${id}" was disconnected by an operator — explicitly start authorization to reconnect it.`,
+      );
+    }
+  }
+  const operatorDisconnectedError = () => new OperatorDisconnectedError();
+
   const scopeEndedError = () =>
     new Error(`Connector "${id}" scope ended during connection.`);
 
@@ -518,16 +528,23 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
     return state.provider;
   };
 
+  const newProvider = (ctx: ConnectorContext): KvOAuthProvider =>
+    new KvOAuthProvider(
+      id,
+      ctx.storage,
+      `${ctx.baseUrl}/oauth/callback/${id}`,
+    );
+
   const buildTransport = (
     ctx: ConnectorContext,
-    state: ConnectionState,
+    provider: KvOAuthProvider | null,
   ): Transport => {
     if (opts._transportFactory) return opts._transportFactory(ctx);
     const url = new URL(opts.url);
     const guardedFetch = redirectSafeFetch(id, opts.redirects);
     if (opts.auth?.type === "oauth") {
       return new StreamableHTTPClientTransport(url, {
-        authProvider: getProvider(ctx, state),
+        authProvider: provider ?? newProvider(ctx),
         fetch: guardedFetch,
       });
     }
@@ -547,6 +564,7 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
     state.transport = null;
     state.connecting = null;
     state.authRequired = false;
+    state.provider = null;
     state.connectedGeneration = null;
     // `closed` is deliberately not cleared — see ConnectionState.
   };
@@ -563,97 +581,160 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
         new UnauthorizedError("Downstream authorization is no longer valid."),
       );
     }
+    // Read the OAuth epoch before trusting either a cached client or starting a
+    // transport. A disconnected epoch is a durable operator instruction, not
+    // merely the absence of credentials: passive status/tool probes must not
+    // turn it back into a pending consent flow.
+    let oauthGeneration: string | undefined;
+    if (isOauth && (state.client || state.connecting)) {
+      const provider = getProvider(ctx, state);
+      oauthGeneration = await provider.generation();
+      if (provider.isOperatorDisconnectedGeneration(oauthGeneration)) {
+        const connecting = state.connecting;
+        const client = state.client;
+        const transport = state.transport;
+        reset(state);
+        void connecting?.catch(() => {});
+        try {
+          if (client) await client.close();
+          else await transport?.close();
+        } catch {
+          // The disconnected epoch is authoritative even if local close fails.
+        }
+        throw operatorDisconnectedError();
+      }
+    }
     // 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.
-    if (state.client && isOauth && state.connectedGeneration !== null) {
-      const generation = await getProvider(ctx, state).generation();
+    if (state.client && oauthGeneration !== undefined && state.connectedGeneration !== null) {
       if (state.closed) throw scopeEndedError();
-      if (generation !== state.connectedGeneration) {
+      if (oauthGeneration !== state.connectedGeneration) {
         reset(state);
       }
     }
     if (state.closed) throw scopeEndedError();
     if (state.client) return;
-    state.connecting ??= (async () => {
-      const provider = isOauth ? getProvider(ctx, state) : null;
-      const genAtStart = provider ? await provider.generation() : 0;
-      if (state.closed) throw scopeEndedError();
-      // Stamp the provider so any saveTokens/saveClientInformation the SDK fires
-      // during this connect (code exchange, DCR) — or during a later refresh on
-      // the resulting client — is dropped if a concurrent force bumps the
-      // generation past this point, instead of re-persisting wiped credentials.
-      provider?.captureGeneration(genAtStart);
-      // The SDK defaults to AJV, which compiles every advertised outputSchema
-      // with `new Function`. Cloudflare Workers prohibit dynamic code
-      // generation, so a remote such as Stripe fails during tools/list unless
-      // the SDK's edge-safe validator is selected explicitly.
-      const c = new Client(
-        { name: "connecta", version: CONNECTA_VERSION },
-        { jsonSchemaValidator: new CfWorkerJsonSchemaValidator() },
-      );
-      const t = buildTransport(ctx, state);
-      state.transport = t;
-      try {
-        await c.connect(t);
-        // A probe deadline can end its scope while connect is still in flight.
-        // The transport is closed immediately by closeScope; if connect wins
-        // that race anyway, close the resulting client rather than resurrecting
-        // a session in the detached state object.
-        if (state.closed) {
+    if (!state.connecting) {
+      let attempt!: Promise<void>;
+      attempt = (async () => {
+        const ownsAttempt = () =>
+          state.connecting === attempt && !state.closed;
+        const abandon = async (owner: Client | Transport) => {
           try {
-            await c.close();
+            await owner.close();
           } catch {
-            // The scope has already been discarded either way.
+            // The attempt is detached either way.
           }
           throw scopeEndedError();
+        };
+        // Let the assignment immediately below this async IIFE publish
+        // `state.connecting = attempt` before ownership is checked. OAuth's
+        // generation read naturally yields; unauthenticated transports do not.
+        await Promise.resolve();
+        // A provider belongs to exactly one connect attempt. A force reset can
+        // abandon that attempt while its transport still holds the provider;
+        // the replacement must never mutate the abandoned provider's epoch.
+        const provider = isOauth ? newProvider(ctx) : null;
+        const genAtStart = provider ? await provider.generation() : "";
+        if (!ownsAttempt()) throw scopeEndedError();
+        if (provider?.isOperatorDisconnectedGeneration(genAtStart)) {
+          throw operatorDisconnectedError();
         }
-        // A force re-auth that landed WHILE we were connecting wiped the creds
-        // this client just bound to. Discard it rather than cache a connection
-        // that resurrects the wiped-and-reauthorized connector from a stale
-        // isolate. Surfaces as auth_required — the connector genuinely needs
-        // re-consent now.
-        if (provider) {
-          const generation = await provider.generation();
-          // closeScope can land while the generation read is pending, after
-          // connect succeeded but before this client is cached. Discard the
-          // client on that side of the await too.
-          if (state.closed) {
-            try {
-              await c.close();
-            } catch {
-              // The scope has already been discarded either way.
+        provider?.captureGeneration(genAtStart);
+        // The SDK defaults to AJV, which compiles every advertised outputSchema
+        // with `new Function`. Cloudflare Workers prohibit dynamic code
+        // generation, so a remote such as Stripe fails during tools/list unless
+        // the SDK's edge-safe validator is selected explicitly.
+        const c = new Client(
+          { name: "connecta", version: CONNECTA_VERSION },
+          { jsonSchemaValidator: new CfWorkerJsonSchemaValidator() },
+        );
+        const t = buildTransport(ctx, provider);
+        if (!ownsAttempt()) await abandon(t);
+        state.transport = t;
+        try {
+          await c.connect(t);
+          // A probe deadline can end its scope while connect is still in flight.
+          // The transport is closed immediately by closeScope; if connect wins
+          // that race anyway, close the resulting client rather than
+          // resurrecting a session in the detached state object.
+          if (!ownsAttempt()) await abandon(c);
+          // A force re-auth that landed WHILE we were connecting wiped the
+          // credentials this client just bound to. Discard it rather than
+          // cache a stale-isolate connection.
+          if (provider) {
+            const generation = await provider.generation();
+            // closeScope can land while the generation read is pending, after
+            // connect succeeded but before this client is cached. Discard the
+            // client on that side of the await too.
+            if (!ownsAttempt()) await abandon(c);
+            if (generation !== genAtStart) {
+              try {
+                await c.close();
+              } catch {
+                // discarding either way
+              }
+              throw new UnauthorizedError(
+                "Connector was re-authorized during connect; reconnect required.",
+              );
             }
-            throw scopeEndedError();
           }
-          if (generation !== genAtStart) {
-            try {
-              await c.close();
-            } catch {
-              // discarding either way
-            }
-            throw new UnauthorizedError(
-              "Connector was re-authorized during connect; reconnect required.",
-            );
+          if (!ownsAttempt()) await abandon(c);
+          state.client = c;
+          state.connectedGeneration = genAtStart;
+          state.authRequired = false;
+        } catch (err) {
+          // Only a real 401/UnauthorizedError means auth is the problem — a
+          // network error on an oauth connector must surface as "error", not
+          // "auth_required".
+          if (err instanceof UnauthorizedError && ownsAttempt()) {
+            state.authRequired = true;
           }
+          if (err instanceof UnauthorizedError) {
+            throw authRequiredError(err);
+          }
+          throw err;
+        } finally {
+          // Force reset may have abandoned this attempt and installed a new one
+          // in the same request scope. An old completion must not erase the new
+          // promise and allow a third concurrent connect.
+          if (state.connecting === attempt) state.connecting = null;
         }
-        state.client = c;
-        state.connectedGeneration = genAtStart;
-        state.authRequired = false;
-      } catch (err) {
-        // Only a real 401/UnauthorizedError means auth is the problem — a
-        // network error on an oauth connector must surface as "error", not
-        // "auth_required".
-        if (err instanceof UnauthorizedError) {
-          state.authRequired = true;
-          throw authRequiredError(err);
+      })();
+      state.connecting = attempt;
+    }
+    return state.connecting;
+  };
+
+  const disconnectAuthorization = async (
+    ctx: ConnectorContext,
+    state: ConnectionState,
+    operatorDisconnected = false,
+  ): Promise<void> => {
+    const provider = getProvider(ctx, state);
+    // Publish the replacement epoch before waiting on or closing any
+    // request-local transport. A hung connect therefore cannot delay the
+    // fence, and every late OAuth write stays in the older namespace.
+    const connecting = state.connecting;
+    try {
+      await provider.resetAuthorization(operatorDisconnected);
+    } finally {
+      // Consume the abandoned connect and close whichever half of the
+      // client/transport exists. Reset is unconditional because KV may already
+      // be fenced behind a newer epoch after a cleanup error.
+      void connecting?.catch(() => {});
+      try {
+        if (state.client) {
+          await state.client.close();
+        } else {
+          await state.transport?.close();
         }
-        throw err;
-      } finally {
-        state.connecting = null;
+      } catch {
+        // best-effort; the state is discarded either way
       }
-    })();
-    return state.connecting;
+      reset(state);
+    }
   };
 
   const connector: Connector = {
@@ -760,7 +841,7 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
         // 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;
+          if (state.client === client) state.authRequired = true;
           throw authRequiredError(err);
         }
         throw err;
@@ -788,8 +869,9 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
     async callTool(name, args, ctx) {
       const state = stateFor(ctx);
       await ensureConnected(ctx, state);
+      const client = state.client!;
       try {
-        return await state.client!.callTool(
+        return await client.callTool(
           {
             name,
             arguments: (args ?? {}) as Record<string, unknown>,
@@ -805,7 +887,7 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
       } catch (err) {
         // A grant revoked after connect surfaces here, not in ensureConnected.
         if (err instanceof UnauthorizedError) {
-          state.authRequired = true;
+          if (state.client === client) state.authRequired = true;
           throw authRequiredError(err);
         }
         throw err;
@@ -860,6 +942,9 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
             message: "Authorization required — open the URL to connect.",
           };
         }
+        if (err instanceof OperatorDisconnectedError) {
+          return { state: "auth_required", message: err.message };
+        }
         return { state: "error", message: msg(err) };
       }
     },
@@ -867,12 +952,11 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
     async finishAuth(code, ctx) {
       const state = stateFor(ctx);
       const provider = getProvider(ctx, state);
-      // The provider here may carry no captured generation, so its token saves
-      // fail open. That is safe only because generation advances solely via the
-      // force path, which always wipes oauth:state — so verifyState rejects any
-      // pre-force callback before this runs. Keep those two facts coupled.
+      // verifyState ran on this request-scoped provider first and captured the
+      // pending flow's generation. If force reset races the exchange, any late
+      // token write remains tagged with that older generation and is unreadable.
       const t = (state.transport ??
-        buildTransport(ctx, state)) as StreamableHTTPClientTransport;
+        buildTransport(ctx, provider)) as StreamableHTTPClientTransport;
       await t.finishAuth(code);
       await provider.clearPending();
       // Reset so the next use reconnects with the freshly stored tokens.
@@ -895,31 +979,15 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
       return getProvider(ctx, state).verifyState(oauthState);
     };
 
+    connector.disconnectAuth = async (ctx) => {
+      await disconnectAuthorization(ctx, stateFor(ctx), true);
+    };
+
     connector.startAuth = async (ctx, startOpts) => {
       const state = stateFor(ctx);
       const p = getProvider(ctx, state);
-      if (startOpts?.force) {
-        // Wipe stored credentials and drop the live connection so the next
-        // connect attempt runs the flow from scratch (DCR + PKCE + consent).
-        // Fence the in-flight connect first: a late-completing attempt must not
-        // resurrect the credentials we're about to wipe, nor leave `client` set
-        // (which would make ensureConnected below report already-authorized and
-        // silently defeat force).
-        await state.connecting?.catch(() => {});
-        try {
-          await state.client?.close();
-        } catch {
-          // best-effort; the connection is being discarded either way
-        }
-        // Bump the shared generation FIRST so any other isolate — one mid-
-        // connect, or on its next tool call — sees the advance and drops its
-        // client instead of keeping the token we're about to revoke.
-        await p.bumpGeneration();
-        // Wipe KV before dropping in-memory state so nothing racing back in can
-        // write tokens over a half-cleared slot.
-        await p.invalidateCredentials("all");
-        await p.clearPending();
-        reset(state);
+      if (startOpts?.force || (await p.operatorDisconnected())) {
+        await disconnectAuthorization(ctx, state);
       } else {
         // A consent URL already outstanding? Re-issue it rather than re-running
         // the SDK flow, which would overwrite the PKCE verifier and invalidate

package/src/execute.ts

@@ -513,6 +513,11 @@ export function createExecuteTool(
       // catalogs, request scopes, or one-closure-per-tool provider arrays.
       if (isAdmittingExecutor(executor)) {
         lease = await executor.acquire({ signal: controller.signal });
+        if ((lease.waitMs ?? 0) > 0) {
+          logger.debug("[connecta] execute_code admitted after queue wait", {
+            waitMs: lease.waitMs,
+          });
+        }
       }
       const providers = await buildSandboxProviders(
         registry,
@@ -532,6 +537,12 @@ export function createExecuteTool(
         : await executor.execute(code, providers);
     } catch (err) {
       if (err instanceof ExecutorAdmissionError) {
+        if (err.code === "executor_overloaded") {
+          logger.warn("[connecta] execute_code admission rejected", {
+            code: err.code,
+            retryAfterMs: err.retryAfterMs,
+          });
+        }
         const result = jsonResult({
           error: {
             code: err.code,

package/src/executor-admission.ts

@@ -1,6 +1,8 @@
 import type {
   AdmittingExecutor,
+  AdmissionSnapshot,
   Executor,
+  ExecutorLease,
 } from "./types.js";
 
 export type ExecutorAdmissionErrorCode =
@@ -35,10 +37,13 @@ export class ExecutorAdmissionError extends Error {
 }
 
 export interface AdmissionLease {
+  /** Time spent waiting behind active work. Zero for immediate admission. */
+  readonly waitMs: number;
   release(): void;
 }
 
 interface Waiter {
+  queuedAt: number;
   resolve: (lease: AdmissionLease) => void;
   reject: (error: ExecutorAdmissionError) => void;
   signal?: AbortSignal;
@@ -82,6 +87,14 @@ export class AdmissionController {
   private active = 0;
   private closed = false;
   private readonly waiters: Waiter[] = [];
+  private admittedTotal = 0;
+  private queuedTotal = 0;
+  private rejectedTotal = 0;
+  private cancelledTotal = 0;
+  private closedTotal = 0;
+  private queueWaitCount = 0;
+  private queueWaitTotalMs = 0;
+  private queueWaitMaxMs = 0;
 
   constructor(options: AdmissionControllerOptions) {
     this.concurrency = positiveWhole(options.concurrency, "concurrency");
@@ -107,8 +120,33 @@ export class AdmissionController {
     return this.waiters.length;
   }
 
+  snapshot(): AdmissionSnapshot {
+    return {
+      concurrency: this.concurrency,
+      maxQueueSize: this.maxQueueSize,
+      queueTimeoutMs: this.queueTimeoutMs,
+      retryAfterMs: this.retryAfterMs,
+      active: this.active,
+      queued: this.waiters.length,
+      closed: this.closed,
+      totals: {
+        admitted: this.admittedTotal,
+        queued: this.queuedTotal,
+        rejected: this.rejectedTotal,
+        cancelled: this.cancelledTotal,
+        closed: this.closedTotal,
+      },
+      queueWaitMs: {
+        count: this.queueWaitCount,
+        total: this.queueWaitTotalMs,
+        max: this.queueWaitMaxMs,
+      },
+    };
+  }
+
   acquire(options: { signal?: AbortSignal } = {}): Promise<AdmissionLease> {
     if (this.closed) {
+      this.closedTotal++;
       return Promise.reject(
         new ExecutorAdmissionError(
           "executor_closed",
@@ -117,6 +155,7 @@ export class AdmissionController {
       );
     }
     if (options.signal?.aborted) {
+      this.cancelledTotal++;
       return Promise.reject(
         new ExecutorAdmissionError(
           "executor_cancelled",
@@ -126,14 +165,17 @@ export class AdmissionController {
     }
     if (this.active < this.concurrency) {
       this.active++;
-      return Promise.resolve(this.makeLease());
+      this.admittedTotal++;
+      return Promise.resolve(this.makeLease(0));
     }
     if (this.waiters.length >= this.maxQueueSize) {
+      this.rejectedTotal++;
       return Promise.reject(this.overloaded("Executor queue is full."));
     }
 
     return new Promise<AdmissionLease>((resolve, reject) => {
       const waiter: Waiter = {
+        queuedAt: Date.now(),
         resolve,
         reject,
         ...(options.signal ? { signal: options.signal } : {}),
@@ -141,6 +183,7 @@ export class AdmissionController {
       waiter.onAbort = () => {
         if (!this.remove(waiter)) return;
         this.cleanup(waiter);
+        this.cancelledTotal++;
         reject(
           new ExecutorAdmissionError(
             "executor_cancelled",
@@ -152,6 +195,7 @@ export class AdmissionController {
       waiter.timer = setTimeout(() => {
         if (!this.remove(waiter)) return;
         this.cleanup(waiter);
+        this.rejectedTotal++;
         reject(
           this.overloaded(
             `Executor admission timed out after ${this.queueTimeoutMs}ms.`,
@@ -159,6 +203,7 @@ export class AdmissionController {
         );
       }, this.queueTimeoutMs);
       this.waiters.push(waiter);
+      this.queuedTotal++;
     });
   }
 
@@ -167,6 +212,7 @@ export class AdmissionController {
     this.closed = true;
     for (const waiter of this.waiters.splice(0)) {
       this.cleanup(waiter);
+      this.closedTotal++;
       waiter.reject(
         new ExecutorAdmissionError(
           "executor_closed",
@@ -182,9 +228,10 @@ export class AdmissionController {
     });
   }
 
-  private makeLease(): AdmissionLease {
+  private makeLease(waitMs: number): AdmissionLease {
     let released = false;
     return {
+      waitMs,
       release: () => {
         if (released) return;
         released = true;
@@ -199,8 +246,13 @@ export class AdmissionController {
     const waiter = this.waiters.shift();
     if (!waiter) return;
     this.cleanup(waiter);
+    const waitMs = Math.max(0, Date.now() - waiter.queuedAt);
+    this.admittedTotal++;
+    this.queueWaitCount++;
+    this.queueWaitTotalMs += waitMs;
+    this.queueWaitMaxMs = Math.max(this.queueWaitMaxMs, waitMs);
     this.active++;
-    waiter.resolve(this.makeLease());
+    waiter.resolve(this.makeLease(waitMs));
   }
 
   private remove(waiter: Waiter): boolean {
@@ -227,3 +279,38 @@ export function isAdmittingExecutor(
     typeof (executor as { acquire?: unknown }).acquire === "function"
   );
 }
+
+/**
+ * Give a structurally-compatible but otherwise unbounded executor the same
+ * admission contract as the built-in Node executor. The wrapper owns only the
+ * queue; closing the underlying runtime remains the Connecta lifecycle's job.
+ */
+export function withExecutorAdmission(
+  executor: Executor,
+  admission: AdmissionController,
+): AdmittingExecutor {
+  return {
+    async acquire(options = {}): Promise<ExecutorLease> {
+      const token = await admission.acquire(options);
+      let released = false;
+      return {
+        waitMs: token.waitMs,
+        execute: (code, providers) => executor.execute(code, providers),
+        release: () => {
+          if (released) return;
+          released = true;
+          token.release();
+        },
+      };
+    },
+    async execute(code, providers) {
+      const lease = await this.acquire();
+      try {
+        return await lease.execute(code, providers);
+      } finally {
+        lease.release();
+      }
+    },
+    admissionSnapshot: () => admission.snapshot(),
+  };
+}

package/src/executors/quickjs-protocol.ts

@@ -1,11 +1,14 @@
 import type { ExecuteResult } from "../types.js";
 import type { QuickJsRuntimeOptions } from "./quickjs-runtime.js";
 
-// The guest result is shaped to 24k characters before transport and QuickJS
-// capture already bounds logs to 256k characters. Every complete message is
-// measured against this ceiling before process.send; one MiB leaves room for
-// multibyte log text and envelope escaping while remaining a hard IPC bound.
+// An execution result is serialized once into payloadJson and again as that
+// string is embedded in ChildToParentMessage. Captured logs therefore get a
+// separate 512 KiB budget measured after both JSON encodings. The final result
+// is shaped to 24k characters; even if every character takes its worst-case
+// seven transport bytes, that leaves ample structural overhead below this hard
+// process.send ceiling.
 export const MAX_QUICKJS_IPC_BYTES = 1024 * 1024;
+export const MAX_QUICKJS_LOG_TRANSPORT_BYTES = 512 * 1024;
 /** Preserve #84's stopgap before a host value enters the child/WASM process. */
 export const MAX_QUICKJS_HOST_RPC_BYTES = 256 * 1024;