@zackbart/connecta 0.4.0 → 0.5.0

package/src/registry.ts

@@ -7,11 +7,53 @@ import type {
   ToolDef,
 } from "./types.js";
 import type { CredentialVault } from "./credentials.js";
+import { splitAddress, type Toolkit } from "./toolkits.js";
 
 const ID_RE = /^[a-z0-9_-]+$/;
 const DEFAULT_TTL_SECONDS = 300;
 const DEFAULT_STALE_SECONDS = 3600;
-const DEFAULT_MAX_RESULT_BYTES = 50_000;
+export const DEFAULT_MAX_RESULT_BYTES = 50_000;
+
+/**
+ * Smallest accepted inline-result cap. One byte is pathological but harmless:
+ * `alignEndToCharBoundary` widens a window narrower than the codepoint at the
+ * offset, so even a 1-byte cap still truncates sanely and still pages. Caps
+ * that small already ship in the test suite (4 and 5), so the floor is placed
+ * where it excludes only values that are *broken* rather than merely tiny.
+ */
+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
+ * `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
+ * silently does something *worse* than the default: `0`/`NaN` serve an empty
+ * head (`slice(0, 0)`) and make paging fail to advance, negatives serve a
+ * LARGER head than asked for (`slice(0, -1)` counts from the end) while still
+ * claiming truncation, and `Infinity` disables the guard with no notice.
+ */
+export function isValidMaxResultBytes(value: number): boolean {
+  return Number.isInteger(value) && value >= MIN_MAX_RESULT_BYTES;
+}
+
+/**
+ * Resolve a configured cap against the value it inherits, dropping anything
+ * `isValidMaxResultBytes` rejects. Operator-facing surfaces pair this with a
+ * startup warning (see `Registry.checkResultCaps`) so the fallback is never
+ * silent; the resolution itself stays total so no call site has to cope with
+ * a broken cap.
+ */
+export function resolveMaxResultBytes(
+  value: number | undefined,
+  inherited: number,
+): number {
+  return value !== undefined && isValidMaxResultBytes(value)
+    ? value
+    : inherited;
+}
 
 interface CacheEntry {
   tools: ToolDef[];
@@ -34,6 +76,48 @@ export interface HealthObservation {
   lastError?: string;
 }
 
+/**
+ * Recent real-call outcomes per connector, as observed by ONE view.
+ *
+ * The deployment keeps one log, and each toolkit keeps its own. That split is a
+ * scope boundary, not bookkeeping: `lastError` is a downstream error string
+ * that routinely names the tool that failed, and `list_connectors` returns the
+ * observation verbatim. Sharing one log would let a toolkit read back the tools
+ * and failures of a sibling toolkit through a connector they happen to share —
+ * and let a sibling's failures flip this view's reported status. A scoped view
+ * reads back only the calls it made itself.
+ */
+export class HealthLog {
+  private readonly observations = new Map<string, HealthObservation>();
+
+  recordSuccess(id: string, latencyMs: number): void {
+    const previous = this.observations.get(id);
+    this.observations.set(id, {
+      ...previous,
+      lastSuccessAt: new Date().toISOString(),
+      lastLatencyMs: latencyMs,
+      consecutiveFailures: 0,
+      lastError: undefined,
+    });
+  }
+
+  recordFailure(id: string, latencyMs: number, error: unknown): void {
+    const previous = this.observations.get(id);
+    this.observations.set(id, {
+      ...previous,
+      lastFailureAt: new Date().toISOString(),
+      lastLatencyMs: latencyMs,
+      consecutiveFailures: (previous?.consecutiveFailures ?? 0) + 1,
+      lastError: msg(error),
+    });
+  }
+
+  get(id: string): HealthObservation | undefined {
+    const observation = this.observations.get(id);
+    return observation ? { ...observation } : undefined;
+  }
+}
+
 export interface RegistryOptions {
   storage: KVStorage;
   logger: Logger;
@@ -41,7 +125,11 @@ export interface RegistryOptions {
   toolCacheTtlSeconds?: number;
   persistToolCatalog?: boolean;
   toolCatalogStaleSeconds?: number;
-  /** Cap on inline result size before truncation + get_result paging. Default 50_000. */
+  /**
+   * Cap on inline result size before truncation + get_result paging. Must be a
+   * whole number of bytes >= 1; anything else warns at startup and falls back
+   * to the default 50_000.
+   */
   maxResultBytes?: number;
 }
 
@@ -57,16 +145,67 @@ function msg(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
+/**
+ * The registry surface a per-connection MCP server consumes: every meta-tool
+ * (`src/meta-tools.ts`) and the `execute_code` sandbox bridge (`src/execute.ts`)
+ * is typed against THIS, never against the concrete `Registry`.
+ *
+ * That indirection is the toolkit boundary (issue #22): a scoped connection is
+ * handed a `ScopedRegistry` instead of the registry, and every meta-tool
+ * inherits the scope from one place. Reaching for a registry method that isn't
+ * here is a compile error, and adding one here is a compile error until
+ * `ScopedRegistry` filters it — so a new meta-tool cannot quietly step around
+ * the boundary.
+ */
+export interface RegistryView {
+  /** Deployment-wide result-size cap threaded to the meta-tools. */
+  readonly maxResultBytes: number;
+  listConnectors(): Connector[];
+  getConnector(id: string): Connector | undefined;
+  resolveAddress(
+    address: string,
+  ): { connector: Connector; toolName: string } | null;
+  getTools(
+    id: string,
+    baseUrl: string,
+    requestScope?: object,
+  ): Promise<ToolDef[]>;
+  refreshTools(
+    id: string,
+    baseUrl: string,
+    requestScope?: object,
+  ): Promise<ToolDef[]>;
+  peekTools(id: string): ToolDef[] | undefined;
+  contextFor(
+    id: string,
+    baseUrl: string,
+    requestScope?: object,
+    callOptions?: { signal?: AbortSignal; timeoutMs?: number },
+  ): ConnectorContext;
+  resultsStorage(): KVStorage;
+  recordSuccess(id: string, latencyMs: number): void;
+  recordFailure(id: string, latencyMs: number, error: unknown): void;
+  healthFor(id: string): HealthObservation | undefined;
+  hasObservedSuccess(id: string): boolean;
+  statusFor(
+    id: string,
+    baseUrl: string,
+    requestScope?: object,
+  ): Promise<ConnectorStatus>;
+  invalidateStored(id: string): Promise<void>;
+}
+
 /**
  * Holds the connector set, resolves addresses, and caches per-connector tool
  * lists in memory with a TTL. Connector failures are isolated: a broken
  * connector surfaces status "error"; the rest keep working.
  */
-export class Registry {
+export class Registry implements RegistryView {
   private readonly connectors = new Map<string, Connector>();
   private readonly cache = new Map<string, CacheEntry>();
   private readonly invalidated = new Set<string>();
-  private readonly health = new Map<string, HealthObservation>();
+  /** Deployment-wide observations — every call, whatever view made it. */
+  private readonly health = new HealthLog();
   private readonly ttlMs: number;
   private readonly staleMs: number;
   private readonly persistToolCatalog: boolean;
@@ -82,7 +221,10 @@ export class Registry {
     this.staleMs =
       (opts.toolCatalogStaleSeconds ?? DEFAULT_STALE_SECONDS) * 1000;
     this.persistToolCatalog = opts.persistToolCatalog ?? true;
-    this.maxResultBytes = opts.maxResultBytes ?? DEFAULT_MAX_RESULT_BYTES;
+    this.maxResultBytes = resolveMaxResultBytes(
+      opts.maxResultBytes,
+      DEFAULT_MAX_RESULT_BYTES,
+    );
     for (const c of connectors) {
       if (!ID_RE.test(c.id)) {
         throw new Error(
@@ -95,6 +237,47 @@ export class Registry {
       this.connectors.set(c.id, c);
     }
     this.checkConventions(opts.logger);
+    this.checkResultCaps(opts.logger, opts.maxResultBytes);
+  }
+
+  /**
+   * Warn once per unusable result cap, at construction time — the same
+   * "runs fine but is surely unintended" channel as the insecure-config
+   * warnings in `createConnecta`. A rejected cap can't be honoured, and
+   * honouring it *approximately* is exactly the inversion issue #32 is about,
+   * so the value is dropped in favour of what it inherits and the operator is
+   * told which one is actually in force.
+   */
+  private checkResultCaps(
+    logger: Logger,
+    configured: number | undefined,
+  ): void {
+    if (configured !== undefined && !isValidMaxResultBytes(configured)) {
+      logger.warn(
+        `[connecta] 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.`,
+      );
+    }
+    for (const c of this.connectors.values()) {
+      if (
+        c.maxResultBytes !== undefined &&
+        !isValidMaxResultBytes(c.maxResultBytes)
+      ) {
+        // The number quoted here is `this.maxResultBytes` because that is
+        // literally what a call falls back to: meta-tools reads the inherited
+        // cap off `RegistryView.maxResultBytes`, so the warned value and the
+        // runtime value are the same field rather than two copies of it.
+        logger.warn(
+          `[connecta] connector "${c.id}" sets maxResultBytes ` +
+            `${c.maxResultBytes}, which is not a whole number of bytes >= ` +
+            `${MIN_MAX_RESULT_BYTES}. Ignoring the override — the connector ` +
+            `inherits the deployment-wide cap calls fall back to ` +
+            `(${this.maxResultBytes}).`,
+        );
+      }
+    }
   }
 
   /**
@@ -169,13 +352,11 @@ export class Registry {
   resolveAddress(
     address: string,
   ): { connector: Connector; toolName: string } | null {
-    const dot = address.indexOf(".");
-    if (dot <= 0 || dot === address.length - 1) return null;
-    const id = address.slice(0, dot);
-    const toolName = address.slice(dot + 1);
-    const connector = this.connectors.get(id);
+    const parts = splitAddress(address);
+    if (!parts) return null;
+    const connector = this.connectors.get(parts.connectorId);
     if (!connector) return null;
-    return { connector, toolName };
+    return { connector, toolName: parts.toolName };
   }
 
   private catalogKey(id: string): string {
@@ -320,30 +501,27 @@ export class Registry {
   }
 
   recordSuccess(id: string, latencyMs: number): void {
-    const previous = this.health.get(id);
-    this.health.set(id, {
-      ...previous,
-      lastSuccessAt: new Date().toISOString(),
-      lastLatencyMs: latencyMs,
-      consecutiveFailures: 0,
-      lastError: undefined,
-    });
+    this.health.recordSuccess(id, latencyMs);
   }
 
   recordFailure(id: string, latencyMs: number, error: unknown): void {
-    const previous = this.health.get(id);
-    this.health.set(id, {
-      ...previous,
-      lastFailureAt: new Date().toISOString(),
-      lastLatencyMs: latencyMs,
-      consecutiveFailures: (previous?.consecutiveFailures ?? 0) + 1,
-      lastError: msg(error),
-    });
+    this.health.recordFailure(id, latencyMs, error);
   }
 
   healthFor(id: string): HealthObservation | undefined {
-    const observation = this.health.get(id);
-    return observation ? { ...observation } : undefined;
+    return this.health.get(id);
+  }
+
+  /**
+   * Whether ANY view of this deployment has seen a successful call to `id` —
+   * a bare boolean, never the observation. Connector liveness (reachable,
+   * credentials still valid) is a deployment-level fact, not a per-view one, so
+   * `list_connectors` may classify a connector as ok/unknown from it. The
+   * observation itself — `lastError` above all, which names the tool that
+   * failed — stays strictly per view.
+   */
+  hasObservedSuccess(id: string): boolean {
+    return this.health.get(id)?.lastSuccessAt !== undefined;
   }
 
   /** Best-effort connector status for list_connectors. */
@@ -398,3 +576,212 @@ export class Registry {
     }
   }
 }
+
+/**
+ * Per-toolkit HealthLogs, keyed by registry and then by toolkit name.
+ *
+ * Module-scoped rather than a `Registry` member on purpose: `Registry`'s type
+ * is part of the public API surface (`Connecta.registry`), and this is internal
+ * factoring only `ScopedRegistry` may touch. The WeakMap keeps the logs alive
+ * exactly as long as their registry, and the inner map is bounded by the
+ * number of configured toolkits.
+ */
+const toolkitHealthLogs = new WeakMap<Registry, Map<string, HealthLog>>();
+
+/** The long-lived log one toolkit records into; created on first use. */
+function toolkitHealthLog(base: Registry, toolkitName: string): HealthLog {
+  let logs = toolkitHealthLogs.get(base);
+  if (!logs) {
+    logs = new Map<string, HealthLog>();
+    toolkitHealthLogs.set(base, logs);
+  }
+  let log = logs.get(toolkitName);
+  if (!log) {
+    log = new HealthLog();
+    logs.set(toolkitName, log);
+  }
+  return log;
+}
+
+/**
+ * THE toolkit enforcement point (issue #22).
+ *
+ * A filtered VIEW of one long-lived `Registry`: same connectors, same tool
+ * caches, same health — narrowed to the connectors and tool addresses one
+ * toolkit selects. `serveMcp` builds it once per scoped connection and hands it
+ * to `registerMetaTools`/`registerExecuteTool`, so `list_connectors`,
+ * `search_tools`, `describe_tools`, `call_tool`, `call_destructive_tool`,
+ * `batch_call`, `authorize_connector`, `get_result`, `skills`, and the
+ * `execute_code` host bridge all inherit the boundary from here instead of
+ * re-implementing nine checks.
+ *
+ * Two invariants make it reviewable:
+ *
+ * 1. **Indistinguishability.** Out-of-scope input fails through the SAME code
+ *    path, with the same error class and message, as input naming something
+ *    that does not exist at all. An out-of-scope CONNECTOR disappears from
+ *    `resolveAddress`/`getConnector` (→ `Unknown address` / `Unknown
+ *    connector`); an out-of-scope TOOL disappears from the catalog this view
+ *    returns (→ `Unknown tool "<t>" on connector "<c>"`), which is exactly the
+ *    error a misspelled tool name already produced. Scoping deliberately does
+ *    NOT reject at `resolveAddress` for tools: that would answer with the
+ *    connector-level message and make "hidden here" distinguishable from
+ *    "never existed".
+ * 2. **It filters views, never state.** Every read delegates to the shared
+ *    registry and filters the returned array, so the tool cache, the persisted
+ *    catalog, and the health map stay whole and shared across scopes.
+ */
+export class ScopedRegistry implements RegistryView {
+  /** This toolkit's own health observations — see HealthLog. */
+  private readonly health: HealthLog;
+
+  constructor(
+    private readonly base: Registry,
+    private readonly toolkit: Toolkit,
+  ) {
+    this.health = toolkitHealthLog(base, toolkit.name);
+  }
+
+  get maxResultBytes(): number {
+    return this.base.maxResultBytes;
+  }
+
+  /** In scope AND actually registered. */
+  private visible(id: string): boolean {
+    return (
+      this.toolkit.hasConnector(id) && this.base.getConnector(id) !== undefined
+    );
+  }
+
+  /** Byte-identical to what the unscoped registry throws for an unknown id. */
+  private unknownConnector(id: string): Error {
+    return new Error(`Unknown connector "${id}"`);
+  }
+
+  private inScopeTools(id: string, tools: ToolDef[]): ToolDef[] {
+    return tools.filter((tool) => this.toolkit.hasTool(id, tool.name));
+  }
+
+  listConnectors(): Connector[] {
+    return this.base
+      .listConnectors()
+      .filter((connector) => this.toolkit.hasConnector(connector.id));
+  }
+
+  getConnector(id: string): Connector | undefined {
+    return this.visible(id) ? this.base.getConnector(id) : undefined;
+  }
+
+  resolveAddress(
+    address: string,
+  ): { connector: Connector; toolName: string } | null {
+    const resolved = this.base.resolveAddress(address);
+    if (!resolved) return null;
+    // Connector-level only — see invariant 1 above.
+    return this.toolkit.hasConnector(resolved.connector.id) ? resolved : null;
+  }
+
+  async getTools(
+    id: string,
+    baseUrl: string,
+    requestScope?: object,
+  ): Promise<ToolDef[]> {
+    if (!this.visible(id)) throw this.unknownConnector(id);
+    return this.inScopeTools(
+      id,
+      await this.base.getTools(id, baseUrl, requestScope),
+    );
+  }
+
+  async refreshTools(
+    id: string,
+    baseUrl: string,
+    requestScope?: object,
+  ): Promise<ToolDef[]> {
+    if (!this.visible(id)) throw this.unknownConnector(id);
+    return this.inScopeTools(
+      id,
+      await this.base.refreshTools(id, baseUrl, requestScope),
+    );
+  }
+
+  peekTools(id: string): ToolDef[] | undefined {
+    if (!this.visible(id)) return undefined;
+    const tools = this.base.peekTools(id);
+    return tools ? this.inScopeTools(id, tools) : undefined;
+  }
+
+  contextFor(
+    id: string,
+    baseUrl: string,
+    requestScope: object = {},
+    callOptions: { signal?: AbortSignal; timeoutMs?: number } = {},
+  ): ConnectorContext {
+    // Unreachable through the meta-tools (they resolve first), so a throw here
+    // is a loud backstop rather than a silent grant of connector storage and
+    // credentials to a scope that may not see the connector.
+    if (!this.visible(id)) throw this.unknownConnector(id);
+    return this.base.contextFor(id, baseUrl, requestScope, callOptions);
+  }
+
+  /**
+   * 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
+   * from another scope reads back as the ordinary "Unknown or expired result
+   * id". Unscoped sessions keep the historical `results:` prefix untouched.
+   */
+  resultsStorage(): KVStorage {
+    return namespaced(
+      this.base.resultsStorage(),
+      `toolkit:${this.toolkit.name}:`,
+    );
+  }
+
+  // Outcomes are recorded twice on purpose: the deployment-wide log keeps the
+  // operator surfaces complete, while the toolkit's own log is the ONLY one
+  // this view reads back — so `list_connectors` here never reports a sibling
+  // toolkit's failures, or the tool names their error strings carry.
+  recordSuccess(id: string, latencyMs: number): void {
+    if (!this.visible(id)) return;
+    this.base.recordSuccess(id, latencyMs);
+    this.health.recordSuccess(id, latencyMs);
+  }
+
+  recordFailure(id: string, latencyMs: number, error: unknown): void {
+    if (!this.visible(id)) return;
+    this.base.recordFailure(id, latencyMs, error);
+    this.health.recordFailure(id, latencyMs, error);
+  }
+
+  healthFor(id: string): HealthObservation | undefined {
+    return this.visible(id) ? this.health.get(id) : undefined;
+  }
+
+  /**
+   * Deliberately NOT per view: whether the connector has ever answered is a
+   * fact about the connector, not about a team's traffic, and withholding it
+   * would report every remote connector as "unknown" to a scoped session that
+   * has not called it yet. It carries no tool name, error text, or count — the
+   * per-view isolation of those, above, is unchanged.
+   */
+  hasObservedSuccess(id: string): boolean {
+    return this.visible(id) ? this.base.hasObservedSuccess(id) : false;
+  }
+
+  async statusFor(
+    id: string,
+    baseUrl: string,
+    requestScope: object = {},
+  ): Promise<ConnectorStatus> {
+    // Same shape the unscoped registry returns for an unregistered id.
+    if (!this.visible(id)) {
+      return { state: "error", message: "Unknown connector" };
+    }
+    return this.base.statusFor(id, baseUrl, requestScope);
+  }
+
+  async invalidateStored(id: string): Promise<void> {
+    if (!this.visible(id)) return;
+    await this.base.invalidateStored(id);
+  }
+}