@zackbart/connecta 0.7.6 → 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/index.ts

@@ -719,8 +719,11 @@ export type {
   ActivityCallSource,
   ActivityOutcome,
   ActivityPage,
+  ActivityReadActor,
+  ActivityReadEvent,
   ActivityReader,
   ActivityReadGate,
+  ActivityReadPage,
   ActivitySink,
   ActivityStore,
   ToolCallActivityEvent,

package/src/registry.ts

@@ -235,6 +235,10 @@ export class Registry implements RegistryView {
   private readonly connectors = new Map<string, Connector>();
   private readonly cache = new Map<string, CacheEntry>();
   private readonly invalidated = new Set<string>();
+  /** Per-connector epoch preventing a pre-invalidation refresh from publishing. */
+  private readonly catalogGenerations = new Map<string, number>();
+  /** Serialize persisted catalog set/delete operations within this isolate. */
+  private readonly catalogMutations = new Map<string, Promise<void>>();
   /** Deployment-wide observations — every call, whatever view made it. */
   private readonly health = new HealthLog();
   private readonly ttlMs: number;
@@ -459,6 +463,36 @@ export class Registry implements RegistryView {
     });
   }
 
+  private catalogGeneration(id: string): number {
+    return this.catalogGenerations.get(id) ?? 0;
+  }
+
+  private advanceCatalogGeneration(id: string): void {
+    this.catalogGenerations.set(id, this.catalogGeneration(id) + 1);
+  }
+
+  /**
+   * Keep this isolate's writes and invalidations ordered. Without the queue, an
+   * old refresh can finish its storage.set after a credential change deletes
+   * the catalog and resurrect the pre-change listing.
+   */
+  private enqueueCatalogMutation(
+    id: string,
+    operation: () => Promise<void>,
+  ): Promise<void> {
+    const previous = this.catalogMutations.get(id) ?? Promise.resolve();
+    const next = previous.catch(() => {}).then(operation);
+    this.catalogMutations.set(id, next);
+    void next
+      .finally(() => {
+        if (this.catalogMutations.get(id) === next) {
+          this.catalogMutations.delete(id);
+        }
+      })
+      .catch(() => {});
+    return next;
+  }
+
   /** Force a live listTools refresh and replace both catalog cache layers. */
   async refreshTools(
     id: string,
@@ -468,11 +502,16 @@ export class Registry implements RegistryView {
   ): Promise<ToolDef[]> {
     const connector = this.connectors.get(id);
     if (!connector) throw new Error(`Unknown connector "${id}"`);
+    const generation = this.catalogGeneration(id);
     const tools = connector.staticTools
       ? connector.staticTools
       : await connector.listTools(
           this.contextFor(id, baseUrl, requestScope, callOptions),
         );
+    // The caller that began this refresh may still use its result, but a
+    // credential/OAuth change that landed while listTools was in flight means
+    // the listing must not enter either shared cache layer.
+    if (generation !== this.catalogGeneration(id)) return tools;
     const now = Date.now();
     const previous = this.cache.get(id);
     const catalogChanged =
@@ -487,13 +526,16 @@ export class Registry implements RegistryView {
     });
     this.invalidated.delete(id);
     if (shouldPersist) {
-      try {
-        await this.storeCatalog(id, tools);
-      } catch (err) {
-        this.opts.logger.warn(
-          `[connecta] connector "${id}" catalog persistence failed: ${msg(err)}`,
-        );
-      }
+      await this.enqueueCatalogMutation(id, async () => {
+        if (generation !== this.catalogGeneration(id)) return;
+        try {
+          await this.storeCatalog(id, tools);
+        } catch (err) {
+          this.opts.logger.warn(
+            `[connecta] connector "${id}" catalog persistence failed: ${msg(err)}`,
+          );
+        }
+      });
     }
     return tools;
   }
@@ -510,11 +552,13 @@ export class Registry implements RegistryView {
     if (connector.staticTools) return connector.staticTools;
 
     const now = Date.now();
+    const requestGeneration = this.catalogGeneration(id);
     const hit = this.cache.get(id);
     if (hit && hit.exp > now) return hit.tools;
 
     let stale = hit && hit.staleUntil > now ? hit.tools : undefined;
     if (this.persistToolCatalog && !this.invalidated.has(id)) {
+      const generation = this.catalogGeneration(id);
       let persisted: PersistedCatalog | null = null;
       try {
         persisted = this.validCatalog(
@@ -525,6 +569,10 @@ export class Registry implements RegistryView {
           `[connecta] connector "${id}" catalog read failed: ${msg(err)}`,
         );
       }
+      if (generation !== this.catalogGeneration(id)) {
+        persisted = null;
+        stale = undefined;
+      }
       if (persisted && persisted.staleUntil > now) {
         this.cache.set(id, {
           tools: persisted.tools,
@@ -539,7 +587,11 @@ export class Registry implements RegistryView {
     try {
       return await this.refreshTools(id, baseUrl, requestScope, callOptions);
     } catch (err) {
-      if (stale) {
+      if (
+        stale &&
+        requestGeneration === this.catalogGeneration(id) &&
+        !this.invalidated.has(id)
+      ) {
         this.opts.logger.warn(
           `[connecta] connector "${id}" catalog refresh failed; serving stale catalog: ${msg(err)}`,
         );
@@ -675,29 +727,37 @@ export class Registry implements RegistryView {
 
   /** Drop a connector's cached tool list (e.g. after auth completes). */
   invalidate(id: string): void {
+    this.advanceCatalogGeneration(id);
     this.cache.delete(id);
     this.invalidated.add(id);
     if (this.persistToolCatalog) {
-      void this.opts.storage.delete(this.catalogKey(id)).catch((err) => {
-        this.opts.logger.warn(
-          `[connecta] connector "${id}" catalog invalidation failed: ${msg(err)}`,
-        );
+      void this.enqueueCatalogMutation(id, async () => {
+        try {
+          await this.opts.storage.delete(this.catalogKey(id));
+        } catch (err) {
+          this.opts.logger.warn(
+            `[connecta] connector "${id}" catalog invalidation failed: ${msg(err)}`,
+          );
+        }
       });
     }
   }
 
   /** Drop both in-memory and persisted tool catalogs. */
   async invalidateStored(id: string): Promise<void> {
+    this.advanceCatalogGeneration(id);
     this.cache.delete(id);
     this.invalidated.add(id);
     if (this.persistToolCatalog) {
-      try {
-        await this.opts.storage.delete(this.catalogKey(id));
-      } catch (err) {
-        this.opts.logger.warn(
-          `[connecta] connector "${id}" catalog invalidation failed: ${msg(err)}`,
-        );
-      }
+      await this.enqueueCatalogMutation(id, async () => {
+        try {
+          await this.opts.storage.delete(this.catalogKey(id));
+        } catch (err) {
+          this.opts.logger.warn(
+            `[connecta] connector "${id}" catalog invalidation failed: ${msg(err)}`,
+          );
+        }
+      });
     }
   }
 }