@zackbart/connecta 0.24.2 → 0.24.4

package/dist/connectors/guarded-fetch.js

@@ -1,14 +1,33 @@
-/** See documentation/connectors.md#the-guarded-fetch-transport. Web APIs only. */
-import { ConnectorCallError } from "../errors.js";
-/** Parse a decimal `Retry-After` header in seconds into milliseconds. */
+/**
+ * The safety machinery every hand-written HTTP surface needs, extracted once
+ * (#341): path confinement, encoded query and framed bodies, per-request
+ * credential headers applied last, a refused redirect, a bounded read, and
+ * network-failure normalization. It owns no *meaning* — it never reads a status
+ * code and never invents an auth scheme, because the same 403 means an ungranted
+ * capability at one provider and a token scope at another, and those want
+ * opposite next moves. The provider's `authenticate` supplies headers and its
+ * mapper turns one `GuardedResponse` into a result or a typed failure.
+ *
+ * Not exported this release: the migrations proved the shape preserves behavior
+ * for connectors that already had this machinery, not that it is the right
+ * public surface. Web APIs only.
+ */
+import { ConnectorCallError, unavailableCallError } from "../errors.js";
+/** Parse delta-seconds or an HTTP-date into a non-negative wait window. */
 export function retryAfterMs(headers) {
     const raw = headers.get("retry-after");
     if (!raw)
         return undefined;
     const seconds = Number(raw.trim());
-    if (!Number.isFinite(seconds) || seconds < 0)
+    if (Number.isFinite(seconds)) {
+        return seconds < 0 ? undefined : Math.trunc(seconds * 1000);
+    }
+    // Require the HTTP-date shape, so Date.parse cannot reinterpret "-1" as
+    // a calendar date on runtimes that accept loose date strings.
+    if (!/^[A-Za-z]{3}, \d{2} [A-Za-z]{3} \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(raw.trim()))
         return undefined;
-    return Math.trunc(seconds * 1000);
+    const date = Date.parse(raw);
+    return Number.isFinite(date) ? Math.max(0, date - Date.now()) : undefined;
 }
 /** Statuses that instruct a client to re-send somewhere else. Never followed. */
 const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
@@ -117,7 +136,18 @@ async function drain(provider, stream, limit) {
     }
     return body;
 }
-/** See documentation/connectors.md#the-guarded-fetch-transport. */
+/**
+ * Every read is capped at `maxResponseBytes`: a streaming body is abandoned at
+ * the ceiling rather than buffered past it, and where a runtime gives no body
+ * stream the text is measured in UTF-8 bytes before it is accepted, with JSON
+ * parsed from that same bounded text. Such a runtime still buffers internally,
+ * but cannot return an oversized body as a successful result.
+ *
+ * A mapper must re-throw `ConnectorCallError` and swallow only what it
+ * recognizes: a bare `catch` around `response.json()` eats this refusal along
+ * with a parse error and turns a response nobody was allowed to read into an
+ * empty success.
+ */
 function boundedResponse(provider, response, limit) {
     if (BODILESS_STATUSES.has(response.status)) {
         const emptyJson = async () => undefined;
@@ -144,13 +174,20 @@ function boundedResponse(provider, response, limit) {
             });
         return read;
     };
+    let readText;
+    const text = () => {
+        readText ??= stream
+            ? bytes().then((body) => decoder.decode(body))
+            : response.text().then((body) => {
+                const size = encoder.encode(body).length;
+                if (size > limit)
+                    throw oversized(provider, limit, `${size} bytes`);
+                return body;
+            });
+        return readText;
+    };
     const json = async () => {
-        // No stream means no bytes to count: a stand-in that answers `json()`
-        // directly is taken at its word, which is the one accessor on the one
-        // path where the ceiling cannot be applied.
-        if (!stream)
-            return await response.json();
-        const body = decoder.decode(await bytes());
+        const body = await text();
         return body.trim() === "" ? undefined : JSON.parse(body);
     };
     return {
@@ -158,15 +195,7 @@ function boundedResponse(provider, response, limit) {
         ok: response.ok,
         headers: response.headers,
         bytes,
-        async text() {
-            if (stream)
-                return decoder.decode(await bytes());
-            const body = await response.text();
-            const size = encoder.encode(body).length;
-            if (size > limit)
-                throw oversized(provider, limit, `${size} bytes`);
-            return body;
-        },
+        text,
         json,
         jsonResult: () => jsonResult(json),
     };
@@ -181,7 +210,11 @@ async function jsonResult(read) {
         return { parseError: cause };
     }
 }
-/** Build the guarded transport described in documentation/connectors.md. */
+/**
+ * Build the transport a connector sends every request through. `maxResponseBytes`
+ * is required rather than defaulted: what counts as an absurd response is a fact
+ * about the API, not about HTTP.
+ */
 export function guardedFetch(options) {
     const { provider, maxResponseBytes: limit } = options;
     if (!Number.isInteger(limit) || limit < 1) {
@@ -224,13 +257,17 @@ export function guardedFetch(options) {
                     : request.rawBody !== undefined
                         ? { body: request.rawBody }
                         : {}),
-                // Rationale: documentation/connectors.md#the-guarded-fetch-transport.
+                // A redirect is an instruction to re-send the credential to whatever
+                // origin `Location` names, and a confinement a redirect can undo was
+                // never one. Refused below rather than followed.
                 redirect: "manual",
                 ...(ctx.signal ? { signal: ctx.signal } : {}),
             });
         }
         catch (cause) {
-            throw new ConnectorCallError("unavailable", `Could not reach the ${provider} API: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+            if (cause instanceof ConnectorCallError)
+                throw cause;
+            throw unavailableCallError(cause, url.href, `Could not reach the ${provider} API.`);
         }
         if (REDIRECT_STATUSES.has(response.status)) {
             await response.body?.cancel().catch(() => { });

package/dist/connectors/remote-mcp.js

@@ -1,7 +1,7 @@
-import { Client, isInputRequiredResult, specTypeSchemas, StreamableHTTPClientTransport, UnauthorizedError, } from "@modelcontextprotocol/client";
+import { Client, ProtocolError, SdkHttpError, isInputRequiredResult, specTypeSchemas, StreamableHTTPClientTransport, UnauthorizedError, } from "@modelcontextprotocol/client";
 import { KvOAuthProvider, OAuthRefreshCoordinator, } from "../auth/downstream-oauth.js";
 import { MAX_CATALOG_TOOLS } from "../catalog-limits.js";
-import { ConnectorCallError, msg } from "../errors.js";
+import { boundedEchoText, ConnectorCallError, msg, unavailableCallError, } from "../errors.js";
 import { CONNECTA_VERSION } from "../version.js";
 /**
  * Apply a maintained provider's slot copy and header framing to credential
@@ -105,8 +105,11 @@ function isCursorShapeError(err) {
  * close with the session left to age out as it did before.
  */
 async function terminateSession(transport, logger, connectorId) {
-    // See documentation/connectors.md#mcp-version-skew for the legacy DELETE
-    // that Client.close() does not send.
+    // SDK v2's Client.close() does not send the legacy session DELETE on our
+    // behalf. Connecta's own endpoint creates no protocol session, but a stateful
+    // legacy downstream can still issue `Mcp-Session-Id`, and every path that
+    // abandons one — scope teardown, credential rotation, OAuth retirement, an
+    // abandoned connect — owes it this best-effort, one-second DELETE.
     const terminate = transport.terminateSession;
     if (typeof terminate !== "function")
         return;
@@ -157,6 +160,28 @@ async function terminateSession(transport, logger, connectorId) {
         });
     });
 }
+/** Classify protocol/status facts; provider prose never decides retryability. */
+function downstreamCallError(error) {
+    if (error instanceof ProtocolError && error.code === -32602) {
+        return new ConnectorCallError("invalid_args", boundedEchoText(error.message));
+    }
+    if (error instanceof SdkHttpError && error.status >= 400 && error.status < 500) {
+        let message = error.message;
+        if (typeof error.data.text === "string") {
+            try {
+                const body = JSON.parse(error.data.text);
+                const detail = body?.message ?? body?.error?.message ?? body?.error_description;
+                if (typeof detail === "string")
+                    message = detail;
+            }
+            catch {
+                // Non-JSON refusals still retain a bounded diagnostic.
+            }
+        }
+        return new ConnectorCallError(error.status === 429 ? "rate_limited" : error.status === 408 ? "timeout" : "connector_call_failed", boundedEchoText(message));
+    }
+    return error;
+}
 const encoder = new TextEncoder();
 /** Base64 of a UTF-8 string, Web-API only so the core still runs on workerd. */
 function base64Utf8(value) {
@@ -266,10 +291,18 @@ export function redirectSafeFetch(connectorId, policy = "none", baseFetch = fetc
         const seen = new Set([current.href]);
         let hops = 0;
         while (true) {
-            const response = await baseFetch(current, {
-                ...init,
-                redirect: "manual",
-            });
+            let response;
+            try {
+                response = await baseFetch(current, {
+                    ...init,
+                    redirect: "manual",
+                });
+            }
+            catch (cause) {
+                if (cause instanceof ConnectorCallError)
+                    throw cause;
+                throw unavailableCallError(cause, current.href);
+            }
             if (!REDIRECT_STATUSES.has(response.status))
                 return response;
             const location = response.headers.get("location");
@@ -549,19 +582,38 @@ export function remoteMcp(id, opts) {
         state.credentialDigest = null;
         // `closed` is deliberately not cleared — see ConnectionState.
     };
-    const closeHalf = async (state) => {
+    // The context has no deferred-work hook. Detached exits start this bounded
+    // best-effort tail immediately; closeScope awaits its own tail so the core
+    // can pass it to the runtime's deferred channel.
+    const closingSessions = new WeakMap();
+    const closeConnection = (client, transport, logger) => {
+        const previous = transport && closingSessions.get(transport);
+        if (previous)
+            return previous;
+        const closing = (async () => {
+            try {
+                if (transport)
+                    await terminateSession(transport, logger, id);
+                if (client)
+                    await client.close();
+                else
+                    await transport?.close();
+            }
+            catch {
+                // Local close cannot replace the operation's result.
+            }
+        })();
+        // A connect can acquire a session after an early close. Deduplicate only
+        // once that session exists, so its late abandonment still sends DELETE.
+        if (transport?.sessionId)
+            closingSessions.set(transport, closing);
+        return closing;
+    };
+    const closeHalf = (state, ctx) => {
         const client = state.client;
         const transport = state.transport;
         reset(state);
-        try {
-            if (client)
-                await client.close();
-            else
-                await transport?.close();
-        }
-        catch {
-            // The discarded state remains authoritative if local close fails.
-        }
+        void closeConnection(client, transport, ctx.logger);
     };
     const ensureConnected = async (ctx, state) => {
         // A 401 after connect is a verdict for the whole request scope, not merely
@@ -581,7 +633,7 @@ export function remoteMcp(id, opts) {
             if (provider.isOperatorDisconnectedGeneration(oauthGeneration)) {
                 const connecting = state.connecting;
                 void connecting?.catch(() => { });
-                await closeHalf(state);
+                closeHalf(state, ctx);
                 throw operatorDisconnectedError();
             }
         }
@@ -592,7 +644,7 @@ export function remoteMcp(id, opts) {
             if (state.closed)
                 throw scopeEndedError();
             if (oauthGeneration !== state.connectedGeneration) {
-                reset(state);
+                closeHalf(state, ctx);
             }
         }
         // The static-credential counterpart of the epoch read above, and
@@ -618,7 +670,7 @@ export function remoteMcp(id, opts) {
                     throw scopeEndedError();
                 const connecting = state.connecting;
                 void connecting?.catch(() => { });
-                await closeHalf(state);
+                closeHalf(state, ctx);
             }
         }
         if (state.closed)
@@ -629,13 +681,8 @@ export function remoteMcp(id, opts) {
             let attempt;
             attempt = (async () => {
                 const ownsAttempt = () => state.connecting === attempt && !state.closed;
-                const abandon = async (owner) => {
-                    try {
-                        await owner.close();
-                    }
-                    catch {
-                        // The attempt is detached either way.
-                    }
+                const abandon = (client, transport) => {
+                    void closeConnection(client, transport, ctx.logger);
                     throw scopeEndedError();
                 };
                 // Let the assignment immediately below this async IIFE publish
@@ -666,7 +713,7 @@ export function remoteMcp(id, opts) {
                 });
                 const t = buildTransport(ctx, provider, credentialFramed);
                 if (!ownsAttempt())
-                    await abandon(t);
+                    abandon(null, t);
                 state.transport = t;
                 try {
                     await c.connect(t);
@@ -675,7 +722,7 @@ export function remoteMcp(id, opts) {
                     // that race anyway, close the resulting client rather than
                     // resurrecting a session in the detached state object.
                     if (!ownsAttempt())
-                        await abandon(c);
+                        abandon(c, t);
                     // 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.
@@ -685,24 +732,22 @@ export function remoteMcp(id, opts) {
                         // connect succeeded but before this client is cached. Discard the
                         // client on that side of the await too.
                         if (!ownsAttempt())
-                            await abandon(c);
+                            abandon(c, t);
                         if (generation !== genAtStart) {
-                            try {
-                                await c.close();
-                            }
-                            catch {
-                                // discarding either way
-                            }
+                            void closeConnection(c, t, ctx.logger);
                             throw new UnauthorizedError("Connector was re-authorized during connect; reconnect required.");
                         }
                     }
                     if (!ownsAttempt())
-                        await abandon(c);
+                        abandon(c, t);
                     state.client = c;
                     state.connectedGeneration = genAtStart;
                     state.authRequired = false;
                 }
                 catch (err) {
+                    void closeConnection(c, t, ctx.logger);
+                    if (ownsAttempt())
+                        state.transport = null;
                     // Only a real 401/UnauthorizedError means auth is the problem — a
                     // network error on an oauth connector must surface as "error", not
                     // "auth_required".
@@ -748,7 +793,7 @@ export function remoteMcp(id, opts) {
             // client/transport exists. Reset is unconditional because KV may already
             // be fenced behind a newer epoch after a cleanup error.
             void connecting?.catch(() => { });
-            await closeHalf(state);
+            closeHalf(state, ctx);
         }
     };
     const connector = {
@@ -825,8 +870,9 @@ export function remoteMcp(id, opts) {
         // the accumulator is returned rather than stored: a cursor is opaque and
         // session-bound, so nothing here may outlive this call.
         async listTools(ctx) {
-            // The complete-catalog rule is documented at
-            // documentation/connectors.md#catalog-contract.
+            // The catalog contract: a downstream catalog is complete or it is a
+            // failure. Follow every page to the end of the cursor chain, preserve
+            // schemas and annotations, and never cache or serve a partial walk.
             const state = stateFor(ctx);
             await ensureConnected(ctx, state);
             // Bind the client once so the whole walk provably rides one session — a
@@ -976,7 +1022,7 @@ export function remoteMcp(id, opts) {
                         state.authRequired = true;
                     throw authRequiredError(err);
                 }
-                throw err;
+                throw downstreamCallError(err);
             }
         },
         async closeScope(ctx) {
@@ -993,20 +1039,7 @@ export function remoteMcp(id, opts) {
             const client = state.client;
             const transport = state.transport;
             reset(state);
-            // Ask the downstream to drop its session first — closing only aborts our
-            // side, and the DELETE that frees the server's rides on the very
-            // AbortSignal the close is about to trip.
-            if (transport)
-                await terminateSession(transport, ctx.logger, id);
-            // Client.close() owns its connected transport. During an unfinished or
-            // failed connect there is no cached client yet, so close the transport
-            // directly to abort/release that half-open session.
-            if (client) {
-                await client.close();
-            }
-            else {
-                await transport?.close();
-            }
+            await closeConnection(client, transport, ctx.logger);
         },
         async status(ctx) {
             const state = stateFor(ctx);
@@ -1054,7 +1087,9 @@ export function remoteMcp(id, opts) {
             }
             await provider.clearPending();
             // Reset so the next use reconnects with the freshly stored tokens.
-            reset(state);
+            if (!state.transport)
+                state.transport = t;
+            closeHalf(state, ctx);
         },
     };
     if (opts.auth?.type === "oauth") {

package/dist/errors.d.ts

@@ -2,11 +2,19 @@
  * Machine-readable classification of a failed connector tool call.
  *
  * A code earns its place by changing what the caller does next, never by
- * naming a cause — the rule provider conventions call H11.
+ * naming a cause — the rule provider conventions call H11, defined in
+ * `test/provider-conventions.test.ts`.
  */
 export type ConnectorCallErrorCode = "timeout" | "auth_required" | "rate_limited" | "unavailable" | "invalid_args"
-/** Provider-owned absence; see provider-conventions.md H11 for the rule and
- * the permission-ambiguity exception. */
+/**
+ * Provider-owned absence: the caller re-addresses rather than waiting,
+ * re-authorizing, or repairing arguments, and a program looping over ids can
+ * continue past it where `connector_call_failed` would abort. Map a status
+ * here only where the provider distinguishes absence from a permission gap —
+ * where it does not (Notion's `object_not_found` covers both), the honest
+ * code stays `connector_call_failed` or `auth_required` with a message that
+ * states the ambiguity (H11).
+ */
  | "not_found" | "input_required_unsupported" | "connector_call_failed";
 /** One bounded, payload-free explanation of an input-schema mismatch. */
 export interface ArgumentValidationIssue {
@@ -39,6 +47,17 @@ export declare function boundedEchoText(value: string, maxBytes?: number): strin
 export declare function echoedCallArgs(args: unknown): {
     args?: unknown;
 };
+/** Optional transport diagnostics; never a URL path or raw runtime message. */
+interface UnavailableDetails {
+    /** HTTP(S) origin only, at most 253 UTF-8 bytes. */
+    host?: string;
+    /** Validated network errno or `timeout`, at most 32 bytes. */
+    code?: string;
+}
+/** Runtime fields only: provider prose cannot supply an errno or a deadline. */
+export declare function networkErrorCode(error: unknown): string | undefined;
+/** Use at a fetch boundary where the destination and transport failure are known. */
+export declare function unavailableCallError(cause: unknown, host?: string, message?: string): ConnectorCallError;
 /** Agent-visible recovery class attached only to `auth_required` failures. */
 export type AuthRecoveryMode = "oauth" | "operator_config" | "unavailable";
 /**
@@ -67,15 +86,20 @@ export declare class ConnectorCallError extends Error {
     readonly retryAfterMs: number | undefined;
     /** Bounded schema findings for `invalid_args`; never submitted values. */
     readonly validation: ArgumentValidationDetails | undefined;
+    /** Sanitized transport diagnostics for `unavailable` only. */
+    readonly details: UnavailableDetails | undefined;
     constructor(code: ConnectorCallErrorCode, message: string, opts?: {
         retryable?: boolean;
         retryAfterMs?: number;
         cause?: unknown;
         validation?: ArgumentValidationDetails;
+        details?: UnavailableDetails;
     });
 }
 /** The `error` object surfaced in value-mode call results and rejected promises. */
 export interface CallErrorDetails {
+    /** Sanitized transport diagnostics, absent when the runtime supplies none. */
+    details?: UnavailableDetails;
     code: string;
     message: string;
     retryable: boolean;
@@ -151,3 +175,4 @@ export declare function framingError(code: string, message: string): CallErrorDe
  */
 export declare function classifyCallError(err: unknown, fallbackCode?: string): CallErrorDetails;
 export declare function msg(err: unknown): string;
+export {};

package/dist/errors.js

@@ -20,7 +20,8 @@ function boundedIssueText(value, maxChars) {
  * the payload lands in both the text content and `structuredContent`. The agent
  * already holds what it sent; the echo is a convenience, never the record.
  */
-// Shared by argument and text echoes; see meta-tools.md lines 360-372.
+// One budget shared by the argument and text echoes, so a caller cannot make a
+// refusal larger by splitting what it sent across the two.
 const MAX_ECHOED_BYTES = 512;
 /**
  * The same budget spent on caller-authored *text* — the address it mistyped,
@@ -102,6 +103,58 @@ function boundedValidation(details) {
         ...(truncated ? { truncated: true } : {}),
     };
 }
+const NETWORK_ERROR_CODES = new Set([
+    "ECONNREFUSED", "ENOTFOUND", "ECONNRESET", "ETIMEDOUT", "EAI_AGAIN",
+    "EAI_FAIL", "EHOSTUNREACH", "ENETUNREACH", "ENETDOWN", "EHOSTDOWN",
+    "ECONNABORTED", "EPIPE", "EACCES", "EPERM",
+    "UND_ERR_CONNECT_TIMEOUT", "UND_ERR_HEADERS_TIMEOUT", "UND_ERR_BODY_TIMEOUT",
+    "UND_ERR_SOCKET", "timeout",
+]);
+function networkCode(value) {
+    return typeof value === "string" && value.length <= 32 && NETWORK_ERROR_CODES.has(value)
+        ? value
+        : undefined;
+}
+function sanitizedUnavailableDetails(details) {
+    if (!details)
+        return undefined;
+    let host;
+    if (typeof details.host === "string") {
+        try {
+            const url = new URL(details.host);
+            if ((url.protocol === "https:" || url.protocol === "http:") &&
+                echoEncoder.encode(url.origin).length <= 253)
+                host = url.origin;
+        }
+        catch {
+            // An invalid or oversized origin is absent, never a clipped destination.
+        }
+    }
+    const code = networkCode(details.code);
+    return host || code ? { ...(host ? { host } : {}), ...(code ? { code } : {}) } : undefined;
+}
+/** Runtime fields only: provider prose cannot supply an errno or a deadline. */
+export function networkErrorCode(error) {
+    if (!error || typeof error !== "object")
+        return undefined;
+    if (error instanceof Error &&
+        (error.name === "AbortError" || error.name === "TimeoutError")) {
+        return "timeout";
+    }
+    const runtime = error;
+    const cause = runtime.cause;
+    return networkCode(runtime.code) ?? (cause && typeof cause === "object"
+        ? networkCode(cause.code)
+        : undefined);
+}
+/** Use at a fetch boundary where the destination and transport failure are known. */
+export function unavailableCallError(cause, host, message = "Could not reach the downstream service.") {
+    const code = networkErrorCode(cause);
+    return new ConnectorCallError("unavailable", message, {
+        cause,
+        details: { ...(host ? { host } : {}), ...(code ? { code } : {}) },
+    });
+}
 const RETRYABLE_BY_CODE = {
     timeout: true,
     rate_limited: true,
@@ -146,12 +199,16 @@ export class ConnectorCallError extends Error {
     retryAfterMs;
     /** Bounded schema findings for `invalid_args`; never submitted values. */
     validation;
+    /** Sanitized transport diagnostics for `unavailable` only. */
+    details;
     constructor(code, message, opts = {}) {
         super(message, opts.cause !== undefined ? { cause: opts.cause } : undefined);
         this.name = "ConnectorCallError";
         this.code = code;
         this.retryable = opts.retryable ?? RETRYABLE_BY_CODE[code];
         this.retryAfterMs = normalizeRetryAfterMs(opts.retryAfterMs);
+        this.details =
+            code === "unavailable" ? sanitizedUnavailableDetails(opts.details) : undefined;
         this.validation =
             code === "invalid_args" ? boundedValidation(opts.validation) : undefined;
     }
@@ -164,6 +221,7 @@ export class ConnectorCallError extends Error {
  * trusts the flag would cheerfully retry a refusal forever.
  */
 const NEVER_RETRYABLE_FRAMING = new Set([
+    "result_processing_failed",
     "unknown_address",
     "unknown_tool",
     "ambiguous_tool_alias",
@@ -203,6 +261,7 @@ export function classifyCallError(err, fallbackCode = "connector_call_failed") {
                 ? { retryAfterMs: err.retryAfterMs }
                 : {}),
             ...(err.validation ? { validation: err.validation } : {}),
+            ...(err.details ? { details: err.details } : {}),
         };
     }
     // An aborted fetch rejects with a DOMException named "AbortError" whose