@zackbart/connecta 0.7.3 → 0.7.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind nine meta-tools.",

package/src/connector-scope.ts

@@ -3,38 +3,63 @@ import type { Connector, ConnectorContext } from "./types.js";
 /** Enough for local transport abort/close without letting cleanup own latency. */
 const CONNECTOR_SCOPE_CLOSE_BUDGET_MS = 100;
 
+/**
+ * Bound on cleanup continued after the caller-facing window expires.
+ *
+ * `remoteMcp` spends at most one second asking the downstream to terminate its
+ * session, leaving another second for the local close. Custom hooks still get a
+ * finite background window: handing a never-settling promise to a Worker's
+ * `waitUntil` would otherwise keep the invocation alive until the platform cap.
+ */
+const CONNECTOR_SCOPE_DEFER_BUDGET_MS = 2_000;
+
+/** Runtime hook for work that may safely continue after a response is ready. */
+export type DeferredWork = (promise: Promise<unknown>) => void;
+
+/** Resolve when `work` settles or `budgetMs` expires; never reject. */
+function waitAtMost(work: Promise<void>, budgetMs: number): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, budgetMs);
+    work.then(() => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+}
+
 /**
  * Tell a connector that a scope owned by the core has ended.
  *
  * Scope teardown is deliberately best-effort: a missing hook is a no-op and a
  * rejected hook is swallowed so cleanup can never replace the probe result that
  * caused it. The hook gets a small, fixed completion window so edge runtimes do
- * not cut off a real close as the response ends, but one that never settles
- * cannot hold the completed probe open indefinitely. Callers own the
- * at-most-once guarantee and must not use the scope again after this returns.
+ * not cut off a real close as the response ends. When the runtime supplies
+ * `defer`, the bounded tail is handed to it without extending the caller-facing
+ * window. Callers own the at-most-once guarantee and must not use the scope
+ * again after this returns.
  */
 export async function closeConnectorScope(
   connector: Connector,
   ctx: ConnectorContext,
+  defer?: DeferredWork,
 ): Promise<void> {
   try {
     const closing = connector.closeScope?.(ctx);
     if (!closing) return;
-    await new Promise<void>((resolve) => {
-      const timer = setTimeout(resolve, CONNECTOR_SCOPE_CLOSE_BUDGET_MS);
-      // Both handlers stay attached after the timer wins, so a late rejection
-      // is still consumed rather than becoming an unhandled rejection.
-      closing.then(
-        () => {
-          clearTimeout(timer);
-          resolve();
-        },
-        () => {
-          clearTimeout(timer);
-          resolve();
-        },
-      );
-    });
+    // Attach both handlers before either timer can win, so a late rejection is
+    // consumed rather than becoming an unhandled rejection.
+    const settled = closing.then(
+      () => {},
+      () => {},
+    );
+    if (defer) {
+      try {
+        defer(waitAtMost(settled, CONNECTOR_SCOPE_DEFER_BUDGET_MS));
+      } catch {
+        // A runtime hook is best-effort too; the caller cap still applies.
+      }
+    }
+    await waitAtMost(settled, CONNECTOR_SCOPE_CLOSE_BUDGET_MS);
   } catch {
     // The scope is over whether or not the connector managed to clean it up.
   }

package/src/connectors/remote-mcp.ts

@@ -75,15 +75,14 @@ export interface RemoteMcpOptions {
 
 /**
  * How long a downstream gets to answer the session-termination DELETE before
- * teardown stops waiting. Deliberately a fraction of the core's scope-close
- * budget (`closeConnectorScope`), so the whole teardown still lands inside the
- * window that budget makes safe on an edge runtime: whatever is still in flight
- * when this expires is aborted by the close that immediately follows. What that
- * costs is only the acknowledgement — the DELETE is headers-only and has long
- * since gone out — so a slow provider still usually ends the session; it just
- * does not get to tell us so.
+ * teardown stops waiting. This is a network round-trip budget, deliberately
+ * independent of the core's 100 ms caller-facing scope-close window: an
+ * already-established cross-internet connection avoids setup, but 50 ms is
+ * still too short for an ordinary round trip plus modest provider scheduling.
+ * The bounded tail is deferred on runtimes that can keep it alive after the
+ * response, while callers continue to wait at most 100 ms.
  */
-const TERMINATE_SESSION_BUDGET_MS = 50;
+const TERMINATE_SESSION_BUDGET_MS = 1_000;
 
 /**
  * Ceiling on the tools one catalog refresh will accumulate while walking
@@ -199,24 +198,62 @@ function msg(err: unknown): string {
  * (405 is a legal answer), errors, or never replies all fall through to the
  * close with the session left to age out as it did before.
  */
-async function terminateSession(transport: Transport): Promise<void> {
+async function terminateSession(
+  transport: Transport,
+  logger: Logger,
+  connectorId: string,
+): Promise<void> {
   const terminate = (
     transport as Transport & { terminateSession?: () => Promise<void> }
   ).terminateSession;
   if (typeof terminate !== "function") return;
   // The SDK issues no request at all when no `mcp-session-id` was captured, so
   // a stateless downstream never sees a spurious DELETE.
-  const done = (async () => terminate.call(transport))().catch(() => {
-    // The session is being abandoned either way; a refusal changes nothing.
-    // Caught here rather than at the await below so a late rejection — one
-    // arriving after the budget expired — is still consumed.
-  });
+  const done = Promise.resolve().then(() => terminate.call(transport));
   await new Promise<void>((resolve) => {
-    const timer = setTimeout(resolve, TERMINATE_SESSION_BUDGET_MS);
-    done.then(() => {
-      clearTimeout(timer);
+    let finished = false;
+    const warn = (message: string, error?: unknown) => {
+      try {
+        if (error === undefined) logger.warn(message);
+        else logger.warn(message, error);
+      } catch {
+        // A diagnostic sink cannot make best-effort teardown observable to the
+        // caller in the one way this contract forbids: by replacing its result.
+      }
+    };
+    const timer = setTimeout(() => {
+      if (finished) return;
+      finished = true;
+      warn(
+        `[connecta] connector "${connectorId}" session termination was not ` +
+          `acknowledged within ${TERMINATE_SESSION_BUDGET_MS} ms; the ` +
+          "downstream may still finish the headers-only DELETE, otherwise " +
+          "the session will remain until its provider timeout.",
+      );
       resolve();
-    });
+    }, TERMINATE_SESSION_BUDGET_MS);
+    done.then(
+      () => {
+        if (finished) return;
+        finished = true;
+        clearTimeout(timer);
+        resolve();
+      },
+      (error) => {
+        // The rejection handler stays attached after the timer wins, so an
+        // abort or other late failure is consumed without a duplicate warning.
+        if (finished) return;
+        finished = true;
+        clearTimeout(timer);
+        warn(
+          `[connecta] connector "${connectorId}" session termination was ` +
+            "refused or failed; the downstream session may remain until its " +
+            "provider timeout.",
+          error,
+        );
+        resolve();
+      },
+    );
   });
 }
 
@@ -797,7 +834,7 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
       // 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);
+      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

package/src/credential-health.ts

@@ -21,7 +21,10 @@ import {
   storedCredentialShape,
 } from "./credentials.js";
 import type { CredentialVault } from "./credentials.js";
-import { closeConnectorScope } from "./connector-scope.js";
+import {
+  closeConnectorScope,
+  type DeferredWork,
+} from "./connector-scope.js";
 import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs, withTimeout } from "./timeout.js";
 import type {
   Connector,
@@ -536,6 +539,7 @@ export class CredentialHealthChecker {
   async check(
     baseUrl: string,
     opts: CredentialCheckOptions = {},
+    defer?: DeferredWork,
   ): Promise<CredentialCheckResult[]> {
     // An id naming no connector is reported, not dropped: a typo in a scheduled
     // check would otherwise return an empty list that looks exactly like a
@@ -546,7 +550,7 @@ export class CredentialHealthChecker {
     return mapWithConcurrency(targets, this.concurrency, (target) =>
       typeof target === "string"
         ? Promise.resolve({ connectorId: target, skipped: "not_found" as const })
-        : this.checkOne(target, baseUrl, opts),
+        : this.checkOne(target, baseUrl, opts, defer),
     );
   }
 
@@ -556,13 +560,16 @@ export class CredentialHealthChecker {
    * gate is armed BEFORE the sweep starts, so a burst of concurrent requests
    * produces one sweep.
    */
-  sweepIfDue(baseUrl: string): Promise<CredentialCheckResult[]> | undefined {
+  sweepIfDue(
+    baseUrl: string,
+    defer?: DeferredWork,
+  ): Promise<CredentialCheckResult[]> | undefined {
     if (!this.onRequest || this.sweeping) return undefined;
     const now = Date.now();
     if (now < this.nextSweepAt) return undefined;
     if (!this.hasCheckableConnectors()) return undefined;
     this.nextSweepAt = now + this.intervalMs;
-    const sweep = this.check(baseUrl).finally(() => {
+    const sweep = this.check(baseUrl, {}, defer).finally(() => {
       this.sweeping = undefined;
     });
     this.sweeping = sweep;
@@ -573,6 +580,7 @@ export class CredentialHealthChecker {
     connector: Connector,
     baseUrl: string,
     opts: CredentialCheckOptions,
+    defer?: DeferredWork,
   ): Promise<CredentialCheckResult> {
     const connectorId = connector.id;
     if (!isCheckableConnector(connector)) {
@@ -587,7 +595,12 @@ export class CredentialHealthChecker {
         ...(await this.recordOrNothing(connectorId)),
       };
     }
-    const run = this.runCheck(connector, baseUrl, opts.force ?? false);
+    const run = this.runCheck(
+      connector,
+      baseUrl,
+      opts.force ?? false,
+      defer,
+    );
     this.inFlight.set(connectorId, run);
     try {
       return await run;
@@ -607,6 +620,7 @@ export class CredentialHealthChecker {
     connector: Connector,
     baseUrl: string,
     force: boolean,
+    defer?: DeferredWork,
   ): Promise<CredentialCheckResult> {
     const connectorId = connector.id;
     const started = Date.now();
@@ -711,7 +725,7 @@ export class CredentialHealthChecker {
         });
       }
     } finally {
-      await closeConnectorScope(connector, ctx);
+      await closeConnectorScope(connector, ctx, defer);
     }
   }
 

package/src/execute.ts

@@ -8,10 +8,18 @@ import {
   discoverySearchLimit,
   errorResult,
   jsonResult,
-  serializeResultText,
   type ToolResult,
 } from "./meta-tools.js";
+import {
+  guardExecuteResultValue,
+  MAX_EXECUTE_LOG_CHARS,
+  truncateExecuteText,
+} from "./executor-result.js";
 import { classifyCallError, ConnectorCallError } from "./errors.js";
+import {
+  ExecutorAdmissionError,
+  isAdmittingExecutor,
+} from "./executor-admission.js";
 import { unwrapMcpResult } from "./mcp-result.js";
 import type { RegistryView } from "./registry.js";
 import type {
@@ -22,9 +30,6 @@ import type {
   ToolDef,
 } from "./types.js";
 
-/** ~6k tokens. Sandbox code should filter data down before returning. */
-const MAX_RESULT_CHARS = 24_000;
-const MAX_LOG_CHARS = 4_000;
 /** Keep one model-written program from amplifying into an unbounded fan-out. */
 export const EXECUTE_MAX_HOST_CALLS = 20;
 export const EXECUTE_MAX_BATCH_CALLS = 10;
@@ -136,6 +141,7 @@ export async function buildSandboxProviders(
     "connecta",
     "console",
     "__invoke",
+    "__namespace",
     "__call",
     "__log",
   ]);
@@ -143,9 +149,17 @@ export async function buildSandboxProviders(
   const catalogStarted = Date.now();
   const loaded = await Promise.allSettled(
     connectors.map((connector) =>
-      registry.getTools(connector.id, baseUrl, requestScope),
+      registry.getTools(connector.id, baseUrl, requestScope, {
+        signal: limits.signal,
+      }),
     ),
   );
+  if (limits.signal?.aborted) {
+    throw new ExecutorAdmissionError(
+      "executor_cancelled",
+      "Execution was cancelled during catalog construction.",
+    );
+  }
   const catalogs = new Map<string, ToolDef[]>();
   const callAddress = async (address: unknown, args: unknown) => {
     const resolved = registry.resolveAddress(String(address));
@@ -474,24 +488,6 @@ export async function buildSandboxProviders(
   return providers;
 }
 
-function truncate(text: string, max: number): string {
-  if (text.length <= max) return text;
-  return `${text.slice(0, max)}\n--- TRUNCATED (${text.length} chars total) — filter/map/slice data inside your code and return only what you need ---`;
-}
-
-function guardResultValue(value: unknown): unknown {
-  // Same serialization the call_tool guards measure, so a program returning
-  // nothing is rendered one way across every result path (issue #42).
-  const text = serializeResultText(value);
-  if (text.length <= MAX_RESULT_CHARS) return value;
-  return {
-    truncated: true,
-    preview: text.slice(0, MAX_RESULT_CHARS),
-    totalChars: text.length,
-    hint: "filter/map/slice data inside execute_code and return only what you need",
-  };
-}
-
 /** The execute_code handler. Exported for direct testing. */
 export function createExecuteTool(
   registry: RegistryView,
@@ -500,28 +496,69 @@ export function createExecuteTool(
   logger: Logger,
   activity?: ActivityRequestContext,
 ) {
-  return async ({ code }: { code: string }): Promise<ToolResult> => {
+  return async (
+    { code }: { code: string },
+    options: { signal?: AbortSignal } = {},
+  ): Promise<ToolResult> => {
     const controller = new AbortController();
-    const providers = await buildSandboxProviders(
-      registry,
-      baseUrl,
-      logger,
-      activity,
-      { signal: controller.signal },
-    );
+    const forwardAbort = () => controller.abort(options.signal?.reason);
+    if (options.signal?.aborted) forwardAbort();
+    else {
+      options.signal?.addEventListener("abort", forwardAbort, { once: true });
+    }
+    let lease;
     let outcome;
     try {
-      outcome = await executor.execute(code, providers);
+      // Admission comes before provider construction: queued calls retain no
+      // catalogs, request scopes, or one-closure-per-tool provider arrays.
+      if (isAdmittingExecutor(executor)) {
+        lease = await executor.acquire({ signal: controller.signal });
+      }
+      const providers = await buildSandboxProviders(
+        registry,
+        baseUrl,
+        logger,
+        activity,
+        { signal: controller.signal },
+      );
+      if (controller.signal.aborted) {
+        throw new ExecutorAdmissionError(
+          "executor_cancelled",
+          "Execution was cancelled during sandbox setup.",
+        );
+      }
+      outcome = lease
+        ? await lease.execute(code, providers)
+        : await executor.execute(code, providers);
     } catch (err) {
+      if (err instanceof ExecutorAdmissionError) {
+        const result = jsonResult({
+          error: {
+            code: err.code,
+            message: err.message,
+            retryable: err.retryable,
+            ...(err.retryAfterMs !== undefined
+              ? { retryAfterMs: err.retryAfterMs }
+              : {}),
+          },
+        });
+        result.isError = true;
+        return result;
+      }
       return errorResult(`Executor failed: ${msg(err)}`);
     } finally {
       // A sandbox timeout or early return must also release any outstanding
       // host waits and signal cooperative connectors to stop their work.
       controller.abort();
+      lease?.release();
+      options.signal?.removeEventListener("abort", forwardAbort);
     }
     const logs =
       outcome.logs && outcome.logs.length > 0
-        ? truncate(outcome.logs.join("\n"), MAX_LOG_CHARS)
+        ? truncateExecuteText(
+            outcome.logs.join("\n"),
+            MAX_EXECUTE_LOG_CHARS,
+          )
         : undefined;
     if (outcome.error) {
       return errorResult(
@@ -533,7 +570,7 @@ export function createExecuteTool(
     // error path so captured logs survive instead of a raw SDK 500.
     let result: unknown;
     try {
-      result = guardResultValue(outcome.result);
+      result = guardExecuteResultValue(outcome.result);
     } catch (err) {
       return errorResult(
         `Error: result is not JSON-serializable: ${msg(err)}${logs ? `\n\nLogs:\n${logs}` : ""}`,
@@ -568,6 +605,7 @@ export function registerExecuteTool(
     executor: Executor;
     logger: Logger;
     activity?: ActivityRequestContext;
+    requestSignal?: AbortSignal;
   },
 ): void {
   const handler = createExecuteTool(
@@ -594,6 +632,26 @@ export function registerExecuteTool(
         openWorldHint: true,
       },
     },
-    async (args) => handler(args as { code: string }),
+    async (args, extra) => {
+      const controller = new AbortController();
+      const signals = [extra.signal, ctx.requestSignal].filter(
+        (signal): signal is AbortSignal => signal !== undefined,
+      );
+      const forwarders = signals.map((signal) => {
+        const forward = () => controller.abort(signal.reason);
+        if (signal.aborted) forward();
+        else signal.addEventListener("abort", forward, { once: true });
+        return { signal, forward };
+      });
+      try {
+        return await handler(args as { code: string }, {
+          signal: controller.signal,
+        });
+      } finally {
+        for (const { signal, forward } of forwarders) {
+          signal.removeEventListener("abort", forward);
+        }
+      }
+    },
   );
 }