@zackbart/connecta 0.7.1 → 0.7.3

package/src/meta-tools.ts

@@ -30,7 +30,7 @@ import {
 import {
   DEFAULT_PROBE_TIMEOUT_MS,
   normalizeTimeoutMs,
-  withTimeout,
+  withAbortableTimeout,
 } from "./timeout.js";
 import { credentialVerdictApplies } from "./credential-health.js";
 import type { ConnectorStatus, KVStorage, ToolDef } from "./types.js";
@@ -597,6 +597,18 @@ export function createMetaTools(
   // identity lets remote connectors reuse one downstream client inside that
   // request without leaking request-bound I/O into the next one.
   const requestScope = {};
+  const withProbeDeadline = <T>(
+    label: string,
+    operation: (options: {
+      signal: AbortSignal;
+      timeoutMs: number;
+    }) => Promise<T>,
+  ) =>
+    withAbortableTimeout(
+      (signal) => operation({ signal, timeoutMs: probeTimeoutMs }),
+      probeTimeoutMs,
+      label,
+    );
 
   interface RunCallOutcome {
     toolResult: ToolResult;
@@ -907,8 +919,8 @@ export function createMetaTools(
       // 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(
-        connectors.map(async (c) => {
+      const pending = connectors.map(
+        async (c) => {
           const statusStarted = Date.now();
           const observed = registry.healthFor(c.id);
           const verdict = await registry.credentialHealthFor(c.id);
@@ -917,10 +929,10 @@ export function createMetaTools(
             | { state: "ok" | "error" | "unknown"; message?: string };
           if (probe) {
             try {
-              status = await withTimeout(
-                registry.statusFor(c.id, baseUrl, scope),
-                probeTimeoutMs,
+              status = await withProbeDeadline(
                 `list_connectors probe of "${c.id}"`,
+                (options) =>
+                  registry.statusFor(c.id, baseUrl, scope, options),
               );
             } catch (err) {
               // A probe that outran probeTimeoutMs (or otherwise threw)
@@ -1004,14 +1016,45 @@ export function createMetaTools(
           // the first (now stale) authorization URL.
           if (probe && status.state === "ok") {
             try {
-              tools = await withTimeout(
-                registry.refreshTools(c.id, baseUrl, scope),
-                probeTimeoutMs,
+              tools = await withProbeDeadline(
                 `list_connectors catalog refresh of "${c.id}"`,
+                (options) =>
+                  registry.refreshTools(c.id, baseUrl, scope, options),
               );
               registry.recordSuccess(c.id, Date.now() - statusStarted);
             } catch (err) {
-              status = { state: "error" as const, message: msg(err) };
+              const details = classifyCallError(err);
+              if (details.code === "auth_required") {
+                let authStatus: ConnectorStatus | undefined;
+                try {
+                  authStatus = await withProbeDeadline(
+                    `list_connectors authorization status of "${c.id}"`,
+                    (options) =>
+                      registry.statusFor(c.id, baseUrl, scope, options),
+                  );
+                } catch {
+                  // The typed auth verdict is still authoritative; this second
+                  // read exists only to recover the connector's pending URL.
+                }
+                status =
+                  authStatus?.state === "auth_required"
+                    ? authStatus
+                    : {
+                        state: "auth_required" as const,
+                        message: details.message,
+                      };
+                await registry.recordCredentialHealth(c.id, {
+                  state: "auth_required",
+                  checkedAt,
+                  ...(status.message ? { message: status.message } : {}),
+                  ...("authorizationUrl" in status &&
+                  status.authorizationUrl
+                    ? { authorizationUrl: status.authorizationUrl }
+                    : {}),
+                });
+              } else {
+                status = { state: "error" as const, message: msg(err) };
+              }
               registry.recordFailure(c.id, Date.now() - statusStarted, err);
             }
           }
@@ -1036,17 +1079,23 @@ 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),
-            ),
+        },
+      );
+      if (!probe) {
+        return jsonResult({ connectors: await Promise.all(pending) });
+      }
+      const settled = await Promise.allSettled(pending);
+      await Promise.all(
+        connectors.map((connector) =>
+          closeConnectorScope(
+            connector,
+            registry.contextFor(connector.id, baseUrl, scope),
           ),
-        );
+        ),
+      );
+      const out = settled.map((result) => {
+        if (result.status === "rejected") throw result.reason;
+        return result.value;
       });
       return jsonResult({ connectors: out });
     },
@@ -1079,10 +1128,10 @@ export function createMetaTools(
       }> = [];
       const catalogs = await Promise.allSettled(
         conns.map((c) =>
-          withTimeout(
-            registry.getTools(c.id, baseUrl, requestScope),
-            probeTimeoutMs,
+          withProbeDeadline(
             `search_tools probe of "${c.id}"`,
+            (options) =>
+              registry.getTools(c.id, baseUrl, requestScope, options),
           ),
         ),
       );
@@ -1208,10 +1257,10 @@ export function createMetaTools(
       ];
       const loaded = await Promise.allSettled(
         connectorIds.map((id) =>
-          withTimeout(
-            registry.getTools(id, baseUrl, requestScope),
-            probeTimeoutMs,
+          withProbeDeadline(
             `describe_tools probe of "${id}"`,
+            (options) =>
+              registry.getTools(id, baseUrl, requestScope, options),
           ),
         ),
       );

package/src/registry.ts

@@ -6,7 +6,11 @@ import type {
   Logger,
   ToolDef,
 } from "./types.js";
-import type { CredentialVault } from "./credentials.js";
+import {
+  storedCredentialShape,
+  type CredentialVault,
+} from "./credentials.js";
+import { ConnectorCallError } from "./errors.js";
 import {
   CredentialHealthChecker,
   type CredentialCheckOptions,
@@ -154,6 +158,11 @@ function msg(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
+type ConnectorOperationOptions = Pick<
+  ConnectorContext,
+  "signal" | "timeoutMs"
+>;
+
 /**
  * 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`)
@@ -178,18 +187,20 @@ export interface RegistryView {
     id: string,
     baseUrl: string,
     requestScope?: object,
+    callOptions?: ConnectorOperationOptions,
   ): Promise<ToolDef[]>;
   refreshTools(
     id: string,
     baseUrl: string,
     requestScope?: object,
+    callOptions?: ConnectorOperationOptions,
   ): Promise<ToolDef[]>;
   peekTools(id: string): ToolDef[] | undefined;
   contextFor(
     id: string,
     baseUrl: string,
     requestScope?: object,
-    callOptions?: { signal?: AbortSignal; timeoutMs?: number },
+    callOptions?: ConnectorOperationOptions,
   ): ConnectorContext;
   resultsStorage(): KVStorage;
   recordSuccess(id: string, latencyMs: number): void;
@@ -209,6 +220,7 @@ export interface RegistryView {
     id: string,
     baseUrl: string,
     requestScope?: object,
+    callOptions?: ConnectorOperationOptions,
   ): Promise<ConnectorStatus>;
   invalidateStored(id: string): Promise<void>;
 }
@@ -352,21 +364,31 @@ export class Registry implements RegistryView {
     id: string,
     baseUrl: string,
     requestScope: object = {},
-    callOptions: { signal?: AbortSignal; timeoutMs?: number } = {},
+    callOptions: ConnectorOperationOptions = {},
   ): ConnectorContext {
+    const credentialConfig = this.connectors.get(id)?.credential;
+    let credentialAccess: ConnectorContext["credential"];
+    if (this.opts.credentialVault && credentialConfig) {
+      const vault = this.opts.credentialVault;
+      const readValues = async () => {
+        const values = await vault.getAll(id);
+        const shape = storedCredentialShape(credentialConfig, values);
+        if (shape.state === "mismatch") {
+          throw new ConnectorCallError("auth_required", shape.message);
+        }
+        return values;
+      };
+      credentialAccess = {
+        get: async (field = "value") =>
+          (await readValues())?.[field] ?? null,
+        getAll: readValues,
+      };
+    }
     return {
       storage: namespaced(this.opts.storage, `conn:${id}:`),
       logger: this.opts.logger,
       baseUrl,
-      ...(this.opts.credentialVault && this.connectors.get(id)?.credential
-        ? {
-            credential: {
-              get: (field?: string) =>
-                this.opts.credentialVault!.get(id, field),
-              getAll: () => this.opts.credentialVault!.getAll(id),
-            },
-          }
-        : {}),
+      ...(credentialAccess ? { credential: credentialAccess } : {}),
       requestScope,
       ...callOptions,
     };
@@ -441,13 +463,14 @@ export class Registry implements RegistryView {
     id: string,
     baseUrl: string,
     requestScope?: object,
+    callOptions: ConnectorOperationOptions = {},
   ): Promise<ToolDef[]> {
     const connector = this.connectors.get(id);
     if (!connector) throw new Error(`Unknown connector "${id}"`);
     const tools = connector.staticTools
       ? connector.staticTools
       : await connector.listTools(
-          this.contextFor(id, baseUrl, requestScope),
+          this.contextFor(id, baseUrl, requestScope, callOptions),
         );
     const now = Date.now();
     const previous = this.cache.get(id);
@@ -479,6 +502,7 @@ export class Registry implements RegistryView {
     id: string,
     baseUrl: string,
     requestScope?: object,
+    callOptions: ConnectorOperationOptions = {},
   ): Promise<ToolDef[]> {
     const connector = this.connectors.get(id);
     if (!connector) throw new Error(`Unknown connector "${id}"`);
@@ -512,7 +536,7 @@ export class Registry implements RegistryView {
     }
 
     try {
-      return await this.refreshTools(id, baseUrl, requestScope);
+      return await this.refreshTools(id, baseUrl, requestScope, callOptions);
     } catch (err) {
       if (stale) {
         this.opts.logger.warn(
@@ -626,10 +650,11 @@ export class Registry implements RegistryView {
     id: string,
     baseUrl: string,
     requestScope: object = {},
+    callOptions: ConnectorOperationOptions = {},
   ): Promise<ConnectorStatus> {
     const connector = this.connectors.get(id);
     if (!connector) return { state: "error", message: "Unknown connector" };
-    const ctx = this.contextFor(id, baseUrl, requestScope);
+    const ctx = this.contextFor(id, baseUrl, requestScope, callOptions);
     if (connector.status) {
       try {
         return await connector.status(ctx);
@@ -638,7 +663,7 @@ export class Registry implements RegistryView {
       }
     }
     try {
-      await this.getTools(id, baseUrl, requestScope);
+      await this.getTools(id, baseUrl, requestScope, callOptions);
       return { state: "ok" };
     } catch (err) {
       return { state: "error", message: msg(err) };
@@ -782,11 +807,12 @@ export class ScopedRegistry implements RegistryView {
     id: string,
     baseUrl: string,
     requestScope?: object,
+    callOptions: ConnectorOperationOptions = {},
   ): Promise<ToolDef[]> {
     if (!this.visible(id)) throw this.unknownConnector(id);
     return this.inScopeTools(
       id,
-      await this.base.getTools(id, baseUrl, requestScope),
+      await this.base.getTools(id, baseUrl, requestScope, callOptions),
     );
   }
 
@@ -794,11 +820,12 @@ export class ScopedRegistry implements RegistryView {
     id: string,
     baseUrl: string,
     requestScope?: object,
+    callOptions: ConnectorOperationOptions = {},
   ): Promise<ToolDef[]> {
     if (!this.visible(id)) throw this.unknownConnector(id);
     return this.inScopeTools(
       id,
-      await this.base.refreshTools(id, baseUrl, requestScope),
+      await this.base.refreshTools(id, baseUrl, requestScope, callOptions),
     );
   }
 
@@ -812,7 +839,7 @@ export class ScopedRegistry implements RegistryView {
     id: string,
     baseUrl: string,
     requestScope: object = {},
-    callOptions: { signal?: AbortSignal; timeoutMs?: number } = {},
+    callOptions: ConnectorOperationOptions = {},
   ): 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
@@ -897,12 +924,13 @@ export class ScopedRegistry implements RegistryView {
     id: string,
     baseUrl: string,
     requestScope: object = {},
+    callOptions: { signal?: AbortSignal; timeoutMs?: number } = {},
   ): 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);
+    return this.base.statusFor(id, baseUrl, requestScope, callOptions);
   }
 
   async invalidateStored(id: string): Promise<void> {

package/src/server.ts

@@ -222,8 +222,8 @@ async function authorize(
   | {
       ok: true;
       actor: ActivityActor;
-      providerKind?: string;
-      userId?: string;
+      /** True only when the admitting provider can also authorize UI mutation. */
+      uiAdminEligible?: boolean;
       /** The admitting identity's toolkit binding (docs/toolkits.md). */
       toolkitBinding?: ToolkitBinding;
     }
@@ -261,8 +261,9 @@ async function authorize(
           kind: provider.kind,
           ...(subjectId ? { id: subjectId } : {}),
         },
-        providerKind: provider.kind,
-        ...(result.userId ? { userId: result.userId } : {}),
+        ...(result.userId && provider.uiAuth?.kind === "clerk"
+          ? { uiAdminEligible: true }
+          : {}),
         ...(binding.binding ? { toolkitBinding: binding.binding } : {}),
       };
     }
@@ -1197,7 +1198,7 @@ export function createFetchHandler(
 
       const operatorPage = operatorPageForPath(path);
       if (operatorPage) {
-        if (request.method !== "GET") {
+        if (request.method !== "GET" && request.method !== "HEAD") {
           return privateJson({ error: "method not allowed" }, { status: 405 });
         }
         // Open shell — carries no operator data; everything comes from the
@@ -1212,7 +1213,9 @@ export function createFetchHandler(
         // — only script execution, the XSS sink, is gated.
         const nonce = uiScriptNonce();
         return new Response(
-          renderUiHtml(uiAuth, mcpUrl, opts.branding, nonce, operatorPage),
+          request.method === "HEAD"
+            ? null
+            : renderUiHtml(uiAuth, mcpUrl, opts.branding, nonce, operatorPage),
           {
             status: 200,
             headers: {
@@ -1235,8 +1238,7 @@ export function createFetchHandler(
         // After the restriction check, not before: an identity that may not
         // read this surface should not get to trigger background work from it.
         sweepCredentials();
-        const eligibleClerkOperator =
-          authz.providerKind === "clerk" && Boolean(authz.userId);
+        const eligibleClerkOperator = authz.uiAdminEligible === true;
         const credentialManagement = credentialManagementCapability({
           eligibleClerkOperator,
           hasCredentialSlots: registry
@@ -1253,6 +1255,7 @@ export function createFetchHandler(
           eligibleClerkOperator ? opts.credentialVault : undefined,
           Boolean(opts.activity?.list),
           credentialManagement,
+          opts.toolkits,
         );
         return privateJson(data);
       }

package/src/timeout.ts

@@ -21,10 +21,9 @@ export function normalizeTimeoutMs(
 
 /**
  * Reject `promise` after `ms` if it has not settled, so one hung downstream
- * cannot stall a whole fan-out. NOTE: this bounds only the caller-facing wait —
- * the registry probe methods take no AbortSignal, so the underlying fetch is
- * NOT cancelled and keeps running in the background. Real cancellation
- * (AbortSignal plumbed through the registry) is a deferred follow-up.
+ * cannot stall a whole fan-out. This form bounds only the caller-facing wait;
+ * use `withAbortableTimeout` when the operation accepts an AbortSignal and the
+ * underlying work must stop too.
  */
 export function withTimeout<T>(
   promise: Promise<T>,
@@ -47,3 +46,41 @@ export function withTimeout<T>(
     );
   });
 }
+
+/**
+ * Give one operation a caller-facing deadline and the matching cancellation
+ * signal. The timeout rejects with the stable, labelled error while aborting
+ * any in-flight work that honors the signal.
+ */
+export function withAbortableTimeout<T>(
+  operation: (signal: AbortSignal) => Promise<T>,
+  ms: number,
+  label: string,
+): Promise<T> {
+  const controller = new AbortController();
+  return new Promise<T>((resolve, reject) => {
+    const timeoutError = new Error(`${label} timed out after ${ms}ms`);
+    const timer = setTimeout(() => {
+      controller.abort(timeoutError);
+      reject(timeoutError);
+    }, ms);
+    let promise: Promise<T>;
+    try {
+      promise = operation(controller.signal);
+    } catch (err) {
+      clearTimeout(timer);
+      reject(err);
+      return;
+    }
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (err) => {
+        clearTimeout(timer);
+        reject(err);
+      },
+    );
+  });
+}

package/src/toolkits.ts

@@ -41,6 +41,14 @@ export type ToolkitConfig = Record<string, ToolkitDefinition>;
 export interface Toolkit {
   readonly name: string;
   readonly description?: string;
+  /**
+   * The validated config this scope came from. Kept as immutable data so
+   * deployment-wide operator surfaces can explain the running configuration
+   * without inventing a second source of truth.
+   */
+  readonly connectors: readonly string[];
+  readonly includeTools: readonly string[];
+  readonly excludeTools: readonly string[];
   /** True when `connectorId` is inside this toolkit's scope. */
   hasConnector(connectorId: string): boolean;
   /** True when `<connectorId>.<toolName>` is inside this toolkit's scope. */
@@ -178,6 +186,9 @@ function resolveToolkit(
   return {
     name,
     ...(definition.description ? { description: definition.description } : {}),
+    connectors: Object.freeze([...connectorIds]),
+    includeTools: Object.freeze([...(definition.includeTools ?? [])]),
+    excludeTools: Object.freeze([...(definition.excludeTools ?? [])]),
     hasConnector: (connectorId) => connectorIds.has(connectorId),
     hasTool: (connectorId, toolName) => {
       if (!connectorIds.has(connectorId)) return false;

package/src/types.ts

@@ -113,9 +113,9 @@ export interface ConnectorContext {
    * when omitted.
    */
   requestScope?: object;
-  /** Best-effort cancellation signal for this individual tool call. */
+  /** Best-effort cancellation signal for this connector operation. */
   signal?: AbortSignal;
-  /** Requested tool-call deadline in milliseconds. */
+  /** Requested connector-operation deadline in milliseconds. */
   timeoutMs?: number;
 }