@zackbart/connecta 0.6.0 → 0.7.0

package/src/index.ts

@@ -1,4 +1,8 @@
-import { CredentialVault } from "./credentials.js";
+import {
+  CredentialVault,
+  credentialTestRule,
+  describeCredentialTestMismatch,
+} from "./credentials.js";
 import { Registry } from "./registry.js";
 import { createFetchHandler } from "./server.js";
 import { droppedBrandingUrls, droppedUiAuthUrls } from "./ui.js";
@@ -24,6 +28,84 @@ import type {
   Logger,
 } from "./types.js";
 
+/** Payload-free activity storage and operator-read policy. */
+export interface ConnectaActivityConfig {
+  /**
+   * Privacy-minimal downstream tool activity storage. Writes are best-effort
+   * and never change tool results. Implement `list` to enable the Activity UI.
+   */
+  store: ActivityStore;
+  /**
+   * Optional authorization gate for the Activity read API. MCP authentication
+   * is still required first. Omit to admit every authenticated actor.
+   */
+  readGate?: ActivityReadGate;
+  /** Stable deployment label included in activity events, e.g. "production". */
+  deploymentId?: string;
+}
+
+/** Operator-vault encryption and proactive credential-health tuning. */
+export interface ConnectaCredentialsConfig {
+  /**
+   * Base64-encoded 32-byte AES key for credentials managed on /credentials.
+   * Keep this in the runtime's secret store, never in KV or source control.
+   */
+  encryptionKey?: string;
+  /**
+   * Tuning for proactive credential liveness checks that let a connector's
+   * status flip to `auth_required` before an agent's call fails. Defaults: one
+   * check per connector per 15 minutes, four in flight, 30 seconds each,
+   * triggered opportunistically by inbound authenticated traffic.
+   *
+   * Optional even without an encryption key because downstream OAuth connectors
+   * manage their own grants. `Connecta.checkCredentials()` runs the same checks
+   * on demand for a Worker cron trigger or Node interval.
+   */
+  health?: CredentialHealthConfig;
+}
+
+/** Tool-catalog caching, persistence, stale fallback, and probe deadlines. */
+export interface ConnectaDiscoveryConfig {
+  /** Tool-list cache TTL (seconds). Default 300. */
+  catalogTtlSeconds?: number;
+  /**
+   * Persist serializable remote tool catalogs in storage so cold isolates can
+   * discover tools without a downstream handshake. Default true.
+   */
+  persistCatalog?: boolean;
+  /**
+   * How long an expired persisted catalog remains available as a fallback
+   * when a live refresh fails. Default 3600 seconds.
+   */
+  staleCatalogSeconds?: number;
+  /**
+   * Deadline (ms) for each downstream probe/catalog call fanned out by
+   * `list_connectors`, `search_tools`, and `describe_tools`. Defaults to
+   * 30_000. A timed-out connector degrades independently; this does not apply
+   * to tool calls or currently abort the underlying fetch.
+   */
+  probeTimeoutMs?: number;
+}
+
+/** Deployment-wide call deadlines and inline-result paging threshold. */
+export interface ConnectaCallsConfig {
+  /**
+   * Deadline (ms) for `call_tool`/`batch_call` calls that pass no `timeoutMs`.
+   * An explicit per-call value wins. Opt-in: unset by default, so existing
+   * long-running calls gain no surprise deadline.
+   *
+   * This bounds one attempt, not all retries. `execute_code` host calls are
+   * unaffected because they already carry their own bound.
+   */
+  defaultTimeoutMs?: number;
+  /**
+   * Max inline result size (bytes) before truncation and `get_result` paging.
+   * Must be a finite whole number >= 1; invalid values warn and fall back to
+   * 50_000. Connectors may override it individually.
+   */
+  maxResultBytes?: number;
+}
+
 export interface ConnectaConfig {
   connectors: Connector[];
   /**
@@ -58,18 +140,6 @@ export interface ConnectaConfig {
    * address, or an address naming no tool on an in-code connector all throw.
    */
   toolkits?: ToolkitConfig;
-  /**
-   * Privacy-minimal downstream tool activity storage. Writes are best-effort
-   * and never change tool results. Implement `list` to enable the Activity UI.
-   */
-  activity?: ActivityStore;
-  /**
-   * Optional authorization gate for the Activity read API. MCP authentication
-   * is still required first. Omit to admit every authenticated actor.
-   */
-  activityReadGate?: ActivityReadGate;
-  /** Stable deployment label included in activity events, e.g. "production". */
-  activityDeploymentId?: string;
   /** Inbound auth adapters. Includes bearerToken(...); omit for open (dev). */
   auth?: InboundAuth | InboundAuth[];
   /** KVStorage impl. Defaults to memoryStorage(). */
@@ -79,78 +149,17 @@ export interface ConnectaConfig {
    * HTTPS URL also redirects matching inbound HTTP requests to HTTPS.
    */
   publicUrl?: string;
-  /**
-   * Base64-encoded 32-byte AES key for connector credentials managed in /ui.
-   * Keep this in the runtime's secret store, never in KV or source control.
-   */
-  credentialEncryptionKey?: string;
+  /** Payload-free tool activity storage and operator-read policy. */
+  activity?: ConnectaActivityConfig;
+  /** Operator credential vault and proactive liveness-check settings. */
+  credentials?: ConnectaCredentialsConfig;
+  /** Tool-catalog caching, persistence, stale fallback, and probe deadlines. */
+  discovery?: ConnectaDiscoveryConfig;
+  /** Deployment-wide call deadlines and result paging threshold. */
+  calls?: ConnectaCallsConfig;
   /** Optional browser UI and OAuth result-page labels. */
   branding?: ConnectaBranding;
   logger?: Logger;
-  /** Tool-list cache TTL (seconds). Default 300. */
-  toolCacheTtlSeconds?: number;
-  /**
-   * Persist serializable remote tool catalogs in storage so cold isolates can
-   * discover tools without a downstream handshake. Default true.
-   */
-  persistToolCatalog?: boolean;
-  /**
-   * How long an expired persisted catalog remains available as a fallback
-   * when a live refresh fails. Default 3600 seconds.
-   */
-  toolCatalogStaleSeconds?: number;
-  /**
-   * Max inline result size (bytes) before call_tool/batch_call truncate and
-   * stash the full text for get_result paging. Must be a whole number of bytes
-   * >= 1; anything else (0, negative, fractional, NaN, Infinity) warns at
-   * startup and falls back to the default 50_000.
-   */
-  maxResultBytes?: number;
-  /**
-   * Deadline (ms) applied to call_tool/batch_call calls that pass no
-   * `timeoutMs`, giving the connector both a budget (`ctx.timeoutMs`) and a
-   * cancellation signal (`ctx.signal`). An explicit per-call `timeoutMs` always
-   * wins. **Opt-in — undefined by default**, because switching it on globally
-   * would put a deadline on every call in an existing deployment and the
-   * failure mode is a working long-running call starting to time out.
-   * `execute_code` host calls are unaffected; they already carry a 15 s bound.
-   *
-   * Bounds a single attempt, not the whole call — the same as an explicit
-   * `timeoutMs` has always done. A call that also passes `maxRetries` can
-   * therefore run to roughly `(maxRetries + 1)` times this value plus backoff.
-   * `maxRetries` defaults to 0, so this is the total for every call that does
-   * not explicitly ask to retry.
-   */
-  defaultToolTimeoutMs?: number;
-  /**
-   * Deadline (ms) applied to each individual downstream probe/catalog call that
-   * the discovery meta-tools fan out — `list_connectors` (with `probe`),
-   * `search_tools`, and `describe_tools` — so a single hung connector can no
-   * longer stall the whole meta-tool call. **Defaults to a generous 30_000**,
-   * chosen to trip only on a pathological hang, not on a realistically slow
-   * probe, so having it on by default will not break existing deployments.
-   * Bounds one downstream call, not the whole fan-out: a connector that outruns
-   * it degrades to an unavailable/errored entry while the rest are unaffected.
-   *
-   * Does NOT apply to `call_tool`/`batch_call` — those carry their own budget
-   * via `defaultToolTimeoutMs` or a per-call `timeoutMs`. Note this bounds the
-   * caller-facing wait only; the underlying fetch is not currently aborted, so
-   * real cancellation of the downstream request is a deferred follow-up.
-   */
-  probeTimeoutMs?: number;
-  /**
-   * Tuning for the proactive credential liveness checks (issue #24) that let a
-   * connector's status flip to `auth_required` *before* an agent's call fails.
-   * Defaults are safe to leave alone: at most one check per connector per 15
-   * minutes, four in flight, 30 s each, triggered opportunistically by inbound
-   * authenticated traffic. Only connectors holding a credential connecta stores
-   * — an operator-managed `credential`, or a downstream-OAuth grant — are ever
-   * checked, and a check never calls a downstream tool.
-   *
-   * `Connecta.checkCredentials()` is the same check on demand, for a Worker cron
-   * trigger or a Node interval.
-   */
-  credentialHealth?: CredentialHealthConfig;
   serverInfo?: {
     name?: string;
     version?: string;
@@ -189,7 +198,7 @@ export interface Connecta {
    *
    * Returns one outcome per connector considered, including why a connector was
    * skipped (`fresh` is the rate limit: a connector checked less than
-   * `credentialHealth.intervalSeconds` ago is not re-checked unless `force`).
+   * `credentials.health.intervalSeconds` ago is not re-checked unless `force`).
    * Never rejects on a connector failure — a broken connector becomes an `error`
    * verdict. Needs a base URL for connector contexts: `publicUrl` supplies it,
    * or pass one.
@@ -219,10 +228,64 @@ function normalizeAuth(auth: ConnectaConfig["auth"]): InboundAuth[] {
   });
 }
 
+const LEGACY_CONFIG_MIGRATIONS = [
+  ["activityReadGate", "activity.readGate"],
+  ["activityDeploymentId", "activity.deploymentId"],
+  ["credentialEncryptionKey", "credentials.encryptionKey"],
+  ["credentialHealth", "credentials.health"],
+  ["toolCacheTtlSeconds", "discovery.catalogTtlSeconds"],
+  ["persistToolCatalog", "discovery.persistCatalog"],
+  ["toolCatalogStaleSeconds", "discovery.staleCatalogSeconds"],
+  ["probeTimeoutMs", "discovery.probeTimeoutMs"],
+  ["defaultToolTimeoutMs", "calls.defaultTimeoutMs"],
+  ["maxResultBytes", "calls.maxResultBytes"],
+] as const;
+
+const hasOwn = (value: object, key: PropertyKey): boolean =>
+  Object.prototype.hasOwnProperty.call(value, key);
+
+/**
+ * Fail closed at the public boundary: a JavaScript caller on the v0.6 shape
+ * must receive one complete migration error, never silently lose an option to
+ * a default. This runs before createConnecta reads any other config field.
+ */
+function assertNoLegacyConfig(config: ConnectaConfig): void {
+  const candidate = config as unknown as Record<PropertyKey, unknown>;
+  const found: Array<readonly [string, string]> = [];
+  if (hasOwn(candidate, "activity")) {
+    const activity = candidate.activity;
+    const isObject =
+      typeof activity === "object" && activity !== null;
+    // A valid v0.6 ActivityStore can itself own a backend field named `store`.
+    // Its required `record` method (including a prototype method) therefore
+    // takes precedence over the otherwise-new wrapper shape.
+    const hasLegacyRecord =
+      isObject &&
+      typeof (activity as { record?: unknown }).record === "function";
+    if (
+      activity !== undefined &&
+      (!isObject ||
+        hasLegacyRecord ||
+        !hasOwn(activity, "store"))
+    ) {
+      found.push(["activity", "activity.store"]);
+    }
+  }
+  for (const migration of LEGACY_CONFIG_MIGRATIONS) {
+    if (hasOwn(candidate, migration[0])) found.push(migration);
+  }
+  if (found.length === 0) return;
+  throw new Error(
+    "Unsupported v0.6.x ConnectaConfig options. Migrate each path for v0.7.0:\n" +
+      found.map(([oldPath, newPath]) => `- ${oldPath} -> ${newPath}`).join("\n"),
+  );
+}
+
 /**
  * One-time construction warnings for deployment shapes that run fine but are
  * usually unintended. Warning-only — never throws and never changes behavior;
- * each condition emits at most one `logger.warn`. Iterates connectors once.
+ * each deployment-wide condition emits at most one `logger.warn`, and each
+ * per-connector condition at most one per connector it names.
  */
 function warnInsecureConfig(
   config: ConnectaConfig,
@@ -328,33 +391,57 @@ function warnInsecureConfig(
     );
   }
 
-  // /ui renders exactly one provider's browser sign-in config — the first that
-  // offers one, which is the same `find` the /ui route performs — and that
-  // provider's frontendApiUrl becomes the loader's `<script src>`. Gate-or-drop
-  // like a branding href: rendering omits the loader for a rejected value and
-  // the dashboard then reports that Clerk could not load, a confusing symptom
-  // without this line naming the cause. Checking only the rendered provider
-  // keeps the claim true — a later provider's uiAuth never reaches the page, so
-  // there is nothing there to warn about.
+  // Operator shells render exactly one provider's browser sign-in config — the
+  // first that offers one, matching the server route's `find` — and that
+  // provider's URLs reach the browser: frontendApiUrl as the loader's
+  // `<script src>`, signInUrl/signUpUrl as the addresses ClerkJS navigates to.
+  // Gate-or-drop like a branding href: rendering drops a rejected value and the
+  // operator page then reports that Clerk could not load or quietly signs in
+  // through Clerk's defaults — both confusing symptoms without this line naming
+  // the cause. Checking only the rendered provider keeps the claim true — a
+  // later provider's uiAuth never reaches the page, so there is nothing there
+  // to warn about.
   const uiAuthProvider = inboundAuth.find((provider) => provider.uiAuth);
   const droppedUiAuth = droppedUiAuthUrls(uiAuthProvider?.uiAuth);
   if (uiAuthProvider && droppedUiAuth.length > 0) {
     logger.warn(
       `[connecta] inbound auth provider "${uiAuthProvider.kind}" had ` +
-        `${droppedUiAuth.join(", ")} dropped: the browser sign-in loader is ` +
-        "fetched from this origin, so it must be an absolute https URL. /ui " +
-        "renders without the loader and cannot start a sign-in.",
+        `${droppedUiAuth.join(", ")} dropped: every uiAuth URL reaches the ` +
+        "browser — as the sign-in loader's source, or as a place Clerk sends " +
+        "the operator — so each must be an absolute https URL. A dropped " +
+        "value reaches no part of the page: without frontendApiUrl the operator shell renders " +
+        "no loader and cannot start a sign-in, and without signInUrl/signUpUrl " +
+        "it signs in through Clerk's defaults.",
+    );
+  }
+
+  // A credential test hook that cannot test the declared credential shape.
+  // The shape picks the hook (see `credentialTestRule`) and the other one is
+  // never substituted, so the connector is simply not testable: /credentials offers no
+  // Test action and the route answers 400. Without this line the only way to
+  // discover the mistake is to click a button that isn't there.
+  for (const connector of config.connectors) {
+    const { mismatch } = credentialTestRule(connector);
+    if (!mismatch) continue;
+    logger.warn(
+      `[connecta] connector "${connector.id}" cannot test its credential: ` +
+        `${describeCredentialTestMismatch(mismatch)}. /credentials offers no Test ` +
+        `action and POST /ui/credentials/${connector.id}/test answers 400 ` +
+        "until the matching hook is implemented.",
     );
   }
 
-  // OAuth connectors whose callback performs no state/CSRF check: the public
-  // /oauth/callback/<id> route would exchange any delivered code.
+  // OAuth connectors whose callback cannot perform a state/CSRF check. The
+  // public route refuses every callback for these connectors rather than hand
+  // an unverified code to finishAuth, so this warning explains why auth cannot
+  // complete instead of describing a vulnerability the server permits.
   for (const connector of oauthConnectors) {
     if (!connector.verifyState) {
       logger.warn(
         `[connecta] connector "${connector.id}" has an OAuth callback with no ` +
-          `state/CSRF check: /oauth/callback/${connector.id} will exchange any ` +
-          "delivered code. Implement `verifyState` (the shipped remoteMcp " +
+          `state/CSRF check: /oauth/callback/${connector.id} refuses every ` +
+          "callback rather than exchange an unverified code. Implement " +
+          "`verifyState` to complete authorization (the shipped remoteMcp " +
           "connector already does).",
       );
     }
@@ -362,26 +449,28 @@ function warnInsecureConfig(
 }
 
 export function createConnecta(config: ConnectaConfig): Connecta {
+  assertNoLegacyConfig(config);
   const storage = config.storage ?? memoryStorage();
   const logger = config.logger ?? defaultLogger();
   const credentialConnectors = config.connectors.filter((c) => c.credential);
-  if (credentialConnectors.length > 0 && !config.credentialEncryptionKey) {
+  const encryptionKey = config.credentials?.encryptionKey;
+  if (credentialConnectors.length > 0 && !encryptionKey) {
     throw new Error(
-      `credentialEncryptionKey is required by connector credentials: ${credentialConnectors.map((c) => c.id).join(", ")}`,
+      `credentials.encryptionKey is required by connector credentials: ${credentialConnectors.map((c) => c.id).join(", ")}`,
     );
   }
-  const credentialVault = config.credentialEncryptionKey
-    ? new CredentialVault(storage, config.credentialEncryptionKey)
+  const credentialVault = encryptionKey
+    ? new CredentialVault(storage, encryptionKey)
     : undefined;
   const registry = new Registry(config.connectors, {
     storage,
     logger,
     credentialVault,
-    toolCacheTtlSeconds: config.toolCacheTtlSeconds,
-    persistToolCatalog: config.persistToolCatalog,
-    toolCatalogStaleSeconds: config.toolCatalogStaleSeconds,
-    maxResultBytes: config.maxResultBytes,
-    credentialHealth: config.credentialHealth,
+    toolCacheTtlSeconds: config.discovery?.catalogTtlSeconds,
+    persistToolCatalog: config.discovery?.persistCatalog,
+    toolCatalogStaleSeconds: config.discovery?.staleCatalogSeconds,
+    maxResultBytes: config.calls?.maxResultBytes,
+    credentialHealth: config.credentials?.health,
   });
   // Throws on every structural mistake it can see (see resolveToolkits): a
   // typo must not become a scope the operator never wrote. Note this is about
@@ -404,12 +493,12 @@ export function createConnecta(config: ConnectaConfig): Connecta {
       version: config.serverInfo?.version ?? CONNECTA_VERSION,
     },
     logger,
-    activity: config.activity,
-    activityReadGate: config.activityReadGate,
-    activityDeploymentId: config.activityDeploymentId,
+    activity: config.activity?.store,
+    activityReadGate: config.activity?.readGate,
+    activityDeploymentId: config.activity?.deploymentId,
     executor: config.executor,
-    defaultToolTimeoutMs: config.defaultToolTimeoutMs,
-    probeTimeoutMs: config.probeTimeoutMs,
+    defaultToolTimeoutMs: config.calls?.defaultTimeoutMs,
+    probeTimeoutMs: config.discovery?.probeTimeoutMs,
     credentialVault,
     deploymentInfo: config.deploymentInfo,
     branding: config.branding,

package/src/meta-tools.ts

@@ -6,6 +6,7 @@ import {
   type ActivityCallSource,
   type ActivityRequestContext,
 } from "./activity.js";
+import { closeConnectorScope } from "./connector-scope.js";
 import { unwrapMcpResult } from "./mcp-result.js";
 import {
   classifyCallError,
@@ -458,9 +459,9 @@ export interface SkillArgs {
  * optional tenth tool, is registered separately by registerExecuteTool.)
  *
  * The deployment-wide result-size cap is read off the registry view rather than
- * passed in: `ConnectaConfig.maxResultBytes` and the per-connector override are
- * the only places a cap is set, so there is one answer to where a deployment
- * sets it (issue #44).
+ * passed in: `ConnectaConfig.calls.maxResultBytes` and the per-connector
+ * override are the only places a cap is set, so there is one answer to where a
+ * deployment sets it (issue #44).
  */
 export function createMetaTools(
   registry: RegistryView,
@@ -788,8 +789,12 @@ export function createMetaTools(
 
     async listConnectors(args: ListArgs = {}): Promise<ToolResult> {
       const probe = args.probe ?? true;
+      // Live inventory owns a short-lived scope separate from the request's
+      // call scope. Closing it cannot defeat call_tool/batch/execute_code reuse.
+      const connectors = registry.listConnectors();
+      const scope = probe ? {} : requestScope;
       const out = await Promise.all(
-        registry.listConnectors().map(async (c) => {
+        connectors.map(async (c) => {
           const statusStarted = Date.now();
           const observed = registry.healthFor(c.id);
           const verdict = await registry.credentialHealthFor(c.id);
@@ -799,7 +804,7 @@ export function createMetaTools(
           if (probe) {
             try {
               status = await withTimeout(
-                registry.statusFor(c.id, baseUrl, requestScope),
+                registry.statusFor(c.id, baseUrl, scope),
                 probeTimeoutMs,
                 `list_connectors probe of "${c.id}"`,
               );
@@ -886,7 +891,7 @@ export function createMetaTools(
           if (probe && status.state === "ok") {
             try {
               tools = await withTimeout(
-                registry.refreshTools(c.id, baseUrl, requestScope),
+                registry.refreshTools(c.id, baseUrl, scope),
                 probeTimeoutMs,
                 `list_connectors catalog refresh of "${c.id}"`,
               );
@@ -918,7 +923,17 @@ export function createMetaTools(
             ...(status.message ? { message: status.message } : {}),
           };
         }),
-      );
+      ).finally(async () => {
+        if (!probe) return;
+        await Promise.all(
+          connectors.map((connector) =>
+            closeConnectorScope(
+              connector,
+              registry.contextFor(connector.id, baseUrl, scope),
+            ),
+          ),
+        );
+      });
       return jsonResult({ connectors: out });
     },
 

package/src/registry.ts

@@ -33,7 +33,7 @@ export const MIN_MAX_RESULT_BYTES = 1;
 /**
  * The one definition of a usable `maxResultBytes`: a finite whole number of at
  * least {@link MIN_MAX_RESULT_BYTES} bytes. Shared by all three intake points
- * — deployment config, the per-connector override, and `get_result`'s
+ * — `calls.maxResultBytes`, the per-connector override, and `get_result`'s
  * `maxBytes` argument — so a value that is valid at one is valid at all.
  *
  * Everything else is rejected rather than coerced, because each rejected shape
@@ -286,7 +286,7 @@ export class Registry implements RegistryView {
   ): void {
     if (configured !== undefined && !isValidMaxResultBytes(configured)) {
       logger.warn(
-        `[connecta] maxResultBytes ${configured} is not a whole number of ` +
+        `[connecta] calls.maxResultBytes ${configured} is not a whole number of ` +
           `bytes >= ${MIN_MAX_RESULT_BYTES}: it would serve an empty, ` +
           "oversized, or unguarded result instead of truncating. Using the " +
           `default ${DEFAULT_MAX_RESULT_BYTES} instead.`,
@@ -612,7 +612,8 @@ export class Registry implements RegistryView {
 
   /**
    * Drop a connector's liveness verdict, because its credential just changed
-   * under us (OAuth callback completed, credential stored or removed in /ui). A
+   * under us (OAuth callback completed, credential stored or removed on
+   * /credentials). A
    * stale `auth_required` must not outlive the re-authorization that fixed it —
    * that is the difference between recovery working and needing a restart.
    */