@zackbart/connecta 0.18.2 → 0.19.0

package/dist/connectors/remote-mcp.js

@@ -1,7 +1,7 @@
 import { Client, isInputRequiredResult, specTypeSchemas, StreamableHTTPClientTransport, UnauthorizedError, } from "@modelcontextprotocol/client";
 import { KvOAuthProvider } from "../auth/downstream-oauth.js";
 import { MAX_CATALOG_TOOLS } from "../catalog-limits.js";
-import { ConnectorCallError } from "../errors.js";
+import { ConnectorCallError, msg } from "../errors.js";
 import { CONNECTA_VERSION } from "../version.js";
 /**
  * Apply a maintained provider's slot copy and header framing to credential
@@ -33,28 +33,6 @@ export function withCredentialDefaults(auth, defaults) {
  * response, while callers continue to wait at most 100 ms.
  */
 const TERMINATE_SESSION_BUDGET_MS = 1_000;
-/**
- * Ceiling on the tools one catalog refresh will accumulate while walking
- * `tools/list`.
- *
- * This is the bound that matters, and pages are the wrong dimension to put it
- * in: the *server* picks the page size, so a page ceiling is a tool ceiling
- * multiplied by a number connecta can neither observe in advance nor control.
- * At ten tools a page, 100 pages is 1,000 tools; at a hundred, 10,000 — and
- * connecta's own large-catalog envelope is benchmarked to 100,000 (issue #82).
- * A page ceiling low enough to be a real defense therefore sits *inside* the
- * catalog sizes this product exists to serve. Worse, the common conformant
- * idiom is to advertise a `nextCursor` whenever a page came back full and then
- * serve one empty page to terminate, so a perfectly well-behaved 10,000-tool
- * server paging at 100 spends 101 requests: bound the pages and its entire
- * catalog fails, for doing nothing wrong.
- *
- * So the ceiling goes on accumulated tools — the thing actually held in memory
- * — and it sits at the top of the benchmarked envelope rather than below it.
- * Deliberately the same philosophy as issue #82's discovery-response bounds:
- * cap the bytes a caller can be made to hold, not the number of round trips it
- * took to get them.
- */
 /**
  * Absolute backstop on `tools/list` pages in one refresh — a runaway guard, not
  * the primary defense.
@@ -111,9 +89,6 @@ function isCursorShapeError(err) {
     // 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) {
-    return err instanceof Error ? err.message : String(err);
-}
 /**
  * End the downstream's session before the connection is torn down.
  *
@@ -130,6 +105,8 @@ function msg(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.
     const terminate = transport.terminateSession;
     if (typeof terminate !== "function")
         return;
@@ -517,11 +494,14 @@ export function remoteMcp(id, opts) {
         }
         return state;
     };
-    const getProvider = (ctx, state) => {
-        state.provider ??= new KvOAuthProvider(id, ctx.storage, `${ctx.baseUrl}/oauth/callback/${id}`);
-        return state.provider;
+    const newProvider = (ctx, state) => {
+        if (state?.provider)
+            return state.provider;
+        const provider = new KvOAuthProvider(id, ctx.storage, `${ctx.baseUrl}/oauth/callback/${id}`);
+        if (state)
+            state.provider = provider;
+        return provider;
     };
-    const newProvider = (ctx) => new KvOAuthProvider(id, ctx.storage, `${ctx.baseUrl}/oauth/callback/${id}`);
     const buildTransport = (ctx, provider, 
     /**
      * This attempt's assembled header value, for credential auth only — framed
@@ -560,6 +540,20 @@ export function remoteMcp(id, opts) {
         state.credentialDigest = null;
         // `closed` is deliberately not cleared — see ConnectionState.
     };
+    const closeHalf = async (state) => {
+        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.
+        }
+    };
     const ensureConnected = async (ctx, state) => {
         // A 401 after connect is a verdict for the whole request scope, not merely
         // for the one call that observed it. Do not let the still-cached client make
@@ -573,23 +567,12 @@ export function remoteMcp(id, opts) {
         // turn it back into a pending consent flow.
         let oauthGeneration;
         if (isOauth && (state.client || state.connecting)) {
-            const provider = getProvider(ctx, state);
+            const provider = newProvider(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.
-                }
+                await closeHalf(state);
                 throw operatorDisconnectedError();
             }
         }
@@ -625,19 +608,8 @@ export function remoteMcp(id, opts) {
                 if (state.closed)
                     throw scopeEndedError();
                 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 rotated-away client is discarded either way.
-                }
+                await closeHalf(state);
             }
         }
         if (state.closed)
@@ -754,7 +726,7 @@ export function remoteMcp(id, opts) {
         return state.connecting;
     };
     const disconnectAuthorization = async (ctx, state, operatorDisconnected = false) => {
-        const provider = getProvider(ctx, state);
+        const provider = newProvider(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.
@@ -767,18 +739,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(() => { });
-            try {
-                if (state.client) {
-                    await state.client.close();
-                }
-                else {
-                    await state.transport?.close();
-                }
-            }
-            catch {
-                // best-effort; the state is discarded either way
-            }
-            reset(state);
+            await closeHalf(state);
         }
     };
     const connector = {
@@ -854,6 +815,8 @@ 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.
             const state = stateFor(ctx);
             await ensureConnected(ctx, state);
             // Bind the client once so the whole walk provably rides one session — a
@@ -1019,13 +982,7 @@ export function remoteMcp(id, opts) {
             state.closed = true;
             const client = state.client;
             const transport = state.transport;
-            state.client = null;
-            state.transport = null;
-            state.toolDefinitions.clear();
-            state.connecting = null;
-            state.authRequired = false;
-            state.connectedGeneration = null;
-            state.credentialDigest = null;
+            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.
@@ -1059,7 +1016,7 @@ export function remoteMcp(id, opts) {
                     // credential connector's downstream 401 is repaired on /credentials,
                     // so do not reach into OAuth storage to look for one.
                     const url = isOauth
-                        ? await getProvider(ctx, state).pendingAuthorizationUrl()
+                        ? await newProvider(ctx, state).pendingAuthorizationUrl()
                         : undefined;
                     return {
                         state: "auth_required",
@@ -1077,7 +1034,7 @@ export function remoteMcp(id, opts) {
         },
         async finishAuth(code, ctx, callbackParams) {
             const state = stateFor(ctx);
-            const provider = getProvider(ctx, state);
+            const provider = newProvider(ctx, state);
             // 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.
@@ -1097,14 +1054,14 @@ export function remoteMcp(id, opts) {
     if (opts.auth?.type === "oauth") {
         connector.verifyState = async (oauthState, ctx) => {
             const state = stateFor(ctx);
-            return getProvider(ctx, state).verifyState(oauthState);
+            return newProvider(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);
+            const p = newProvider(ctx, state);
             if (startOpts?.force || (await p.operatorDisconnected())) {
                 await disconnectAuthorization(ctx, state);
             }

package/dist/errors.d.ts

@@ -5,26 +5,8 @@
  * naming a cause — the rule provider conventions call H11.
  */
 export type ConnectorCallErrorCode = "timeout" | "auth_required" | "rate_limited" | "unavailable" | "invalid_args"
-/**
- * The downstream answered, and the thing addressed is not there.
- *
- * Its own code because the next move is none of the others': not a retry,
- * not `authorize_connector`, not a reshaped argument object, but
- * re-addressing — look the identifier up again, or accept the absence and
- * carry on. Inside `execute_code` a program reads that difference from a
- * caught error's `code` or a `connecta.batch` entry's `errorDetails.code` —
- * continue past this one, abort on `connector_call_failed`. Message prose
- * cannot be classified.
- *
- * Use it only where the provider distinguishes absence from a permission
- * gap. A status that means both "it is not there" and "you cannot see it" —
- * Notion's `object_not_found` is the worked example — stays
- * `connector_call_failed` with a message that states the ambiguity, because
- * inventing certainty here is how an agent concludes a page was deleted when
- * it was simply never shared. Addresses connecta itself cannot resolve are
- * already framed as `unknown_address` or `unknown_tool` and never reach a
- * connector, so this code is always about a resource the downstream owns.
- */
+/** Provider-owned absence; see provider-conventions.md H11 for the rule and
+ * the permission-ambiguity exception. */
  | "not_found" | "input_required_unsupported" | "connector_call_failed";
 /** One bounded, payload-free explanation of an input-schema mismatch. */
 export interface ArgumentValidationIssue {
@@ -48,7 +30,7 @@ export declare const MAX_ARGUMENT_VALIDATION_ISSUES = 3;
  */
 export declare function boundedEchoText(value: string, maxBytes?: number): string;
 /**
- * `{ args }` when the caller's arguments fit {@link MAX_ECHOED_ARGS_BYTES},
+ * `{ args }` when the caller's arguments fit the shared echo budget,
  * `{}` when they do not. All or nothing: a clipped echo would be a *different*
  * call than the one that was refused, and the routes this feeds end at a human
  * approving one. Unserializable arguments are treated the same way as oversized
@@ -97,11 +79,7 @@ export interface CallErrorDetails {
     code: string;
     message: string;
     retryable: boolean;
-    /**
-     * Connector-reported wait window in ms, when known. Reported verbatim — the
-     * engine bounds how long it will itself wait, but the caller sees the real
-     * window so it can schedule a re-issue.
-     */
+    /** Connector-known wait window; see {@link ConnectorCallError.retryAfterMs}. */
     retryAfterMs?: number;
     /** Bounded input-schema findings; paths and expectations, never values. */
     validation?: ArgumentValidationDetails;
@@ -132,7 +110,7 @@ export interface CallErrorDetails {
             address: string;
             /**
              * The caller's own arguments, echoed only when they fit
-             * {@link MAX_ECHOED_ARGS_BYTES} — and then whole, never clipped. Absent
+             * the shared echo budget — and then whole, never clipped. Absent
              * means "re-send exactly what you sent": a half-copied argument object
              * routed into a human approval prompt would describe a call nobody made.
              */
@@ -172,3 +150,4 @@ export declare function framingError(code: string, message: string): CallErrorDe
  * heuristic.
  */
 export declare function classifyCallError(err: unknown, fallbackCode?: string): CallErrorDetails;
+export declare function msg(err: unknown): string;

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.
  */
-const MAX_ECHOED_ARGS_BYTES = 512;
+// Shared by argument and text echoes; see meta-tools.md lines 360-372.
+const MAX_ECHOED_BYTES = 512;
 /**
  * The same budget spent on caller-authored *text* — the address it mistyped,
  * the discovery query derived from it — rather than on its arguments.
@@ -37,7 +38,6 @@ const MAX_ECHOED_ARGS_BYTES = 512;
  * `structuredContent`), so an unbounded address turned a 50 KB typo into a
  * 200 KB refusal against a deployment that capped results at 1 KB.
  */
-const MAX_ECHOED_TEXT_BYTES = 512;
 const echoEncoder = new TextEncoder();
 const echoDecoder = new TextDecoder();
 /**
@@ -45,7 +45,7 @@ const echoDecoder = new TextDecoder();
  * Short strings — the common case, and the one that has to stay exact — are
  * returned unchanged and untagged.
  */
-export function boundedEchoText(value, maxBytes = MAX_ECHOED_TEXT_BYTES) {
+export function boundedEchoText(value, maxBytes = MAX_ECHOED_BYTES) {
     const bytes = echoEncoder.encode(value);
     if (bytes.length <= maxBytes)
         return value;
@@ -57,7 +57,7 @@ export function boundedEchoText(value, maxBytes = MAX_ECHOED_TEXT_BYTES) {
     return `${echoDecoder.decode(bytes.slice(0, end))}…`;
 }
 /**
- * `{ args }` when the caller's arguments fit {@link MAX_ECHOED_ARGS_BYTES},
+ * `{ args }` when the caller's arguments fit the shared echo budget,
  * `{}` when they do not. All or nothing: a clipped echo would be a *different*
  * call than the one that was refused, and the routes this feeds end at a human
  * approving one. Unserializable arguments are treated the same way as oversized
@@ -75,7 +75,7 @@ export function echoedCallArgs(args) {
     }
     if (text === undefined)
         return {};
-    return echoEncoder.encode(text).length <= MAX_ECHOED_ARGS_BYTES
+    return echoEncoder.encode(text).length <= MAX_ECHOED_BYTES
         ? { args }
         : {};
 }
@@ -221,3 +221,6 @@ export function classifyCallError(err, fallbackCode = "connector_call_failed") {
         retryable: RETRYABLE_MESSAGE_RE.test(message),
     };
 }
+export function msg(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/execute.d.ts

@@ -136,7 +136,9 @@ export declare class EmitCollector {
      * complaint about its type would send the author to fix the wrong thing.
      */
     acceptUi(...values: unknown[]): void;
-    acceptUiPayload(payload: UiPayload): void;
+    acceptValidatedUi(payload: UiPayload): void;
+    private assertUiVacant;
+    private acceptUiPayload;
 }
 /** Convert a connector/tool name into a valid JS identifier. */
 export declare function sanitizeIdentifier(name: string): string;
@@ -146,30 +148,30 @@ export declare function sanitizeIdentifier(name: string): string;
  * calls that namespace or explicitly asks search/describe.
  */
 export declare function buildSandboxProviders(registry: RegistryView, baseUrl: string, logger: Logger, activity?: ActivityRequestContext, limits?: {
-    signal?: AbortSignal;
-    maxHostCalls?: number;
-    hostCallTimeoutMs?: number;
-    discoveryConcurrency?: number;
+    signal?: AbortSignal | undefined;
+    maxHostCalls?: number | undefined;
+    hostCallTimeoutMs?: number | undefined;
+    discoveryConcurrency?: number | undefined;
     /** Per-connector deadline for in-program catalog probes. Default 30_000. */
-    probeTimeoutMs?: number;
-    onInvocationFailure?: (failure: InvocationFailure) => void;
-    diagnostics?: ExecuteDiagnostics;
+    probeTimeoutMs?: number | undefined;
+    onInvocationFailure?: ((failure: InvocationFailure) => void) | undefined;
+    diagnostics?: ExecuteDiagnostics | undefined;
     /**
      * Where `connecta.emit` collects. The handler that will deliver the
      * blocks owns it; without one, emit fails loudly rather than accept
      * blocks nobody will ever return.
      */
-    emitCollector?: EmitCollector;
+    emitCollector?: EmitCollector | undefined;
     /** Runtime-owned tail for stale catalog refreshes. */
-    defer?: DeferredWork;
+    defer?: DeferredWork | undefined;
 }): Promise<ExecutorProvider[]>;
 /** The execute_code handler. Exported for direct testing. */
 export declare function createExecuteTool(registry: RegistryView, baseUrl: string, executor: Executor, logger: Logger, activity?: ActivityRequestContext, config?: {
-    discoveryConcurrency?: number;
-    probeTimeoutMs?: number;
-    maxEmittedBytes?: number;
-    maxEmittedBlocks?: number;
-    defer?: DeferredWork;
+    discoveryConcurrency?: number | undefined;
+    probeTimeoutMs?: number | undefined;
+    maxEmittedBytes?: number | undefined;
+    maxEmittedBlocks?: number | undefined;
+    defer?: DeferredWork | undefined;
 }): ({ code, diagnostics: diagnosticsRequested }: {
     code: string;
     diagnostics?: boolean;
@@ -181,20 +183,20 @@ export declare function registerExecuteTool(server: McpServer, registry: Registr
     baseUrl: string;
     executor: Executor;
     logger: Logger;
-    activity?: ActivityRequestContext;
-    requestSignal?: AbortSignal;
-    discoveryConcurrency?: number;
+    activity?: ActivityRequestContext | undefined;
+    requestSignal?: AbortSignal | undefined;
+    discoveryConcurrency?: number | undefined;
     /**
      * The deployment's configured per-connector probe deadline. Programs probe
      * the same downstream catalogs the top-level tools do, so an operator who
      * tightened `discovery.probeTimeoutMs` gets it honored inside the sandbox
      * too rather than silently falling back to the 30s default.
      */
-    probeTimeoutMs?: number;
+    probeTimeoutMs?: number | undefined;
     /** Aggregate serialized-byte budget for connecta.emit. Default 4_000_000. */
-    maxEmittedBytes?: number;
+    maxEmittedBytes?: number | undefined;
     /** Block-count budget for connecta.emit. Default 32. */
-    maxEmittedBlocks?: number;
-    defer?: DeferredWork;
+    maxEmittedBlocks?: number | undefined;
+    defer?: DeferredWork | undefined;
 }): void;
 export {};