@zackbart/connecta 0.7.9 → 0.8.1

package/src/connectors/api.ts

@@ -92,10 +92,10 @@ export interface ApiOptions {
 export function api(id: string, opts: ApiOptions): Connector {
   const defs: ToolDef[] = opts.tools.map((t) => ({
     name: t.name,
-    description: t.description,
-    inputSchema: t.inputSchema,
-    outputSchema: t.outputSchema,
-    annotations: t.annotations,
+    ...(t.description !== undefined ? { description: t.description } : {}),
+    ...(t.inputSchema !== undefined ? { inputSchema: t.inputSchema } : {}),
+    ...(t.outputSchema !== undefined ? { outputSchema: t.outputSchema } : {}),
+    ...(t.annotations !== undefined ? { annotations: t.annotations } : {}),
   }));
   const byName = new Map(opts.tools.map((t) => [t.name, t]));
   const validateArgs = opts.validateArgs ?? true;
@@ -110,15 +110,25 @@ export function api(id: string, opts: ApiOptions): Connector {
   }
   return {
     id,
-    title: opts.title,
+    ...(opts.title !== undefined ? { title: opts.title } : {}),
     kind: "api",
-    description: opts.description,
-    maxResultBytes: opts.maxResultBytes,
-    callAdmission: opts.callAdmission,
-    usageGuide: opts.usageGuide,
-    credential: opts.credential,
-    testCredential: opts.testCredential,
-    testCredentials: opts.testCredentials,
+    ...(opts.description !== undefined
+      ? { description: opts.description }
+      : {}),
+    ...(opts.maxResultBytes !== undefined
+      ? { maxResultBytes: opts.maxResultBytes }
+      : {}),
+    ...(opts.callAdmission !== undefined
+      ? { callAdmission: opts.callAdmission }
+      : {}),
+    ...(opts.usageGuide !== undefined ? { usageGuide: opts.usageGuide } : {}),
+    ...(opts.credential !== undefined ? { credential: opts.credential } : {}),
+    ...(opts.testCredential !== undefined
+      ? { testCredential: opts.testCredential }
+      : {}),
+    ...(opts.testCredentials !== undefined
+      ? { testCredentials: opts.testCredentials }
+      : {}),
     staticTools: defs,
     async listTools() {
       return defs;

package/src/connectors/remote-mcp.ts

@@ -9,6 +9,7 @@ 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 { MAX_CATALOG_TOOLS } from "../catalog-limits.js";
 import { ConnectorCallError } from "../errors.js";
 import { CONNECTA_VERSION } from "../version.js";
 import type {
@@ -109,18 +110,16 @@ const TERMINATE_SESSION_BUDGET_MS = 1_000;
  * cap the bytes a caller can be made to hold, not the number of round trips it
  * took to get them.
  */
-const MAX_TOOLS = 100_000;
-
 /**
  * Absolute backstop on `tools/list` pages in one refresh — a runaway guard, not
  * the primary defense.
  *
  * The walk terminates on its own well before this: a cursor handed back twice
  * 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 on a path with no discovery deadline. Set high enough that no honest
- * server reaches it.
+ * going nowhere, and MAX_CATALOG_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 on a path with no discovery deadline. Set high
+ * enough that no honest server reaches it.
  */
 const MAX_TOOL_PAGES = 10_000;
 
@@ -191,8 +190,7 @@ function msg(err: unknown): string {
  * `Client.close()` only unwinds our side — it aborts the transport's controller
  * and fires `onclose`. Spec session termination is a separate DELETE carrying
  * `Mcp-Session-Id`, and without it a stateful provider keeps the session alive
- * until its own (often hour-long) timeout, which a periodic probe would then
- * accumulate several of per connector.
+ * until its own (often hour-long) timeout, accumulating abandoned sessions.
  *
  * Ordering is load-bearing: the SDK sends that DELETE on the transport's
  * AbortSignal, so calling this *after* close would abort the request on issue
@@ -298,7 +296,9 @@ function redirectedInit(init: RequestInit, status: number): RequestInit {
   if (!becomesGet) return init;
   const headers = new Headers(init.headers);
   for (const name of BODY_HEADERS) headers.delete(name);
-  return { ...init, method: "GET", body: undefined, headers };
+  const redirected = { ...init, method: "GET", headers };
+  delete redirected.body;
+  return redirected;
 }
 
 /**
@@ -467,6 +467,14 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
   const scopeEndedError = () =>
     new Error(`Connector "${id}" scope ended during connection.`);
 
+  const requestOptions = (ctx: ConnectorContext) =>
+    ctx.timeoutMs || ctx.signal
+      ? {
+          ...(ctx.timeoutMs ? { timeout: ctx.timeoutMs } : {}),
+          ...(ctx.signal ? { signal: ctx.signal } : {}),
+        }
+      : undefined;
+
   /**
    * One `tools/list` request. The SDK schema is retained wholesale except for
    * accepting `null` as the common, unambiguous end-of-chain spelling. Other
@@ -484,12 +492,7 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
           ...(cursor === undefined ? {} : { params: { cursor } }),
         },
         CompatibleListToolsResultSchema,
-        ctx.timeoutMs || ctx.signal
-          ? {
-              ...(ctx.timeoutMs ? { timeout: ctx.timeoutMs } : {}),
-              ...(ctx.signal ? { signal: ctx.signal } : {}),
-            }
-          : undefined,
+        requestOptions(ctx),
       );
     } catch (err) {
       if (!isCursorShapeError(err)) throw err;
@@ -546,10 +549,14 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
     const url = new URL(opts.url);
     const guardedFetch = redirectSafeFetch(id, opts.redirects);
     if (opts.auth?.type === "oauth") {
+      // The SDK class declares `sessionId` as an own `string | undefined`
+      // property while its Transport interface declares it optional. They are
+      // runtime-compatible; exact optional types only exposes that declaration
+      // mismatch at this boundary.
       return new StreamableHTTPClientTransport(url, {
         authProvider: provider ?? newProvider(ctx),
         fetch: guardedFetch,
-      });
+      }) as unknown as Transport;
     }
     const headers =
       opts.auth?.type === "headers" ? opts.auth.headers : undefined;
@@ -559,7 +566,7 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
         ...(headers ? { requestInit: { headers } } : {}),
         fetch: guardedFetch,
       },
-    );
+    ) as unknown as Transport;
   };
 
   const reset = (state: ConnectionState) => {
@@ -742,12 +749,18 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
 
   const connector: Connector = {
     id,
-    title: opts.title,
+    ...(opts.title !== undefined ? { title: opts.title } : {}),
     kind: "mcp",
-    description: opts.description,
-    maxResultBytes: opts.maxResultBytes,
-    callAdmission: opts.callAdmission,
-    usageGuide: opts.usageGuide,
+    ...(opts.description !== undefined
+      ? { description: opts.description }
+      : {}),
+    ...(opts.maxResultBytes !== undefined
+      ? { maxResultBytes: opts.maxResultBytes }
+      : {}),
+    ...(opts.callAdmission !== undefined
+      ? { callAdmission: opts.callAdmission }
+      : {}),
+    ...(opts.usageGuide !== undefined ? { usageGuide: opts.usageGuide } : {}),
 
     // `tools/list` is cursor-paginated: the server chooses the page size and
     // signals "there is more" with a `nextCursor`, which the SDK's
@@ -830,9 +843,9 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
           }
           // 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) {
+          if (listed.length > MAX_CATALOG_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.`,
+              `Connector "${id}" advertised further tools/list pages past ${listed.length} tools, over the ${MAX_CATALOG_TOOLS}-tool ceiling one catalog refresh will collect.`,
             );
           }
           // Opaque by contract: handed straight back, never parsed, rewritten,
@@ -863,10 +876,28 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
       primeToolMetadata(client, listed);
       return listed.map((t) => ({
         name: t.name,
-        description: t.description,
-        inputSchema: t.inputSchema as ToolDef["inputSchema"],
-        outputSchema: t.outputSchema as ToolDef["outputSchema"],
-        annotations: t.annotations as ToolDef["annotations"],
+        ...(t.description !== undefined ? { description: t.description } : {}),
+        ...(t.inputSchema !== undefined
+          ? {
+              inputSchema: t.inputSchema as NonNullable<
+                ToolDef["inputSchema"]
+              >,
+            }
+          : {}),
+        ...(t.outputSchema !== undefined
+          ? {
+              outputSchema: t.outputSchema as NonNullable<
+                ToolDef["outputSchema"]
+              >,
+            }
+          : {}),
+        ...(t.annotations !== undefined
+          ? {
+              annotations: t.annotations as NonNullable<
+                ToolDef["annotations"]
+              >,
+            }
+          : {}),
       }));
     },
 
@@ -881,12 +912,7 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
             arguments: (args ?? {}) as Record<string, unknown>,
           },
           undefined,
-          ctx.timeoutMs || ctx.signal
-            ? {
-                ...(ctx.timeoutMs ? { timeout: ctx.timeoutMs } : {}),
-                ...(ctx.signal ? { signal: ctx.signal } : {}),
-              }
-            : undefined,
+          requestOptions(ctx),
         );
       } catch (err) {
         // A grant revoked after connect surfaces here, not in ensureConnected.
@@ -942,7 +968,7 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
           const url = await getProvider(ctx, state).pendingAuthorizationUrl();
           return {
             state: "auth_required",
-            authorizationUrl: url,
+            ...(url !== undefined ? { authorizationUrl: url } : {}),
             message: "Authorization required — open the URL to connect.",
           };
         }
@@ -969,15 +995,6 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
   };
 
   if (opts.auth?.type === "oauth") {
-    // The credential liveness checks (issue #24) probe only connectors that
-    // actually hold a stored grant: with no tokens there is nothing whose
-    // liveness could have lapsed, and a `status()` probe would kick off DCR +
-    // consent on a timer for a connector nobody has authorized yet.
-    connector.hasStoredCredential = async (ctx) => {
-      const state = stateFor(ctx);
-      return (await getProvider(ctx, state).tokens()) !== undefined;
-    };
-
     connector.verifyState = async (oauthState, ctx) => {
       const state = stateFor(ctx);
       return getProvider(ctx, state).verifyState(oauthState);
@@ -1013,9 +1030,10 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
         };
       } catch (err) {
         if (state.authRequired) {
+          const authorizationUrl = await p.pendingAuthorizationUrl();
           return {
             state: "auth_required",
-            authorizationUrl: await p.pendingAuthorizationUrl(),
+            ...(authorizationUrl !== undefined ? { authorizationUrl } : {}),
             message: "Authorization required — open the URL to connect.",
           };
         }

package/src/credentials.ts

@@ -24,7 +24,7 @@ interface CredentialPlaintext {
   updatedBy: string;
 }
 
-export interface CredentialFieldMetadata {
+interface CredentialFieldMetadata {
   configured: true;
   /** Only emitted when the value is long enough that four chars don't leak much. */
   lastFour?: string;
@@ -41,7 +41,7 @@ export interface CredentialMetadata {
 }
 
 /** Which hook a testable credential is checked with. */
-export type CredentialTestMode = "single" | "multiple";
+type CredentialTestMode = "single" | "multiple";
 
 /** Operator-safe explanation shared by every surface that detects shape drift. */
 export const STORED_CREDENTIAL_SHAPE_MISMATCH_ERROR =

package/src/errors.ts

@@ -10,6 +10,12 @@ export type ConnectorCallErrorCode =
   | "invalid_args"
   | "connector_call_failed";
 
+/** Agent-visible recovery class attached only to `auth_required` failures. */
+export type AuthRecoveryMode =
+  | "oauth"
+  | "operator_config"
+  | "unavailable";
+
 const RETRYABLE_BY_CODE: Record<ConnectorCallErrorCode, boolean> = {
   timeout: true,
   rate_limited: true,
@@ -49,7 +55,7 @@ export class ConnectorCallError extends Error {
    * the assignment would not keep it off the instance. Keeping the window out
    * of the wire format is `classifyCallError`'s job, not this constructor's.
    */
-  readonly retryAfterMs?: number;
+  readonly retryAfterMs: number | undefined;
 
   constructor(
     code: ConnectorCallErrorCode,
@@ -78,6 +84,20 @@ export interface CallErrorDetails {
    * window so it can schedule a re-issue.
    */
   retryAfterMs?: number;
+  /** Connector whose failed operation needs recovery. */
+  connector?: string;
+  /** Canonical downstream address the agent may retry after recovery. */
+  operation?: string;
+  /** Which safe recovery path `authorize_connector` will return. */
+  recovery?: AuthRecoveryMode;
+  /** The single model-facing entry point for every credential class. */
+  nextAction?: {
+    tool: "authorize_connector";
+    arguments: { connector: string };
+    operatorHandoff: string;
+  };
+  /** Explicit retry guidance; recovery never retries or mutates by itself. */
+  retry?: string;
 }
 
 const RETRYABLE_MESSAGE_RE =