@zackbart/connecta 0.6.1 → 0.7.1

package/src/credential-health.ts

@@ -5,7 +5,7 @@
 // something *observed* a failure, so an expired or revoked token surfaced
 // mid-task as a failed agent call. A liveness check asks the connector whether
 // the credential it holds still works, records the verdict, and lets the cached
-// status surfaces (`list_connectors({ probe: false })`, `/ui`) report
+// status surfaces (`list_connectors({ probe: false })`, operator pages) report
 // `auth_required` BEFORE a real call discovers it.
 //
 // Runtime-agnostic on purpose: nothing here schedules itself. The core exposes a
@@ -15,8 +15,12 @@
 // There is no background daemon and no long-lived timer, so Workers and Node run
 // the same code.
 
-import { credentialTestRule } from "./credentials.js";
+import {
+  credentialTestRule,
+  storedCredentialShape,
+} from "./credentials.js";
 import type { CredentialVault } from "./credentials.js";
+import { closeConnectorScope } from "./connector-scope.js";
 import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs, withTimeout } from "./timeout.js";
 import type {
   Connector,
@@ -328,7 +332,10 @@ export interface CredentialCheckOptions {
   force?: boolean;
   /** Restrict the sweep to these connector ids. Default: every connector. */
   ids?: string[];
-  /** Request-scope identity to reuse a connector's per-request resources. */
+  /**
+   * Internal scope identity supplied by an existing owner. When omitted, the
+   * check creates and ends its own probe scope.
+   */
   requestScope?: object;
 }
 
@@ -339,14 +346,14 @@ export interface CredentialCheckOptions {
  * Deliberately narrow. `listTools`/`callTool` are NOT liveness probes here: a
  * tool call may mutate downstream state, and the catalog path is already covered
  * by the existing probe. So a connector is checkable only through the two hooks
- * that exist to answer exactly this question — `testCredential(s)` (what /ui's
+ * that exist to answer exactly this question — `testCredential(s)` (what the
  * Test button runs) and `status()` — and only when it has a credential of ours
  * to be asked about: an operator-managed `credential`, or a stored downstream
  * grant it reports via `hasStoredCredential`. A static-token connector stores
  * nothing here and is never probed on a timer.
  *
  * Whether a test hook counts is `credentialTestRule`'s call, not this function's
- * — the same rule /ui's Test button and the credential API read (issue #55), so
+ * Credentials Test button and the credential API read (issue #55), so
  * a credential the operator cannot test by hand is not one a sweep tests behind
  * their back. A connector whose only hook cannot test its declared shape is
  * checkable only if it also implements `status()`.
@@ -367,7 +374,7 @@ export function isCheckableConnector(connector: Connector): boolean {
  *
  * `isCheckableConnector` answers the static question ("could this connector be
  * asked at all"); this answers it against the vault. The hook itself is picked
- * by `credentialTestRule` (src/credentials.ts, issue #55), the one rule /ui's
+ * by `credentialTestRule` (src/credentials.ts, issue #55), the one rule the UI's
  * `testable` flag and `POST /ui/credentials/<id>/test` also read: named
  * `credential.fields` are tested as a set by `testCredentials`, a single-value
  * `credential` by `testCredential` on the vault's reserved `value` field, and
@@ -384,15 +391,21 @@ function testHookFor(
   connector: Connector,
   values: ConnectorCredentialValues | null,
 ): ((ctx: ConnectorContext) => Promise<CredentialTestResult>) | undefined {
-  if (!values) return undefined;
+  if (
+    !connector.credential ||
+    storedCredentialShape(connector.credential, values).state !== "valid"
+  ) {
+    return undefined;
+  }
+  const storedValues = values!;
   const { mode } = credentialTestRule(connector);
   if (mode === "multiple") {
-    return (ctx) => connector.testCredentials!(values, ctx);
+    return (ctx) => connector.testCredentials!(storedValues, ctx);
   }
   // A single-value shape with nothing under the reserved field is still nothing
   // to test, so the stored value gets the last word even when the rule fits.
-  if (mode === "single" && typeof values.value === "string") {
-    return (ctx) => connector.testCredential!(values.value, ctx);
+  if (mode === "single" && typeof storedValues.value === "string") {
+    return (ctx) => connector.testCredential!(storedValues.value, ctx);
   }
   return undefined;
 }
@@ -433,8 +446,8 @@ async function mapWithConcurrency<T, R>(
  *    triggered sweep per interval per isolate, and never two at once, so a burst
  *    of requests costs one sweep, not one per request.
  * 4. **Deadline + fan-out bound** — each check is bounded by `timeoutMs` and at
- *    most `concurrency` run together (the same shape as the `probeTimeoutMs`
- *    bound on the discovery fan-out, issue #19).
+ *    most `concurrency` run together (the same shape as the
+ *    `discovery.probeTimeoutMs` bound on the discovery fan-out, issue #19).
  */
 export class CredentialHealthChecker {
   private readonly store: CredentialHealthStore;
@@ -573,16 +586,12 @@ export class CredentialHealthChecker {
         ...(await this.recordOrNothing(connectorId)),
       };
     }
-    if (!opts.force) {
-      const current = await this.store.get(connectorId);
-      if (
-        current &&
-        Date.now() - Date.parse(current.checkedAt) < this.intervalMs
-      ) {
-        return { connectorId, skipped: "fresh", record: current };
-      }
-    }
-    const run = this.runCheck(connector, baseUrl, opts.requestScope);
+    const run = this.runCheck(
+      connector,
+      baseUrl,
+      opts.force ?? false,
+      opts.requestScope,
+    );
     this.inFlight.set(connectorId, run);
     try {
       return await run;
@@ -601,56 +610,110 @@ export class CredentialHealthChecker {
   private async runCheck(
     connector: Connector,
     baseUrl: string,
+    force: boolean,
     requestScope?: object,
   ): Promise<CredentialCheckResult> {
     const connectorId = connector.id;
     const started = Date.now();
-    // Captured BEFORE anything downstream happens: everything after this point
-    // is a window in which the operator may replace the very credential being
-    // judged, and `settle` fences the write against exactly that.
+    // Captured BEFORE anything downstream happens — including the vault read
+    // below: everything after this point is a window in which the operator may
+    // replace the very credential being judged, and `settle` fences the write
+    // against exactly that. It cannot move later to save a read on the fresh
+    // path; a generation sampled AFTER the values would miss a `clear` that
+    // landed between the two and let a verdict about the replaced credential
+    // through the fence.
     const generation = await this.store.generation(connectorId);
-    const ctx = this.deps.contextFor(connectorId, baseUrl, requestScope);
     let values: ConnectorCredentialValues | null = null;
+    let credentialReadError: unknown;
     if (connector.credential && this.deps.credentialVault) {
       try {
         values = await this.deps.credentialVault.getAll(connectorId);
       } catch (err) {
-        // A stored credential that cannot be decrypted (rotated key, corrupt
-        // envelope) is exactly the kind of dead credential this feature exists
-        // to surface early, so it is a verdict rather than a skip.
+        credentialReadError = err;
+      }
+      const shape = storedCredentialShape(connector.credential, values);
+      if (shape.state === "mismatch") {
+        // Drift is a persistent operator-error state, not an event: left
+        // outside the freshness gate it would spend a write on every sweep in
+        // every isolate, forever, against exactly the deployments this feature
+        // is meant to help (and on Cloudflare KV those writes are metered).
+        // Once the SAME drift verdict is already stored and still fresh, this
+        // is the rate limit doing its job, same as a fresh `ok`. A stored
+        // verdict that says anything else — a pre-redeploy `ok`, a different
+        // message — is still replaced immediately, which is the whole point of
+        // checking the shape before the gate.
+        if (!force) {
+          const current = await this.store.get(connectorId);
+          if (
+            current &&
+            current.state === "error" &&
+            current.message === shape.message &&
+            Date.now() - Date.parse(current.checkedAt) < this.intervalMs
+          ) {
+            return { connectorId, skipped: "fresh", record: current };
+          }
+        }
         return this.settle(connectorId, started, generation, {
-          state: "auth_required",
+          state: "error",
           checkedAt: new Date().toISOString(),
-          message: msg(err),
+          message: shape.message,
         });
       }
     }
-    const stored = connector.hasStoredCredential
-      ? await connector
-          .hasStoredCredential(ctx)
-          .catch(() => values !== null)
-      : values !== null;
-    if (!stored) return { connectorId, skipped: "no_credential" };
-    if (!this.canAsk(connector, values)) {
-      return { connectorId, skipped: "not_checkable" };
+    // Shape drift is checked before this shortcut so an old, still-fresh `ok`
+    // cannot survive a redeploy that changed the credential declaration.
+    if (!force) {
+      const current = await this.store.get(connectorId);
+      if (
+        current &&
+        Date.now() - Date.parse(current.checkedAt) < this.intervalMs
+      ) {
+        return { connectorId, skipped: "fresh", record: current };
+      }
     }
-
+    const ownsScope = requestScope === undefined;
+    const scope = requestScope ?? {};
+    const ctx = this.deps.contextFor(connectorId, baseUrl, scope);
     try {
-      const verdict = await withTimeout(
-        this.probe(connector, ctx, values),
-        this.timeoutMs,
-        `credential check of "${connectorId}"`,
-      );
-      return await this.settle(connectorId, started, generation, {
-        ...verdict,
-        checkedAt: new Date().toISOString(),
-      });
-    } catch (err) {
-      return await this.settle(connectorId, started, generation, {
-        state: "error",
-        checkedAt: new Date().toISOString(),
-        message: msg(err),
-      });
+      if (credentialReadError) {
+        // A stored credential that cannot be decrypted (rotated key, corrupt
+        // envelope) is exactly the kind of dead credential this feature
+        // exists to surface early, so it is a verdict rather than a skip.
+        return this.settle(connectorId, started, generation, {
+          state: "auth_required",
+          checkedAt: new Date().toISOString(),
+          message: msg(credentialReadError),
+        });
+      }
+      const stored = connector.hasStoredCredential
+        ? await connector
+            .hasStoredCredential(ctx)
+            .catch(() => values !== null)
+        : values !== null;
+      if (!stored) return { connectorId, skipped: "no_credential" };
+      if (!this.canAsk(connector, values)) {
+        return { connectorId, skipped: "not_checkable" };
+      }
+
+      try {
+        const verdict = await withTimeout(
+          this.probe(connector, ctx, values),
+          this.timeoutMs,
+          `credential check of "${connectorId}"`,
+        );
+        return await this.settle(connectorId, started, generation, {
+          ...verdict,
+          checkedAt: new Date().toISOString(),
+        });
+      } catch (err) {
+        return await this.settle(connectorId, started, generation, {
+          state: "error",
+          checkedAt: new Date().toISOString(),
+          message: msg(err),
+        });
+      }
+    } finally {
+      if (ownsScope) await closeConnectorScope(connector, ctx);
     }
   }
 
@@ -687,12 +750,12 @@ export class CredentialHealthChecker {
       }
       // A rejected stored credential needs an operator, not a retry — the same
       // actionable state a revoked OAuth grant reports. There is no consent URL
-      // for a vault credential; /ui's credential form is where it is replaced.
+      // for a vault credential; /credentials is where it is replaced.
       return {
         state: "auth_required",
         message:
           result.message ??
-          "Stored credential was rejected by the connector — replace it in /ui.",
+          "Stored credential was rejected by the connector — replace it in /credentials.",
       };
     }
     const status = await connector.status!(ctx);

package/src/credentials.ts

@@ -1,5 +1,6 @@
 import type {
   Connector,
+  ConnectorCredentialConfig,
   ConnectorCredentialValues,
   KVStorage,
 } from "./types.js";
@@ -42,6 +43,98 @@ export interface CredentialMetadata {
 /** Which hook a testable credential is checked with. */
 export type CredentialTestMode = "single" | "multiple";
 
+/** Operator-safe explanation shared by every surface that detects shape drift. */
+export const STORED_CREDENTIAL_SHAPE_MISMATCH_ERROR =
+  "Stored credential fields do not match this connector's current declaration. Replace the credential before using or testing this connector.";
+
+export type StoredCredentialShape =
+  | { state: "missing" }
+  | {
+      state: "valid";
+      mode: CredentialTestMode;
+      /**
+       * Stored keys the connector no longer declares, sorted. Harmless — the
+       * credential works — but worth telling an operator about, since nothing
+       * else in `/ui` can show a field the declaration has stopped naming.
+       */
+      undeclared: string[];
+    }
+  | {
+      state: "mismatch";
+      mode: CredentialTestMode;
+      message: typeof STORED_CREDENTIAL_SHAPE_MISMATCH_ERROR;
+    };
+
+/**
+ * Compare a connector's current declaration with the keys in its stored
+ * credential. Values are deliberately ignored: callers may pass decrypted
+ * values or `/credentials`' masked field metadata and get the same answer.
+ *
+ * The test is CONTAINMENT, not equality: the stored key set is compatible when
+ * it holds every field currently declared — the reserved `value` key for a
+ * single-value declaration, every declared name for a named one. Anything the
+ * declaration asks for and the vault does not have is `mismatch`, which is
+ * precisely what a renamed field, a newly added field, or a swap between the
+ * two shapes produces. The swap needs no special case: `value` is never one of
+ * the declared names, so single→named and named→single each leave the declared
+ * side unsatisfied. An empty stored map (reachable through a hand-written
+ * plaintext) satisfies nothing and is a mismatch too.
+ *
+ * Extra keys are NOT drift. They are what *dropping* a field leaves behind, and
+ * every accessor a connector actually uses — `ctx.credential.get("apiKey")`,
+ * `getAll().apiKey` — keeps returning the right secret across that redeploy.
+ * Calling it drift would order an operator to re-enter a working secret that
+ * many providers will not reissue in readable form. The leftovers come back as
+ * `undeclared` instead, for a surface to mention without blocking anything.
+ */
+export function storedCredentialShape(
+  config: ConnectorCredentialConfig,
+  stored: Readonly<Record<string, unknown>> | null,
+): StoredCredentialShape {
+  if (!stored) return { state: "missing" };
+  const mode: CredentialTestMode = config.fields?.length
+    ? "multiple"
+    : "single";
+  const declared = new Set(
+    mode === "multiple" ? config.fields!.map((field) => field.name) : ["value"],
+  );
+  const actual = Object.keys(stored);
+  const present = new Set(actual);
+  for (const field of declared) {
+    if (!present.has(field)) {
+      return {
+        state: "mismatch",
+        mode,
+        message: STORED_CREDENTIAL_SHAPE_MISMATCH_ERROR,
+      };
+    }
+  }
+  return {
+    state: "valid",
+    mode,
+    undeclared: actual.filter((field) => !declared.has(field)).sort(),
+  };
+}
+
+/** How many leftover field names an advisory names before it summarizes. */
+const UNDECLARED_SAMPLE = 5;
+
+/**
+ * The one sentence describing leftover stored fields, so every surface words it
+ * the same way. Names only — the values stay in the vault, and a field name from
+ * a previous declaration is not a secret. Deliberately reassuring: nothing is
+ * broken, and the only thing an operator gains by acting is that a connector
+ * iterating `getAll()` stops seeing a field its code no longer knows about.
+ */
+export function describeUndeclaredCredentialFields(fields: string[]): string {
+  const shown = fields.slice(0, UNDECLARED_SAMPLE);
+  const rest = fields.length - shown.length;
+  const named = shown.join(", ") + (rest > 0 ? `, and ${rest} more` : "");
+  return fields.length === 1
+    ? `Stored credential also holds a field this connector no longer declares (${named}). It keeps working; replace the credential to drop it.`
+    : `Stored credential also holds fields this connector no longer declares (${named}). It keeps working; replace the credential to drop them.`;
+}
+
 /** A declared credential shape whose only test hook cannot test it. */
 export interface CredentialTestMismatch {
   /** The shape the connector declared. */
@@ -59,7 +152,7 @@ export interface CredentialTestRule {
 
 /**
  * The one rule deciding whether a connector's credential can be tested — read
- * by /ui's `testable` flag, by the `POST /ui/credentials/<id>/test` route when
+ * by /credentials' `testable` flag, by `POST /ui/credentials/<id>/test` when
  * it picks a hook, and by the construction-time mismatch warning, so those
  * three cannot drift apart.
  *
@@ -121,7 +214,7 @@ function base64ToBytes(value: string): Uint8Array {
     binary = atob(value);
   } catch {
     throw new Error(
-      "credentialEncryptionKey must be a base64-encoded 32-byte key",
+      "credentials.encryptionKey must be a base64-encoded 32-byte key",
     );
   }
   return Uint8Array.from(binary, (char) => char.charCodeAt(0));
@@ -216,7 +309,7 @@ export class CredentialVault {
     const raw = base64ToBytes(encryptionKey.trim());
     if (raw.byteLength !== KEY_BYTES) {
       throw new Error(
-        "credentialEncryptionKey must be a base64-encoded 32-byte key",
+        "credentials.encryptionKey must be a base64-encoded 32-byte key",
       );
     }
     this.key = crypto.subtle.importKey(

package/src/execute.ts

@@ -3,6 +3,9 @@ import { z } from "zod";
 import { compactSchema, rankTools, summarizeDescription } from "./catalog.js";
 import { recordToolActivity, type ActivityRequestContext } from "./activity.js";
 import {
+  assertDiscoveryResultSize,
+  discoveryAddresses,
+  discoverySearchLimit,
   errorResult,
   jsonResult,
   serializeResultText,
@@ -369,7 +372,7 @@ export async function buildSandboxProviders(
         }
         matches.sort((a, b) => b.score - a.score || a.order - b.order);
         const offset = Math.max(0, Math.trunc(args.offset ?? 0));
-        const limit = Math.max(1, Math.trunc(args.limit ?? 25));
+        const limit = discoverySearchLimit(args.limit);
         const page = matches.slice(offset, offset + limit).map((match) => {
           const input = match.tool.inputSchema ?? { type: "object" };
           return {
@@ -404,7 +407,7 @@ export async function buildSandboxProviders(
           offset + page.length < matches.length
             ? offset + page.length
             : undefined;
-        return {
+        const result = {
           tools: page,
           total: matches.length,
           offset,
@@ -412,6 +415,11 @@ export async function buildSandboxProviders(
           hasMore: nextOffset !== undefined,
           ...(nextOffset !== undefined ? { nextOffset } : {}),
         };
+        assertDiscoveryResultSize(
+          result,
+          "Request a smaller limit, omit fullDescriptions, or use compact schemas.",
+        );
+        return result;
       },
       describe: async (raw: unknown) => {
         const args = (raw ?? {}) as {
@@ -419,12 +427,10 @@ export async function buildSandboxProviders(
           format?: "compact" | "json";
           fullDescriptions?: boolean;
         };
-        if (!Array.isArray(args.addresses)) {
-          throw new Error("addresses must be an array");
-        }
+        const addresses = discoveryAddresses(args.addresses);
         const format = args.format ?? "compact";
-        return {
-          tools: args.addresses.map((rawAddress) => {
+        const result = {
+          tools: addresses.map((rawAddress) => {
             const address = String(rawAddress);
             const resolved = registry.resolveAddress(address);
             if (!resolved) {
@@ -457,6 +463,11 @@ export async function buildSandboxProviders(
             };
           }),
         };
+        assertDiscoveryResultSize(
+          result,
+          'Split the address list or use format: "compact".',
+        );
+        return result;
       },
     },
   });