@zackbart/connecta 0.7.8 → 0.7.9

package/src/index.ts

@@ -648,6 +648,7 @@ export function createConnecta(config: ConnectaConfig): Connecta {
       closePromise ??= Promise.resolve().then(async () => {
         requestAdmission.close();
         codeAdmission?.close();
+        registry.closeCallAdmission();
         await config.executor?.close?.();
       });
       await closePromise;
@@ -698,6 +699,10 @@ export type {
 export type { ApiOptions, ApiTool } from "./connectors/api.js";
 export type {
   Connector,
+  ConnectorCallAdmissionInput,
+  ConnectorCallAdmissionPolicy,
+  ConnectorCallAdmissionRule,
+  ConnectorRollingWindowBudget,
   ConnectaBranding,
   ConnectorCredentialAccess,
   ConnectorCredentialConfig,

package/src/meta-tools.ts

@@ -17,6 +17,7 @@ import {
   messageLooksRetryable,
   type CallErrorDetails,
 } from "./errors.js";
+import { isCallAdmissionError } from "./call-admission.js";
 import {
   isValidMaxResultBytes,
   MIN_MAX_RESULT_BYTES,
@@ -228,6 +229,24 @@ function errorDetails(code: string, message: string): ErrorDetails {
   return { code, message, retryable: messageLooksRetryable(message) };
 }
 
+function callerCancelledDetails(): ErrorDetails {
+  return {
+    code: "cancelled",
+    message: "Tool call was cancelled by the caller.",
+    retryable: false,
+  };
+}
+
+function isCallerCancellation(
+  error: unknown,
+  signal: AbortSignal | undefined,
+): boolean {
+  return (
+    signal?.aborted === true ||
+    (isCallAdmissionError(error) && error.admissionKind === "cancelled")
+  );
+}
+
 /** True if `b` is a UTF-8 continuation byte (0b10xxxxxx). */
 function isContinuationByte(b: number): boolean {
   return (b & 0xc0) === 0x80;
@@ -598,6 +617,8 @@ export function createMetaTools(
     /** Per-connector deadline for the list/search/describe probe fan-out. Default 30_000. */
     probeTimeoutMs?: number;
     activity?: ActivityRequestContext;
+    /** Inbound request cancellation shared by direct and batch child calls. */
+    requestSignal?: AbortSignal;
     /** Runtime continuation for the bounded tail of probe-owned teardown. */
     defer?: DeferredWork;
   } = {},
@@ -631,6 +652,7 @@ export function createMetaTools(
     attempts: number;
     timing: {
       catalogMs: number;
+      admissionMs: number;
       connectorMs: number;
       backoffMs: number;
       resultProcessingMs: number;
@@ -648,12 +670,14 @@ export function createMetaTools(
   ): Promise<RunCallOutcome> {
     const started = Date.now();
     let catalogMs = 0;
+    let admissionMs = 0;
     let connectorMs = 0;
     let backoffMs = 0;
     let resultProcessingMs = 0;
     let attempts = 0;
     const timing = () => ({
       catalogMs,
+      admissionMs,
       connectorMs,
       backoffMs,
       resultProcessingMs,
@@ -661,7 +685,7 @@ export function createMetaTools(
     });
     const resolved = registry.resolveAddress(call.address);
     const record = (
-      outcome: "success" | "error" | "timeout",
+      outcome: "success" | "error" | "timeout" | "cancelled",
       errorCode?: string,
     ) => {
       if (!resolved) return;
@@ -679,7 +703,14 @@ export function createMetaTools(
     const failed = (error: ErrorDetails): RunCallOutcome => {
       const durationMs = Date.now() - started;
       const diagnostics = timing();
-      record(error.code === "timeout" ? "timeout" : "error", error.code);
+      record(
+        error.code === "timeout"
+          ? "timeout"
+          : error.code === "cancelled"
+            ? "cancelled"
+            : "error",
+        error.code,
+      );
       return {
         toolResult:
           call.resultMode === "value"
@@ -729,6 +760,9 @@ export function createMetaTools(
       ).find((tool) => tool.name === resolved.toolName);
     } catch (err) {
       catalogMs += Date.now() - catalogStarted;
+      if (opts.requestSignal?.aborted) {
+        return failed(callerCancelledDetails());
+      }
       // A connector whose catalog cannot be fetched is as unusable as one whose
       // execution fails, so it feeds health accounting the same way the
       // execution catch below does — otherwise a connector every call_tool
@@ -774,38 +808,76 @@ export function createMetaTools(
     let result: unknown;
     while (true) {
       attempts++;
-      const controller = timeoutMs ? new AbortController() : undefined;
+      let permit: Awaited<ReturnType<RegistryView["admitCall"]>> | undefined;
+      const controller =
+        timeoutMs || opts.requestSignal ? new AbortController() : undefined;
+      const forwardAbort = () =>
+        controller?.abort(opts.requestSignal?.reason);
+      if (opts.requestSignal?.aborted) forwardAbort();
+      else {
+        opts.requestSignal?.addEventListener("abort", forwardAbort, {
+          once: true,
+        });
+      }
       let timer: ReturnType<typeof setTimeout> | undefined;
-      const ctx = registry.contextFor(
-        resolved.connector.id,
-        baseUrl,
-        requestScope,
-        { signal: controller?.signal, timeoutMs },
-      );
-      const connectorStarted = Date.now();
+      let onAbort: (() => void) | undefined;
+      let attemptFailed = false;
+      let attemptError: unknown;
       try {
-        const pending = resolved.connector.callTool(
-          resolved.toolName,
-          call.args ?? {},
-          ctx,
+        const admissionStarted = Date.now();
+        try {
+          permit = await registry.admitCall(resolved.connector.id, {
+            toolName: resolved.toolName,
+            args: call.args ?? {},
+            signal: opts.requestSignal,
+          });
+        } finally {
+          admissionMs += Date.now() - admissionStarted;
+        }
+        const ctx = registry.contextFor(
+          resolved.connector.id,
+          baseUrl,
+          requestScope,
+          { signal: controller?.signal, timeoutMs },
         );
-        result = timeoutMs
-          ? await Promise.race([
-              pending,
-              new Promise<never>((_, reject) => {
-                timer = setTimeout(() => {
-                  reject(
-                    new ConnectorCallError(
-                      "timeout",
-                      `Tool call timed out after ${timeoutMs}ms`,
-                    ),
-                  );
-                  controller?.abort();
-                }, timeoutMs);
-              }),
-            ])
-          : await pending;
-        connectorMs += Date.now() - connectorStarted;
+        let rejectCancelled!: (reason: unknown) => void;
+        const cancelled = controller
+          ? new Promise<never>((_, reject) => {
+              rejectCancelled = reject;
+            })
+          : undefined;
+        onAbort = () => {
+          rejectCancelled(
+            controller?.signal.reason ??
+              new ConnectorCallError("timeout", "Tool call was cancelled"),
+          );
+        };
+        controller?.signal.addEventListener("abort", onAbort, { once: true });
+        if (controller?.signal.aborted) onAbort();
+        if (controller?.signal.aborted) await cancelled;
+        if (timeoutMs) {
+          timer = setTimeout(() => {
+            controller?.abort(
+              new ConnectorCallError(
+                "timeout",
+                `Tool call timed out after ${timeoutMs}ms`,
+              ),
+            );
+          }, timeoutMs);
+        }
+        const connectorStarted = Date.now();
+        try {
+          const pending = resolved.connector.callTool(
+            resolved.toolName,
+            call.args ?? {},
+            ctx,
+          );
+          result = cancelled
+            ? await Promise.race([pending, cancelled])
+            : await pending;
+        } finally {
+          connectorMs += Date.now() - connectorStarted;
+        }
         const mcpResult = result as {
           content?: TextContent[];
           isError?: boolean;
@@ -816,34 +888,72 @@ export function createMetaTools(
               "Downstream tool call failed",
           );
         }
-        break;
       } catch (err) {
-        // Includes connector setup, downstream execution, and timeout wait.
-        connectorMs += Date.now() - connectorStarted;
-        const details = classifyCallError(err);
-        if (attempts <= maxRetries && retrySafe && details.retryable) {
+        attemptFailed = true;
+        attemptError = err;
+      } finally {
+        if (timer) clearTimeout(timer);
+        if (onAbort) {
+          controller?.signal.removeEventListener("abort", onAbort);
+        }
+        opts.requestSignal?.removeEventListener("abort", forwardAbort);
+        permit?.release();
+      }
+      if (attemptFailed) {
+        const callerCancelled = isCallerCancellation(
+          attemptError,
+          opts.requestSignal,
+        );
+        const details = callerCancelled
+          ? callerCancelledDetails()
+          : classifyCallError(attemptError);
+        if (
+          !callerCancelled &&
+          attempts <= maxRetries &&
+          retrySafe &&
+          details.retryable
+        ) {
           const wait = retryBackoffMs(attempts, details.retryAfterMs);
           if (wait !== undefined) {
             const backoffStarted = Date.now();
             if (wait > 0) {
-              await new Promise((resolve) => setTimeout(resolve, wait));
+              const completed = await new Promise<boolean>((resolve) => {
+                let settled = false;
+                const finish = (value: boolean) => {
+                  if (settled) return;
+                  settled = true;
+                  clearTimeout(timer);
+                  opts.requestSignal?.removeEventListener("abort", cancel);
+                  resolve(value);
+                };
+                const timer = setTimeout(() => finish(true), wait);
+                const cancel = () => finish(false);
+                opts.requestSignal?.addEventListener("abort", cancel, {
+                  once: true,
+                });
+                if (opts.requestSignal?.aborted) cancel();
+              });
+              backoffMs += Date.now() - backoffStarted;
+              if (!completed) return failed(callerCancelledDetails());
+            } else {
+              backoffMs += Date.now() - backoffStarted;
             }
-            backoffMs += Date.now() - backoffStarted;
             continue;
           }
           // The reported window is longer than the engine will park a
           // synchronous request for. Fall through to failure with
           // retryAfterMs reported verbatim so the agent can re-issue.
         }
-        registry.recordFailure(
-          resolved.connector.id,
-          Date.now() - started,
-          err,
-        );
+        if (!callerCancelled && !isCallAdmissionError(attemptError)) {
+          registry.recordFailure(
+            resolved.connector.id,
+            Date.now() - started,
+            attemptError,
+          );
+        }
         return failed(details);
-      } finally {
-        if (timer) clearTimeout(timer);
       }
+      break;
     }
 
     registry.recordSuccess(resolved.connector.id, Date.now() - started);
@@ -1657,6 +1767,7 @@ export function registerMetaTools(
     defaultToolTimeoutMs?: number;
     probeTimeoutMs?: number;
     activity?: ActivityRequestContext;
+    requestSignal?: AbortSignal;
     defer?: DeferredWork;
   },
 ): void {
@@ -1664,6 +1775,7 @@ export function registerMetaTools(
     defaultToolTimeoutMs: ctx.defaultToolTimeoutMs,
     probeTimeoutMs: ctx.probeTimeoutMs,
     activity: ctx.activity,
+    requestSignal: ctx.requestSignal,
     defer: ctx.defer,
   });
 

package/src/registry.ts

@@ -18,6 +18,11 @@ import {
   type CredentialHealthConfig,
   type CredentialHealthRecord,
 } from "./credential-health.js";
+import {
+  ConnectorCallAdmissionController,
+  type CallAdmissionPermit,
+  type ConnectorCallAdmissionSnapshot,
+} from "./call-admission.js";
 import type { DeferredWork } from "./connector-scope.js";
 import { splitAddress, type Toolkit } from "./toolkits.js";
 
@@ -212,6 +217,14 @@ export interface RegistryView {
     requestScope?: object,
     callOptions?: ConnectorOperationOptions,
   ): ConnectorContext;
+  /**
+   * Acquire the connector's shared downstream-call permit. Scoped views
+   * delegate to the base registry so every toolkit contends on the same pool.
+   */
+  admitCall(
+    id: string,
+    input: { toolName: string; args: unknown; signal?: AbortSignal },
+  ): Promise<CallAdmissionPermit>;
   resultsStorage(): KVStorage;
   recordSuccess(id: string, latencyMs: number): void;
   recordFailure(id: string, latencyMs: number, error: unknown): void;
@@ -242,6 +255,10 @@ export interface RegistryView {
  */
 export class Registry implements RegistryView {
   private readonly connectors = new Map<string, Connector>();
+  private readonly callAdmission = new Map<
+    string,
+    ConnectorCallAdmissionController
+  >();
   private readonly cache = new Map<string, CacheEntry>();
   private readonly invalidated = new Set<string>();
   /** Per-connector epoch preventing a pre-invalidation refresh from publishing. */
@@ -287,6 +304,12 @@ export class Registry implements RegistryView {
         throw new Error(`Duplicate connector id "${c.id}"`);
       }
       this.connectors.set(c.id, c);
+      if (c.callAdmission) {
+        this.callAdmission.set(
+          c.id,
+          new ConnectorCallAdmissionController(c.id, c.callAdmission),
+        );
+      }
     }
     this.checkConventions(opts.logger);
     this.checkResultCaps(
@@ -430,6 +453,30 @@ export class Registry implements RegistryView {
     };
   }
 
+  admitCall(
+    id: string,
+    input: { toolName: string; args: unknown; signal?: AbortSignal },
+  ): Promise<CallAdmissionPermit> {
+    const admission = this.callAdmission.get(id);
+    if (admission) return admission.acquire(input);
+    return Promise.resolve({ waitMs: 0, release() {} });
+  }
+
+  /** Payload-free aggregate state for the open health endpoint. */
+  callAdmissionSnapshot(): Record<string, ConnectorCallAdmissionSnapshot> {
+    return Object.fromEntries(
+      [...this.callAdmission].map(([id, admission]) => [
+        id,
+        admission.snapshot(),
+      ]),
+    );
+  }
+
+  /** Reject queued/future downstream admission; active permits release safely. */
+  closeCallAdmission(): void {
+    for (const admission of this.callAdmission.values()) admission.close();
+  }
+
   /**
    * Storage namespaced to the meta-tool result store (`results:` prefix), kept
    * separate from any connector's `conn:<id>:` namespace. Backs get_result.
@@ -946,6 +993,14 @@ export class ScopedRegistry implements RegistryView {
     return this.base.contextFor(id, baseUrl, requestScope, callOptions);
   }
 
+  admitCall(
+    id: string,
+    input: { toolName: string; args: unknown; signal?: AbortSignal },
+  ): Promise<CallAdmissionPermit> {
+    if (!this.visible(id)) return Promise.reject(this.unknownConnector(id));
+    return this.base.admitCall(id, input);
+  }
+
   /**
    * Stashed oversized results are bound to the scope that produced them: a
    * scoped session cannot page a result it could not have produced, and an id

package/src/server.ts

@@ -1273,6 +1273,7 @@ async function serveMcp(
     activity,
     defaultToolTimeoutMs: opts.defaultToolTimeoutMs,
     probeTimeoutMs: opts.probeTimeoutMs,
+    requestSignal: request.signal,
     ...(runtimeContext
       ? { defer: runtimeContext.waitUntil.bind(runtimeContext) }
       : {}),
@@ -1577,6 +1578,10 @@ export function createFetchHandler(
             code: opts.executor
               ? (codeAdmission ?? { managedByExecutor: true })
               : null,
+            downstreamCalls: {
+              policy: "connector-partitioned-per-runtime",
+              connectors: registry.callAdmissionSnapshot(),
+            },
             reservedRoutes: [
               "/health",
               "/",

package/src/types.ts

@@ -44,6 +44,61 @@ export interface ToolAnnotations extends Record<string, unknown> {
   openWorldHint?: boolean;
 }
 
+/** Inputs a connector may reduce to a non-secret admission partition key. */
+export interface ConnectorCallAdmissionInput {
+  toolName: string;
+  args: unknown;
+}
+
+/** Exact sliding-window budget for one connector-call partition. */
+export interface ConnectorRollingWindowBudget {
+  kind: "rolling-window";
+  /** Calls admitted during `windowMs` before another is proactively refused. */
+  maxCalls: number;
+  /** Width of the rolling window in milliseconds. */
+  windowMs: number;
+}
+
+/**
+ * One connector-level downstream call-admission rule.
+ *
+ * This release accepts the plural `rules` container below but enforces exactly
+ * one rule. That keeps the public shape ready for providers whose concurrency
+ * and budget limits eventually need different partition dimensions without
+ * pretending multi-rule admission is already atomic.
+ */
+export interface ConnectorCallAdmissionRule {
+  /** Maximum simultaneous Connector.callTool attempts in one partition. */
+  maxConcurrency?: number;
+  /** Callers allowed to wait behind the concurrency bound. Default 32. */
+  maxQueueSize?: number;
+  /** Maximum concurrency-queue wait in milliseconds. Default 5,000. */
+  queueTimeoutMs?: number;
+  /** Retry hint for concurrency overloads. Default 1,000. */
+  retryAfterMs?: number;
+  /** Optional exact rolling-window call-start budget. */
+  budget?: ConnectorRollingWindowBudget;
+  /**
+   * Derive a bounded, non-secret partition key from the tool call. Omit for
+   * one connector-wide partition. Connecta retains the returned key only; it
+   * never copies arguments into limiter state.
+   */
+  partitionKey?(
+    input: Readonly<ConnectorCallAdmissionInput>,
+  ): string;
+}
+
+/** Optional downstream call-admission policy declared by one connector. */
+export interface ConnectorCallAdmissionPolicy {
+  /**
+   * Plural-ready policy container. Exactly one rule is supported in this
+   * release; empty or multi-rule policies fail construction.
+   */
+  rules: readonly ConnectorCallAdmissionRule[];
+  /** Maximum simultaneously retained partition states. Default 1,024. */
+  maxPartitions?: number;
+}
+
 export type ConnectorCredentialValues = Record<string, string>;
 
 /** Read-only access to the credentials assigned to one connector. */
@@ -145,6 +200,12 @@ export interface Connector {
    * the connector inherits the deployment-wide cap.
    */
   maxResultBytes?: number;
+  /**
+   * Optional per-runtime admission policy for downstream tool calls. It covers
+   * call_tool, every batch_call child, and execute_code host calls, but not
+   * catalog/status/auth operations.
+   */
+  callAdmission?: ConnectorCallAdmissionPolicy;
   /**
    * Optional agent-facing usage guide (markdown) for this connector — preferred
    * tools, address quirks, pagination conventions, rate-limit etiquette, good

package/src/ui.ts

@@ -1064,7 +1064,8 @@ ${clerkScript}
   .activity-address { font-family: var(--mono); font-size: .78rem; overflow-wrap: anywhere; }
   .activity-outcome { font-size: .9em; }
   .activity-item.error .activity-outcome,
-  .activity-item.timeout .activity-outcome { text-decoration: underline; }
+  .activity-item.timeout .activity-outcome,
+  .activity-item.cancelled .activity-outcome { text-decoration: underline; }
   .activity-empty { border-top: 1px solid var(--rule); padding: .75rem 0; }
   .activity-more { margin-top: .75rem; }
   .unavailable {
@@ -1498,9 +1499,12 @@ function renderActivity() {
   }
   for (const event of visible) {
     const item = document.createElement("article");
-    const outcomeClass = ["success", "error", "timeout"].includes(event.outcome)
-      ? event.outcome
-      : "error";
+    const outcomeClass = [
+      "success",
+      "error",
+      "timeout",
+      "cancelled",
+    ].includes(event.outcome) ? event.outcome : "error";
     item.className = "activity-item " + outcomeClass;
     const retryCopy = event.attempts > 1
       ? " · " + esc(event.attempts) + " attempts"

package/src/version.ts

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.7.8";
+export const CONNECTA_VERSION = "0.7.9";