@zackbart/connecta 0.8.0 → 0.9.0

package/src/connectors/remote-mcp.ts

@@ -1,13 +1,17 @@
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import {
+  Client,
+  isInputRequiredResult,
+  specTypeSchemas,
+  StreamableHTTPClientTransport,
+  UnauthorizedError,
+} from "@modelcontextprotocol/client";
 import type {
   FetchLike,
+  ListToolsResult,
+  StandardSchemaV1,
+  Tool,
   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";
+} from "@modelcontextprotocol/client";
 import { KvOAuthProvider } from "../auth/downstream-oauth.js";
 import { MAX_CATALOG_TOOLS } from "../catalog-limits.js";
 import { ConnectorCallError } from "../errors.js";
@@ -131,36 +135,29 @@ type ListedTool = Awaited<ReturnType<Client["listTools"]>>["tools"][number];
  * 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.
- *
- * 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
- * exactly and `test/remote-mcp-pagination.test.ts` asserts the method still
- * exists, so a bump that renames it fails CI rather than quietly restoring the
- * bug.
- */
-function primeToolMetadata(client: Client, tools: ListedTool[]): void {
-  const prime = (
-    client as unknown as {
-      cacheToolMetadata?: (tools: ListedTool[]) => void;
-    }
-  ).cacheToolMetadata;
-  if (typeof prime !== "function") return;
-  prime.call(client, tools);
-}
+const CompatibleListToolsResultSchema: StandardSchemaV1<
+  unknown,
+  ListToolsResult
+> = {
+  "~standard": {
+    version: 1,
+    vendor: "connecta",
+    validate(value) {
+      const normalized =
+        typeof value === "object" &&
+        value !== null &&
+        "nextCursor" in value &&
+        value.nextCursor === null
+          ? (() => {
+              const copy = { ...value };
+              delete copy.nextCursor;
+              return copy;
+            })()
+          : value;
+      return specTypeSchemas.ListToolsResult["~standard"].validate(normalized);
+    },
+  },
+};
 
 /**
  * True for a result-parse failure caused by the page's `nextCursor` itself.
@@ -171,13 +168,18 @@ function primeToolMetadata(client: Client, tools: ListedTool[]): void {
  */
 function isCursorShapeError(err: unknown): boolean {
   const issues = (err as { issues?: unknown } | null)?.issues;
-  return (
+  if (
     Array.isArray(issues) &&
     issues.some((issue) => {
       const path = (issue as { path?: unknown }).path;
       return Array.isArray(path) && path[0] === "nextCursor";
     })
-  );
+  ) {
+    return true;
+  }
+  // SDK v2 wraps Standard Schema failures in a ProtocolError and preserves the
+  // failing path in the message rather than exposing the validator's issues.
+  return msg(err).startsWith("Invalid result for tools/list: nextCursor:");
 }
 
 function msg(err: unknown): string {
@@ -190,8 +192,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
@@ -394,6 +395,14 @@ export function redirectSafeFetch(
 interface ConnectionState {
   client: Client | null;
   transport: Transport | null;
+  /**
+   * The last complete raw catalog, retained only for this request scope.
+   *
+   * SDK v2 exposes `toolDefinition` as the public call-time seam for output
+   * validation and header mirroring, replacing the v1 private
+   * `cacheToolMetadata` reach-through.
+   */
+  toolDefinitions: Map<string, Tool>;
   connecting: Promise<void> | null;
   authRequired: boolean;
   provider: KvOAuthProvider | null;
@@ -468,6 +477,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
@@ -485,12 +502,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;
@@ -509,6 +521,7 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
       state = {
         client: null,
         transport: null,
+        toolDefinitions: new Map(),
         connecting: null,
         authRequired: false,
         provider: null,
@@ -547,29 +560,23 @@ 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;
-    return new StreamableHTTPClientTransport(
-      url,
-      {
-        ...(headers ? { requestInit: { headers } } : {}),
-        fetch: guardedFetch,
-      },
-    ) as unknown as Transport;
+    return new StreamableHTTPClientTransport(url, {
+      ...(headers ? { requestInit: { headers } } : {}),
+      fetch: guardedFetch,
+    });
   };
 
   const reset = (state: ConnectionState) => {
     state.client = null;
     state.transport = null;
+    state.toolDefinitions.clear();
     state.connecting = null;
     state.authRequired = false;
     state.provider = null;
@@ -650,13 +657,17 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
           throw operatorDisconnectedError();
         }
         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.
+        // SDK v2 selects its validator by runtime export condition: AJV on
+        // Node and @cfworker/json-schema under workerd. The Workers-safe path
+        // no longer needs Connecta-specific wiring.
         const c = new Client(
           { name: "connecta", version: CONNECTA_VERSION },
-          { jsonSchemaValidator: new CfWorkerJsonSchemaValidator() },
+          {
+            versionNegotiation: { mode: "auto" },
+            // Connecta has no interactive relay. Surface the result manually
+            // below as one structured, non-retryable connector failure.
+            inputRequired: { autoFulfill: false },
+          },
         );
         const t = buildTransport(ctx, provider);
         if (!ownsAttempt()) await abandon(t);
@@ -869,9 +880,9 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
           `Connector "${id}" kept advertising more tools/list pages after ${MAX_TOOL_PAGES} — refusing to page further.`,
         );
       }
-      // Repair what the per-page listTools calls left behind before any of
-      // these tools can be called. See primeToolMetadata.
-      primeToolMetadata(client, listed);
+      // Publish definitions only after the full walk succeeds. A later-page
+      // failure must not leave a partial validation/header view behind.
+      state.toolDefinitions = new Map(listed.map((tool) => [tool.name, tool]));
       return listed.map((t) => ({
         name: t.name,
         ...(t.description !== undefined ? { description: t.description } : {}),
@@ -904,19 +915,32 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
       await ensureConnected(ctx, state);
       const client = state.client!;
       try {
-        return await client.callTool(
+        const toolDefinition = state.toolDefinitions.get(name);
+        if (toolDefinition?.execution?.taskSupport === "required") {
+          throw new Error(
+            `Tool "${name}" requires task-based execution, which Connecta does not support.`,
+          );
+        }
+        const result = await client.callTool(
           {
             name,
             arguments: (args ?? {}) as Record<string, unknown>,
           },
-          undefined,
-          ctx.timeoutMs || ctx.signal
-            ? {
-                ...(ctx.timeoutMs ? { timeout: ctx.timeoutMs } : {}),
-                ...(ctx.signal ? { signal: ctx.signal } : {}),
-              }
-            : undefined,
+          {
+            ...requestOptions(ctx),
+            allowInputRequired: true,
+            ...(toolDefinition ? { toolDefinition } : {}),
+          },
         );
+        if (isInputRequiredResult(result)) {
+          throw new ConnectorCallError(
+            "input_required_unsupported",
+            `Connector "${id}" returned input_required for "${name}". ` +
+              "Connecta cannot relay multi-round-trip input yet; this " +
+              "capability is gated pending real host and downstream adoption.",
+          );
+        }
+        return result;
       } catch (err) {
         // A grant revoked after connect surfaces here, not in ensureConnected.
         if (err instanceof UnauthorizedError) {
@@ -942,6 +966,7 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
       const transport = state.transport;
       state.client = null;
       state.transport = null;
+      state.toolDefinitions.clear();
       state.connecting = null;
       state.authRequired = false;
       state.connectedGeneration = null;
@@ -982,7 +1007,7 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
       }
     },
 
-    async finishAuth(code, ctx) {
+    async finishAuth(code, ctx, callbackParams) {
       const state = stateFor(ctx);
       const provider = getProvider(ctx, state);
       // verifyState ran on this request-scoped provider first and captured the
@@ -990,7 +1015,11 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
       // token write remains tagged with that older generation and is unreadable.
       const t = (state.transport ??
         buildTransport(ctx, provider)) as StreamableHTTPClientTransport;
-      await t.finishAuth(code);
+      if (callbackParams !== undefined) {
+        await t.finishAuth(callbackParams);
+      } else {
+        await t.finishAuth(code);
+      }
       await provider.clearPending();
       // Reset so the next use reconnects with the freshly stored tokens.
       reset(state);
@@ -998,15 +1027,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);

package/src/errors.ts

@@ -8,14 +8,22 @@ export type ConnectorCallErrorCode =
   | "rate_limited"
   | "unavailable"
   | "invalid_args"
+  | "input_required_unsupported"
   | "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,
   unavailable: true,
   auth_required: false,
   invalid_args: false,
+  input_required_unsupported: false,
   connector_call_failed: false,
 };
 
@@ -78,6 +86,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 =

package/src/execute.ts

@@ -1,8 +1,8 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { McpServer } from "@modelcontextprotocol/server";
 import { z } from "zod";
 import type { ActivityRequestContext } from "./activity.js";
 import {
-  assertDiscoveryResultSize,
+  boundedDiscoveryText,
   CatalogService,
   flatSearchResult,
 } from "./catalog-service.js";
@@ -16,14 +16,12 @@ import {
   ExecutorAdmissionError,
   isAdmittingExecutor,
 } from "./executor-admission.js";
-import { unwrapMcpResult } from "./mcp-result.js";
 import {
   InvocationFailure,
   InvocationService,
 } from "./invocation.js";
 import type { RegistryView } from "./registry.js";
 import type {
-  Connector,
   Executor,
   ExecutorProvider,
   Logger,
@@ -137,19 +135,6 @@ ${declarations}
 })();`;
 }
 
-/**
- * Unwrap an MCP CallToolResult so sandbox code sees plain values:
- * isError throws (a real exception the code can catch), structuredContent
- * wins when present, all-text content is JSON.parsed when possible.
- * Non-MCP connectors already return plain values.
- */
-export function unwrapForSandbox(
-  kind: Connector["kind"],
-  result: unknown,
-): unknown {
-  return unwrapMcpResult(kind, result);
-}
-
 /**
  * Expose one fixed host provider plus trusted sandbox setup that creates a
  * lazy proxy global per connector. No connector catalog is touched until code
@@ -165,6 +150,7 @@ export async function buildSandboxProviders(
     maxHostCalls?: number;
     hostCallTimeoutMs?: number;
     discoveryConcurrency?: number;
+    onInvocationFailure?: (failure: InvocationFailure) => void;
   } = {},
 ): Promise<ExecutorProvider[]> {
   // All host calls made by one execute_code invocation share a downstream
@@ -225,7 +211,11 @@ export async function buildSandboxProviders(
       args ?? {},
       invocationContext(),
     );
-    if (!outcome.ok) throw new InvocationFailure(outcome.error);
+    if (!outcome.ok) {
+      const failure = new InvocationFailure(outcome.error);
+      limits.onInvocationFailure?.(failure);
+      throw failure;
+    }
     return outcome.value;
   };
   const callNamespace = async (
@@ -240,7 +230,11 @@ export async function buildSandboxProviders(
       args ?? {},
       invocationContext(),
     );
-    if (!outcome.ok) throw new InvocationFailure(outcome.error);
+    if (!outcome.ok) {
+      const failure = new InvocationFailure(outcome.error);
+      limits.onInvocationFailure?.(failure);
+      throw failure;
+    }
     return outcome.value;
   };
 
@@ -287,7 +281,7 @@ export async function buildSandboxProviders(
             includeSchemas?: "compact" | "json";
           };
           const result = flatSearchResult(await catalog.search(args));
-          assertDiscoveryResultSize(
+          boundedDiscoveryText(
             result,
             "Request a smaller limit, omit fullDescriptions, or use compact schemas.",
           );
@@ -300,7 +294,7 @@ export async function buildSandboxProviders(
             fullDescriptions?: boolean;
           };
           const result = { tools: await catalog.describe(args) };
-          assertDiscoveryResultSize(
+          boundedDiscoveryText(
             result,
             'Split the address list or use format: "compact".',
           );
@@ -332,6 +326,7 @@ export function createExecuteTool(
     }
     let lease;
     let outcome;
+    const invocationFailures: InvocationFailure[] = [];
     try {
       // Admission comes before provider construction: queued calls retain no
       // catalogs, request scopes, or one-closure-per-tool provider arrays.
@@ -350,6 +345,9 @@ export function createExecuteTool(
         activity,
         {
           signal: controller.signal,
+          onInvocationFailure: (failure) => {
+            invocationFailures.push(failure);
+          },
           ...(config.discoveryConcurrency !== undefined
             ? { discoveryConcurrency: config.discoveryConcurrency }
             : {}),
@@ -401,6 +399,27 @@ export function createExecuteTool(
           )
         : undefined;
     if (outcome.error) {
+      // Executor bridges necessarily reduce thrown host errors to strings.
+      // Match that terminal string back to the request-local typed failure so
+      // an unhandled tool failure keeps the same structured contract as
+      // call_tool and batch_call. Failures caught by model code never reach
+      // outcome.error and therefore remain under that code's control.
+      let invocationFailure: InvocationFailure | undefined;
+      for (let i = invocationFailures.length - 1; i >= 0; i--) {
+        const candidate = invocationFailures[i];
+        if (candidate && outcome.error.includes(candidate.message)) {
+          invocationFailure = candidate;
+          break;
+        }
+      }
+      if (invocationFailure) {
+        const result = jsonResult({
+          error: invocationFailure.details,
+          ...(logs ? { logs } : {}),
+        });
+        result.isError = true;
+        return result;
+      }
       return errorResult(
         `Error: ${outcome.error}${logs ? `\n\nLogs:\n${logs}` : ""}`,
       );
@@ -463,11 +482,11 @@ export function registerExecuteTool(
     "execute_code",
     {
       description: EXECUTE_DESC,
-      inputSchema: {
+      inputSchema: z.object({
         code: z
           .string()
           .describe("A JavaScript async arrow function to execute."),
-      },
+      }),
       // The sandbox exposes only tools that are explicitly read-only, and the
       // executor grants no network, filesystem, env, or timer capabilities.
       annotations: {
@@ -478,7 +497,7 @@ export function registerExecuteTool(
     },
     async (args, extra) => {
       const controller = new AbortController();
-      const signals = [extra.signal, ctx.requestSignal].filter(
+      const signals = [extra.mcpReq.signal, ctx.requestSignal].filter(
         (signal): signal is AbortSignal => signal !== undefined,
       );
       const forwarders = signals.map((signal) => {

package/src/executor-result.ts

@@ -9,7 +9,7 @@ function msg(err: unknown): string {
 }
 
 function serializeExecuteValue(value: unknown): string {
-  const serialized = JSON.stringify(value, null, 2);
+  const serialized = JSON.stringify(value);
   return serialized === undefined ? String(value) : serialized;
 }