@zackbart/connecta 0.8.0 → 0.8.1

package/src/catalog.ts

@@ -17,6 +17,61 @@ function normalized(text: string): string {
   return text.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
 }
 
+/**
+ * Conversational framing selected by the #188 research run before the #189
+ * holdout existed. Action-bearing terms such as get/list/search/find/create
+ * deliberately remain: arbitrary connector catalogs need those distinctions.
+ */
+const CONVERSATIONAL_QUERY_WORDS = new Set([
+  "a",
+  "all",
+  "an",
+  "and",
+  "are",
+  "can",
+  "could",
+  "current",
+  "for",
+  "from",
+  "i",
+  "in",
+  "into",
+  "it",
+  "latest",
+  "let",
+  "me",
+  "most",
+  "of",
+  "on",
+  "our",
+  "please",
+  "right",
+  "show",
+  "that",
+  "the",
+  "this",
+  "to",
+  "up",
+  "want",
+  "when",
+  "which",
+  "with",
+  "you",
+]);
+
+/**
+ * Remove conversational framing before the all-term/partial decision. If
+ * every term is framing, retain the original query rather than turning a
+ * search into an unfiltered catalog browse.
+ */
+export function lexicalSearchQuery(query: string): string {
+  const terms = normalized(query).split(/\s+/).filter(Boolean);
+  const contentTerms = terms.filter(
+    (term) => !CONVERSATIONAL_QUERY_WORDS.has(term),
+  );
+  return contentTerms.length > 0 ? contentTerms.join(" ") : query;
+}
+
 interface SearchDocument {
   tool: ToolDef;
   name: string;

package/src/connectors/remote-mcp.ts

@@ -190,8 +190,7 @@ function msg(err: unknown): string {
  * `Client.close()` only unwinds our side — it aborts the transport's controller
  * and fires `onclose`. Spec session termination is a separate DELETE carrying
  * `Mcp-Session-Id`, and without it a stateful provider keeps the session alive
- * until its own (often hour-long) timeout, which a periodic probe would then
- * accumulate several of per connector.
+ * until its own (often hour-long) timeout, accumulating abandoned sessions.
  *
  * Ordering is load-bearing: the SDK sends that DELETE on the transport's
  * AbortSignal, so calling this *after* close would abort the request on issue
@@ -468,6 +467,14 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
   const scopeEndedError = () =>
     new Error(`Connector "${id}" scope ended during connection.`);
 
+  const requestOptions = (ctx: ConnectorContext) =>
+    ctx.timeoutMs || ctx.signal
+      ? {
+          ...(ctx.timeoutMs ? { timeout: ctx.timeoutMs } : {}),
+          ...(ctx.signal ? { signal: ctx.signal } : {}),
+        }
+      : undefined;
+
   /**
    * One `tools/list` request. The SDK schema is retained wholesale except for
    * accepting `null` as the common, unambiguous end-of-chain spelling. Other
@@ -485,12 +492,7 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
           ...(cursor === undefined ? {} : { params: { cursor } }),
         },
         CompatibleListToolsResultSchema,
-        ctx.timeoutMs || ctx.signal
-          ? {
-              ...(ctx.timeoutMs ? { timeout: ctx.timeoutMs } : {}),
-              ...(ctx.signal ? { signal: ctx.signal } : {}),
-            }
-          : undefined,
+        requestOptions(ctx),
       );
     } catch (err) {
       if (!isCursorShapeError(err)) throw err;
@@ -910,12 +912,7 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
             arguments: (args ?? {}) as Record<string, unknown>,
           },
           undefined,
-          ctx.timeoutMs || ctx.signal
-            ? {
-                ...(ctx.timeoutMs ? { timeout: ctx.timeoutMs } : {}),
-                ...(ctx.signal ? { signal: ctx.signal } : {}),
-              }
-            : undefined,
+          requestOptions(ctx),
         );
       } catch (err) {
         // A grant revoked after connect surfaces here, not in ensureConnected.
@@ -998,15 +995,6 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
   };
 
   if (opts.auth?.type === "oauth") {
-    // The credential liveness checks (issue #24) probe only connectors that
-    // actually hold a stored grant: with no tokens there is nothing whose
-    // liveness could have lapsed, and a `status()` probe would kick off DCR +
-    // consent on a timer for a connector nobody has authorized yet.
-    connector.hasStoredCredential = async (ctx) => {
-      const state = stateFor(ctx);
-      return (await getProvider(ctx, state).tokens()) !== undefined;
-    };
-
     connector.verifyState = async (oauthState, ctx) => {
       const state = stateFor(ctx);
       return getProvider(ctx, state).verifyState(oauthState);

package/src/errors.ts

@@ -10,6 +10,12 @@ export type ConnectorCallErrorCode =
   | "invalid_args"
   | "connector_call_failed";
 
+/** Agent-visible recovery class attached only to `auth_required` failures. */
+export type AuthRecoveryMode =
+  | "oauth"
+  | "operator_config"
+  | "unavailable";
+
 const RETRYABLE_BY_CODE: Record<ConnectorCallErrorCode, boolean> = {
   timeout: true,
   rate_limited: true,
@@ -78,6 +84,20 @@ export interface CallErrorDetails {
    * window so it can schedule a re-issue.
    */
   retryAfterMs?: number;
+  /** Connector whose failed operation needs recovery. */
+  connector?: string;
+  /** Canonical downstream address the agent may retry after recovery. */
+  operation?: string;
+  /** Which safe recovery path `authorize_connector` will return. */
+  recovery?: AuthRecoveryMode;
+  /** The single model-facing entry point for every credential class. */
+  nextAction?: {
+    tool: "authorize_connector";
+    arguments: { connector: string };
+    operatorHandoff: string;
+  };
+  /** Explicit retry guidance; recovery never retries or mutates by itself. */
+  retry?: string;
 }
 
 const RETRYABLE_MESSAGE_RE =

package/src/execute.ts

@@ -2,7 +2,7 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import type { ActivityRequestContext } from "./activity.js";
 import {
-  assertDiscoveryResultSize,
+  boundedDiscoveryText,
   CatalogService,
   flatSearchResult,
 } from "./catalog-service.js";
@@ -16,14 +16,12 @@ import {
   ExecutorAdmissionError,
   isAdmittingExecutor,
 } from "./executor-admission.js";
-import { unwrapMcpResult } from "./mcp-result.js";
 import {
   InvocationFailure,
   InvocationService,
 } from "./invocation.js";
 import type { RegistryView } from "./registry.js";
 import type {
-  Connector,
   Executor,
   ExecutorProvider,
   Logger,
@@ -137,19 +135,6 @@ ${declarations}
 })();`;
 }
 
-/**
- * Unwrap an MCP CallToolResult so sandbox code sees plain values:
- * isError throws (a real exception the code can catch), structuredContent
- * wins when present, all-text content is JSON.parsed when possible.
- * Non-MCP connectors already return plain values.
- */
-export function unwrapForSandbox(
-  kind: Connector["kind"],
-  result: unknown,
-): unknown {
-  return unwrapMcpResult(kind, result);
-}
-
 /**
  * Expose one fixed host provider plus trusted sandbox setup that creates a
  * lazy proxy global per connector. No connector catalog is touched until code
@@ -287,7 +272,7 @@ export async function buildSandboxProviders(
             includeSchemas?: "compact" | "json";
           };
           const result = flatSearchResult(await catalog.search(args));
-          assertDiscoveryResultSize(
+          boundedDiscoveryText(
             result,
             "Request a smaller limit, omit fullDescriptions, or use compact schemas.",
           );
@@ -300,7 +285,7 @@ export async function buildSandboxProviders(
             fullDescriptions?: boolean;
           };
           const result = { tools: await catalog.describe(args) };
-          assertDiscoveryResultSize(
+          boundedDiscoveryText(
             result,
             'Split the address list or use format: "compact".',
           );

package/src/executor-result.ts

@@ -9,7 +9,7 @@ function msg(err: unknown): string {
 }
 
 function serializeExecuteValue(value: unknown): string {
-  const serialized = JSON.stringify(value, null, 2);
+  const serialized = JSON.stringify(value);
   return serialized === undefined ? String(value) : serialized;
 }
 

package/src/index.ts

@@ -6,12 +6,6 @@ import {
 import { Registry } from "./registry.js";
 import { createFetchHandler } from "./server.js";
 import { droppedBrandingUrls, droppedUiAuthUrls } from "./ui.js";
-import {
-  resolveToolkits,
-  validateToolkitBindings,
-  type Toolkit,
-  type ToolkitConfig,
-} from "./toolkits.js";
 import { memoryStorage } from "./storage/memory.js";
 import { CONNECTA_VERSION } from "./version.js";
 import {
@@ -20,11 +14,6 @@ import {
   withExecutorAdmission,
 } from "./executor-admission.js";
 import type { ActivityReadGate, ActivityStore } from "./activity.js";
-import type {
-  CredentialCheckResult,
-  CredentialHealthConfig,
-} from "./credential-health.js";
-import type { DeferredWork } from "./connector-scope.js";
 import type {
   Connector,
   ConnectaBranding,
@@ -50,24 +39,13 @@ export interface ConnectaActivityConfig {
   deploymentId?: string;
 }
 
-/** Operator-vault encryption and proactive credential-health tuning. */
+/** Operator-vault encryption. */
 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. */
@@ -156,38 +134,6 @@ export interface ConnectaAdmissionConfig {
 
 export interface ConnectaConfig {
   connectors: Connector[];
-  /**
-   * Named scoped views over `connectors`, selected per client connection with
-   * `?toolkit=<name>` on the `/mcp` URL. One deployment belongs to one org;
-   * a toolkit is the slice of it a group of team members sees.
-   *
-   * ```ts
-   * toolkits: {
-   *   support: { connectors: ["zendesk", "notion"] },
-   *   exec: {
-   *     connectors: ["zendesk", "notion", "gmail"],
-   *     excludeTools: ["gmail.send_message"],
-   *   },
-   * }
-   * ```
-   *
-   * Inside a toolkit-scoped session every meta-tool behaves as if out-of-scope
-   * connectors and tools do not exist, and an out-of-scope address fails
-   * exactly as a nonexistent one does. No `?toolkit=` ⇒ the full registry, so
-   * adding toolkits changes nothing for connections that don't ask for one; an
-   * unknown name is an error, never a silent fallback.
-   *
-   * Selection is self-service until a toolkit is BOUND to an inbound identity:
-   * pass `toolkits` to an auth adapter — `bearerToken(secret, { toolkits:
-   * ["support"] })` — and that credential may open only those toolkits, and may
-   * not connect unscoped unless it also passes `unscoped: true`. An unbound
-   * identity keeps the self-service behavior.
-   *
-   * Definitions are validated at construction: an unknown connector id, an
-   * empty connector selection, an empty `includeTools`, a malformed tool
-   * address, or an address naming no tool on an in-code connector all throw.
-   */
-  toolkits?: ToolkitConfig;
   /** Inbound auth adapters. Includes bearerToken(...); omit for open (dev). */
   auth?: InboundAuth | InboundAuth[];
   /** KVStorage impl. Defaults to memoryStorage(). */
@@ -199,7 +145,7 @@ export interface ConnectaConfig {
   publicUrl?: string;
   /** Payload-free tool activity storage and operator-read policy. */
   activity?: ConnectaActivityConfig;
-  /** Operator credential vault and proactive liveness-check settings. */
+  /** Operator credential vault settings. */
   credentials?: ConnectaCredentialsConfig;
   /** Tool-catalog caching, persistence, stale fallback, and probe deadlines. */
   discovery?: ConnectaDiscoveryConfig;
@@ -235,37 +181,6 @@ export interface Connecta {
   /** Web-standard fetch handler. Usable as `export default { fetch: connecta.fetch }`. */
   fetch: (request: Request, env?: unknown, ctx?: unknown) => Promise<Response>;
   registry: Registry;
-  /**
-   * Check the stored downstream credentials now — the scheduler-facing half of
-   * credential health (issue #24). Wire it to whatever timer the runtime has:
-   *
-   * ```ts
-   * // Cloudflare Workers (wrangler.jsonc: "triggers": { "crons": ["*\/15 * * * *"] })
-   * async scheduled(_c, env, ctx) {
-   *   const defer = ctx.waitUntil.bind(ctx);
-   *   ctx.waitUntil(build(env).checkCredentials({ defer }));
-   * }
-   * // Node
-   * setInterval(() => void connecta.checkCredentials(), 15 * 60_000).unref();
-   * ```
-   *
-   * Returns one outcome per connector considered, including why a connector was
-   * skipped (`fresh` is the rate limit: a connector checked less than
-   * `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.
-   */
-  checkCredentials: (opts?: {
-    baseUrl?: string;
-    force?: boolean;
-    ids?: string[];
-    /**
-     * Runtime continuation for bounded teardown after the check result is ready.
-     * Workers should pass `ctx.waitUntil.bind(ctx)`.
-     */
-    defer?: DeferredWork;
-  }) => Promise<CredentialCheckResult[]>;
   /** Drain and release configured executor resources. Idempotent. */
   close: () => Promise<void>;
 }
@@ -318,7 +233,6 @@ 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"],
@@ -337,6 +251,23 @@ const hasOwn = (value: object, key: PropertyKey): boolean =>
  */
 function assertNoLegacyConfig(config: ConnectaConfig): void {
   const candidate = config as unknown as Record<PropertyKey, unknown>;
+  if (hasOwn(candidate, "toolkits")) {
+    throw new Error(
+      "ConnectaConfig.toolkits was removed in issue #178. Deploy one " +
+        "connecta instance per audience instead; see ethos.md.",
+    );
+  }
+  const credentials = candidate.credentials;
+  const hasNestedHealth =
+    typeof credentials === "object" &&
+    credentials !== null &&
+    hasOwn(credentials, "health");
+  if (hasOwn(candidate, "credentialHealth") || hasNestedHealth) {
+    throw new Error(
+      "`credentials.health` and legacy `credentialHealth` were removed in " +
+        "issue #179. Credentials now fail at use; see ethos.md.",
+    );
+  }
   const found: Array<readonly [string, string]> = [];
   if (hasOwn(candidate, "activity")) {
     const activity = candidate.activity;
@@ -376,7 +307,6 @@ function assertNoLegacyConfig(config: ConnectaConfig): void {
 function warnInsecureConfig(
   config: ConnectaConfig,
   inboundAuth: InboundAuth[],
-  toolkits: ReadonlyMap<string, Toolkit> | undefined,
   logger: Logger,
 ): void {
   const oauthConnectors = config.connectors.filter((c) => c.finishAuth);
@@ -407,64 +337,6 @@ function warnInsecureConfig(
     );
   }
 
-  // Toolkits that nothing binds to an identity: selection is then self-service,
-  // and the boundary organizes the surface rather than protecting it. Three
-  // distinct shapes, so three distinct warnings — an operator can only act on
-  // the one they are actually in.
-  //
-  // All are keyed off the RESOLVED toolkits, which is the same map `?toolkit=`
-  // resolves against, rather than the presence of the config key: `toolkits: {}`
-  // is a truthy object that resolves to nothing selectable, so warning about a
-  // choice no caller can make would name a risk that does not exist.
-  if (toolkits) {
-    const unbound = inboundAuth.filter((provider) => !provider.toolkitBinding);
-    if (inboundAuth.length === 0) {
-      // No auth at all ⇒ no identity exists to bind, so binding is not even the
-      // fix here. The open-mode warning above covers the wider exposure.
-      logger.warn(
-        "[connecta] toolkits are configured but there is no inbound " +
-          "authentication: with no identity to bind a toolkit to, any caller " +
-          "can choose any toolkit or omit ?toolkit= and see every connector. " +
-          "Configure `auth` (for example bearerToken(...) or Clerk), then bind " +
-          "each credential with `toolkits: [...]`.",
-      );
-    } else if (unbound.length === inboundAuth.length) {
-      // Authenticated, but every credential may still select every view. This is
-      // the shape issue #37 exists to close, and it is invisible without a line
-      // saying so: nothing fails, the teams are simply not separated.
-      logger.warn(
-        "[connecta] toolkits are configured but no inbound identity is bound " +
-          "to one: every credential `auth` admits can select any toolkit, or " +
-          "omit ?toolkit= and see the whole deployment, so a token handed to " +
-          "one team also opens the others' views. Bind each credential with " +
-          "`toolkits: [...]` on its auth adapter (add `unscoped: true` for an " +
-          "operator credential that should still see everything).",
-      );
-    } else if (unbound.length > 0) {
-      // The dangerous middle: SOME credentials are bound, which is exactly when
-      // an operator believes the deployment is separated — while one forgotten
-      // provider still opens every view and the whole deployment-wide surface.
-      // Naming the unbound providers is the point; an intentionally unrestricted
-      // credential says so with `unscoped: true` and stops appearing here.
-      const counted = new Map<string, number>();
-      for (const provider of unbound) {
-        counted.set(provider.kind, (counted.get(provider.kind) ?? 0) + 1);
-      }
-      const named = [...counted]
-        .map(([kind, count]) => (count > 1 ? `${kind} x${count}` : kind))
-        .join(", ");
-      logger.warn(
-        `[connecta] toolkits are bound on some inbound auth providers but not ` +
-          `all: ${named} ${unbound.length === 1 ? "declares" : "declare"} no ` +
-          "binding, so a caller that provider admits can still select any " +
-          "toolkit, connect unscoped, and read the deployment-wide operator " +
-          "surfaces — whatever the bound credentials beside it allow. Bind it " +
-          "too, or declare the exemption with `toolkits: [...], unscoped: true` " +
-          "if it is meant to be an operator credential.",
-      );
-    }
-  }
-
   // Branding URLs that failed their scheme gate. Rendering silently falls back
   // (a bad URL must not take the page down), so this warning is the only way an
   // operator learns their value never reached the page.
@@ -541,8 +413,10 @@ export function createConnecta(config: ConnectaConfig): Connecta {
   const credentialConnectors = config.connectors.filter((c) => c.credential);
   const encryptionKey = config.credentials?.encryptionKey;
   if (credentialConnectors.length > 0 && !encryptionKey) {
-    throw new Error(
-      `credentials.encryptionKey is required by connector credentials: ${credentialConnectors.map((c) => c.id).join(", ")}`,
+    logger.warn(
+      "Operator-managed credentials are unavailable because " +
+        "credentials.encryptionKey is not configured for connectors: " +
+        credentialConnectors.map((c) => c.id).join(", "),
     );
   }
   const credentialVault = encryptionKey
@@ -567,21 +441,9 @@ export function createConnecta(config: ConnectaConfig): Connecta {
     ...(config.calls?.maxBatchResultBytes !== undefined
       ? { maxBatchResultBytes: config.calls.maxBatchResultBytes }
       : {}),
-    ...(config.credentials?.health !== undefined
-      ? { 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
-  // the scope being *intended*, not about it being an access check — a toolkit
-  // scopes visibility, and `auth` remains the thing deciding who gets in.
-  const toolkits = resolveToolkits(config.toolkits, config.connectors);
   const inboundAuth = normalizeAuth(config.auth);
-  // Same contract for the identity half: a binding that names a toolkit this
-  // deployment does not declare would deny that credential every connection,
-  // with a 403 its client reports as a transport failure. Throw here instead.
-  validateToolkitBindings(inboundAuth, toolkits);
-  warnInsecureConfig(config, inboundAuth, toolkits, logger);
+  warnInsecureConfig(config, inboundAuth, logger);
   const requestAdmission = admissionController(
     config.admission?.requests,
     REQUEST_ADMISSION_DEFAULTS,
@@ -637,7 +499,6 @@ export function createConnecta(config: ConnectaConfig): Connecta {
       ? { deploymentInfo: config.deploymentInfo }
       : {}),
     ...(config.branding !== undefined ? { branding: config.branding } : {}),
-    ...(toolkits ? { toolkits } : {}),
   });
   let closePromise: Promise<void> | undefined;
   return {
@@ -649,33 +510,6 @@ export function createConnecta(config: ConnectaConfig): Connecta {
           : undefined,
       ),
     registry,
-    checkCredentials: (opts = {}) => {
-      // A scheduled check has no inbound request to derive an origin from, and
-      // a connector context without one would mint OAuth redirect URIs against
-      // a guess. Say so instead: the fix is one config line.
-      const baseUrl = opts.baseUrl ?? config.publicUrl;
-      if (!baseUrl) {
-        // Rejected, not thrown: the callers this is written for are
-        // `ctx.waitUntil(...)` and `.catch(...)` on the returned promise, and a
-        // synchronous throw escapes both — it would take down a scheduled
-        // handler instead of being reported by it.
-        return Promise.reject(
-          new Error(
-            "checkCredentials() needs a base URL: set `publicUrl` on the " +
-              "config (recommended — it is also what downstream OAuth " +
-              "callbacks use) or pass checkCredentials({ baseUrl }).",
-          ),
-        );
-      }
-      return registry.checkCredentialHealth(
-        baseUrl,
-        {
-          ...(opts.force !== undefined ? { force: opts.force } : {}),
-          ...(opts.ids ? { ids: opts.ids } : {}),
-        },
-        opts.defer,
-      );
-    },
     close: async () => {
       closePromise ??= Promise.resolve().then(async () => {
         requestAdmission.close();
@@ -705,23 +539,6 @@ export { CONNECTA_VERSION } from "./version.js";
 // the class itself, the credential vault, and the meta-tool/sandbox factories
 // are internal factoring and are deliberately not part of the API surface.
 export type { Registry } from "./registry.js";
-// Config-as-code shapes for `ConnectaConfig.toolkits` and the identity bindings
-// that gate them. The resolved `Toolkit` and the `ScopedRegistry` that enforces
-// it are internal factoring.
-export type {
-  ToolkitBindingOptions,
-  ToolkitConfig,
-  ToolkitDefinition,
-} from "./toolkits.js";
-// Credential health: the config shape, and the result shape a scheduled
-// `checkCredentials()` returns. The checker itself is internal factoring.
-export type {
-  CredentialCheckResult,
-  CredentialCheckSkip,
-  CredentialCheckState,
-  CredentialHealthConfig,
-  CredentialHealthRecord,
-} from "./credential-health.js";
 
 export type {
   RemoteMcpOptions,
@@ -750,7 +567,6 @@ export type {
   ExecutorLease,
   ExecutorProvider,
   InboundAuth,
-  ToolkitBinding,
   UiAuthConfig,
   AuthResult,
   JsonSchema,