@zackbart/connecta 0.7.1 → 0.7.4

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 } : {}),
       };
     }
@@ -896,6 +897,9 @@ async function serveMcp(
     activity,
     defaultToolTimeoutMs: opts.defaultToolTimeoutMs,
     probeTimeoutMs: opts.probeTimeoutMs,
+    ...(runtimeContext
+      ? { defer: runtimeContext.waitUntil.bind(runtimeContext) }
+      : {}),
   });
   if (opts.executor) {
     registerExecuteTool(server, registry, {
@@ -903,6 +907,7 @@ async function serveMcp(
       executor: opts.executor,
       logger: opts.logger,
       activity,
+      requestSignal: request.signal,
     });
   }
   const transport = new WebStandardStreamableHTTPServerTransport({
@@ -1044,6 +1049,9 @@ export function createFetchHandler(
     const url = new URL(request.url);
     const baseUrl = publicUrl ?? url.origin;
     const path = url.pathname;
+    const defer = runtimeContext
+      ? runtimeContext.waitUntil.bind(runtimeContext)
+      : undefined;
 
     /**
      * Piggyback a DUE credential liveness sweep on traffic that has already been
@@ -1059,7 +1067,7 @@ export function createFetchHandler(
       // throws while deciding whether anything is due. Nothing about a
       // background health check may turn a served request into a 500.
       try {
-        const sweep = registry.sweepCredentialHealthIfDue(baseUrl);
+        const sweep = registry.sweepCredentialHealthIfDue(baseUrl, defer);
         if (!sweep) return;
         const settled = sweep.then(
           () => {},
@@ -1067,7 +1075,7 @@ export function createFetchHandler(
             opts.logger.warn("[connecta] credential health sweep failed", err);
           },
         );
-        if (runtimeContext?.waitUntil) runtimeContext.waitUntil(settled);
+        if (defer) defer(settled);
         else void settled;
       } catch (err) {
         opts.logger.warn("[connecta] credential health sweep failed", err);
@@ -1197,7 +1205,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 +1220,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 +1245,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 +1262,8 @@ export function createFetchHandler(
           eligibleClerkOperator ? opts.credentialVault : undefined,
           Boolean(opts.activity?.list),
           credentialManagement,
+          opts.toolkits,
+          defer,
         );
         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;
 }
 
@@ -264,6 +264,23 @@ export interface ExecutorProvider {
  */
 export interface Executor {
   execute(code: string, providers: ExecutorProvider[]): Promise<ExecuteResult>;
+  /** Release runtime resources. Node's built-in pool implements this. */
+  close?(): void | Promise<void>;
+}
+
+/**
+ * Optional admission capability used by bounded executors. The acquired lease
+ * carries execution so an already-admitted caller cannot accidentally acquire
+ * a second slot and deadlock a pool of one.
+ */
+export interface AdmittingExecutor extends Executor {
+  acquire(options?: { signal?: AbortSignal }): Promise<ExecutorLease>;
+}
+
+export interface ExecutorLease {
+  execute(code: string, providers: ExecutorProvider[]): Promise<ExecuteResult>;
+  /** Idempotent. Call from finally even when provider construction fails. */
+  release(): void;
 }
 
 /**

package/src/ui.ts

@@ -4,8 +4,12 @@ import {
   storedCredentialShape,
 } from "./credentials.js";
 import type { CredentialVault } from "./credentials.js";
-import { closeConnectorScope } from "./connector-scope.js";
+import {
+  closeConnectorScope,
+  type DeferredWork,
+} from "./connector-scope.js";
 import type { Registry } from "./registry.js";
+import type { Toolkit } from "./toolkits.js";
 import type { ConnectaBranding, UiAuthConfig } from "./types.js";
 
 /** Connecta's default monochrome "C" mark. */
@@ -296,10 +300,21 @@ export interface UiConnector {
 export interface UiData {
   serverInfo: { name: string; version: string };
   connectors: UiConnector[];
+  /** Read-only projection of the validated deployment config. */
+  toolkits: UiToolkit[];
   activityEnabled: boolean;
   credentialManagement: CredentialManagementCapability;
 }
 
+export interface UiToolkit {
+  name: string;
+  connectors: string[];
+  includeTools: string[];
+  excludeTools: string[];
+  /** Tools currently loaded through healthy connectors and visible in this view. */
+  toolCount: number;
+}
+
 export type CredentialManagementCapability =
   | "available"
   | "requires_clerk"
@@ -391,10 +406,12 @@ export async function buildUiData(
   credentialManagement: CredentialManagementCapability = credentialVault
     ? "available"
     : "requires_clerk",
+  toolkits?: ReadonlyMap<string, Toolkit>,
+  defer?: DeferredWork,
 ): Promise<UiData> {
   const requestScope = {};
   const connectorSet = registry.listConnectors();
-  const connectors = await Promise.all(
+  const settled = await Promise.allSettled(
     connectorSet.map(async (c): Promise<UiConnector> => {
       const status = await registry.statusFor(c.id, baseUrl, requestScope);
       const credentialCheck = await registry.credentialHealthFor(c.id);
@@ -530,19 +547,42 @@ export async function buildUiData(
         ...(credential ? { credential } : {}),
       };
     }),
-  ).finally(async () => {
-    await Promise.all(
-      connectorSet.map((connector) =>
-        closeConnectorScope(
-          connector,
-          registry.contextFor(connector.id, baseUrl, requestScope),
-        ),
+  );
+  await Promise.all(
+    connectorSet.map((connector) =>
+      closeConnectorScope(
+        connector,
+        registry.contextFor(connector.id, baseUrl, requestScope),
+        defer,
       ),
-    );
+    ),
+  );
+  const connectors = settled.map((result) => {
+    if (result.status === "rejected") throw result.reason;
+    return result.value;
   });
+  const toolkitData: UiToolkit[] = [...(toolkits?.values() ?? [])].map(
+    (toolkit) => ({
+      name: toolkit.name,
+      connectors: [...toolkit.connectors],
+      includeTools: [...toolkit.includeTools],
+      excludeTools: [...toolkit.excludeTools],
+      toolCount: connectors.reduce(
+        (count, connector) =>
+          count +
+          (toolkit.hasConnector(connector.id)
+            ? connector.tools.filter((tool) =>
+                toolkit.hasTool(connector.id, tool.name),
+              ).length
+            : 0),
+        0,
+      ),
+    }),
+  );
   return {
     serverInfo,
     connectors,
+    toolkits: toolkitData,
     activityEnabled,
     credentialManagement,
   };
@@ -876,6 +916,56 @@ ${clerkScript}
   .connector-description { margin-top: .25rem; max-width: 40rem; }
   .connector-message,
   .connector-auth { margin-top: .75rem; }
+  .connector-toolkits {
+    align-items: baseline;
+    display: flex;
+    flex-wrap: wrap;
+    gap: .25rem .5rem;
+    margin-top: .5rem;
+  }
+  .scope-label {
+    border: 1px solid var(--rule);
+    display: inline-block;
+    font-family: var(--mono);
+    font-size: .72rem;
+    padding: .05rem .35rem;
+  }
+
+  .toolkit-copy { margin-bottom: 1rem; max-width: 42rem; }
+  .toolkit-ledger { border-bottom: 1px solid var(--rule); }
+  .toolkit-card {
+    border-top: 1px solid var(--rule);
+    padding: .9rem 0 1rem;
+  }
+  .toolkit-head {
+    display: grid;
+    gap: var(--gap);
+    grid-template-columns: minmax(0, 2fr) minmax(10rem, 1fr);
+  }
+  .toolkit-name {
+    align-items: baseline;
+    display: flex;
+    flex-wrap: wrap;
+    gap: .5rem;
+  }
+  .toolkit-name h3 { overflow-wrap: anywhere; }
+  .toolkit-state { text-align: right; }
+  .toolkit-connectors {
+    display: flex;
+    flex-wrap: wrap;
+    gap: .5rem;
+    margin-top: .75rem;
+  }
+  .toolkit-connector {
+    border-left: 1px solid var(--ink);
+    display: inline-flex;
+    flex-wrap: wrap;
+    gap: .4rem;
+    padding-left: .5rem;
+  }
+  .toolkit-rules { margin-top: .75rem; }
+  .toolkit-rules > * + * { margin-top: .25rem; }
+  .toolkit-endpoint { margin-top: .75rem; }
 
   .credential-ledger { border-bottom: 1px solid var(--rule); }
   .credential-card { border-top: 1px solid var(--rule); padding-bottom: .75rem; padding-top: .75rem; }
@@ -991,9 +1081,11 @@ ${clerkScript}
     .section,
     .section + .section { margin-top: 2.5rem; }
     .connector-head,
+    .toolkit-head,
     .tool,
     .activity-item { grid-template-columns: 1fr; }
-    .connector-state { text-align: left; }
+    .connector-state,
+    .toolkit-state { text-align: left; }
     .credential-field { align-items: start; grid-template-columns: 1fr; gap: .25rem; }
     input { min-height: 2.75rem; }
   }
@@ -1068,6 +1160,16 @@ ${clerkScript}
         <div id="list" class="connector-tools" aria-busy="false"></div>
       </div>
     </section>
+    <section class="section pgrid" aria-labelledby="toolkitLedgerHeading">
+      <h2 class="pcap" id="toolkitLedgerHeading">Toolkits</h2>
+      <div class="pbody">
+        <p class="toolkit-copy meta">
+          Read-only views from deployment config. Change the config and redeploy
+          to update them.
+        </p>
+        <div id="toolkitList" class="toolkit-ledger"></div>
+      </div>
+    </section>
   </section>
 
   <section id="credentialsView"${page === "credentials" ? "" : ' class="hidden"'}>
@@ -1129,6 +1231,7 @@ let ACTIVITY_LOADED = false;
 let CURRENT_PAGE = INITIAL_PAGE;
 let SESSION_GENERATION = 0;
 let ACTIVITY_GENERATION = 0;
+let CLERK_SESSION_ID = null;
 $("mcpUrl").textContent = MCP_URL;
 
 function esc(s) {
@@ -1184,6 +1287,7 @@ function clearIdentityState() {
   DATA = null;
   clearActivityState();
   $("list").innerHTML = "";
+  $("toolkitList").innerHTML = "";
   $("filter").value = "";
   $("credentialList").innerHTML = "";
   $("credentialList").setAttribute("aria-busy", "false");
@@ -1267,7 +1371,10 @@ function activatePage(page, options) {
       loadActivity(true);
     }
   }
-  if (next !== "credentials") $("credentialList").innerHTML = "";
+  if (next !== "credentials") {
+    $("credentialList").innerHTML = "";
+    setNotice("");
+  }
   // Focus what is actually on screen. While gated the page views are hidden, so
   // focusing their heading is a silent no-op that drops focus to <body> and
   // restarts the next Tab from the top of the document — the gate's own h1 is
@@ -1452,6 +1559,71 @@ async function loadActivity(reset) {
   }
 }
 
+function toolkitMcpUrl(name) {
+  const url = new URL(MCP_URL, window.location.href);
+  url.searchParams.set("toolkit", name);
+  return url.toString();
+}
+
+function renderToolkits() {
+  const list = $("toolkitList");
+  const toolkits = DATA.toolkits || [];
+  list.innerHTML = "";
+  if (!toolkits.length) {
+    list.innerHTML =
+      '<p class="empty">No toolkits are configured. Unscoped clients see the full connector registry.</p>';
+    return;
+  }
+  const connectors = new Map(
+    DATA.connectors.map((connector) => [connector.id, connector]),
+  );
+  for (const toolkit of toolkits) {
+    const el = document.createElement("article");
+    el.className = "toolkit-card";
+    const connectorCount = toolkit.connectors.length;
+    const toolCount = toolkit.toolCount || 0;
+    let body =
+      '<div class="toolkit-head"><div><div class="toolkit-name">' +
+      '<h3 class="mono">' + esc(toolkit.name) + "</h3>" +
+      '<span class="cap">configured view</span></div>';
+    body += '</div><div class="toolkit-state cap">' +
+      connectorCount + (connectorCount === 1 ? " connector" : " connectors") +
+      " · " + toolCount + (toolCount === 1 ? " loaded tool" : " loaded tools") +
+      "</div></div>";
+    body += '<ul class="toolkit-connectors" aria-label="Included connectors">';
+    for (const id of toolkit.connectors) {
+      const connector = connectors.get(id);
+      body += '<li class="toolkit-connector"><span>' +
+        esc(connector?.title || id) + '</span><code class="mono">' +
+        esc(id) + "</code></li>";
+    }
+    body += "</ul>";
+    body += '<div class="toolkit-rules meta">';
+    if (toolkit.includeTools.length) {
+      body += '<p>Per-connector allowlist: <span class="mono">' +
+        toolkit.includeTools.map(esc).join('</span>, <span class="mono">') +
+        "</span>. Connectors without an allowlist keep all tools.</p>";
+    }
+    if (toolkit.excludeTools.length) {
+      body += '<p>Hidden: <span class="mono">' +
+        toolkit.excludeTools.map(esc).join('</span>, <span class="mono">') +
+        "</span></p>";
+    }
+    if (!toolkit.includeTools.length && !toolkit.excludeTools.length) {
+      body += "<p>All tools on the included connectors are visible.</p>";
+    }
+    body += "</div>";
+    const endpoint = toolkitMcpUrl(toolkit.name);
+    body += '<div class="endpoint toolkit-endpoint"><div class="endpoint-row">' +
+      '<code class="mono">' + esc(endpoint) + "</code>" +
+      '<button class="linklike" type="button" data-toolkit-copy="' +
+      esc(toolkit.name) + '" aria-label="Copy endpoint for ' +
+      esc(toolkit.name) + '">Copy URL</button></div></div>';
+    el.innerHTML = body;
+    list.appendChild(el);
+  }
+}
+
 function renderConnections() {
   const q = $("filter").value.trim().toLowerCase();
   const list = $("list");
@@ -1472,6 +1644,15 @@ function renderConnections() {
     if (c.description) {
       head += '<p class="connector-description meta">' + esc(c.description) + "</p>";
     }
+    const memberships = (DATA.toolkits || [])
+      .filter((toolkit) => toolkit.connectors.includes(c.id))
+      .map((toolkit) => toolkit.name);
+    if (memberships.length) {
+      head += '<div class="connector-toolkits meta"><span>Toolkits</span>' +
+        memberships.map((name) =>
+          '<span class="scope-label">' + esc(name) + "</span>"
+        ).join("") + "</div>";
+    }
     head += '</div><div class="connector-state cap">' + esc(status) + " · " +
       c.toolCount + (c.toolCount === 1 ? " tool" : " tools") +
       '<br><span class="mono">' + esc(c.id) + "</span></div></div>";
@@ -1525,6 +1706,7 @@ function renderConnections() {
         : "No connectors are declared in this deployment.") +
       "</p>";
   }
+  renderToolkits();
 }
 
 function renderCredentials() {
@@ -1771,6 +1953,19 @@ $("copyMcpUrl").onclick = async () => {
   }
   window.setTimeout(() => { button.textContent = "Copy URL"; }, 1600);
 };
+$("toolkitList").onclick = async (event) => {
+  const button = event.target.closest("[data-toolkit-copy]");
+  if (!button) return;
+  try {
+    await navigator.clipboard.writeText(
+      toolkitMcpUrl(button.dataset.toolkitCopy),
+    );
+    button.textContent = "Copied";
+  } catch (e) {
+    button.textContent = "Copy failed";
+  }
+  window.setTimeout(() => { button.textContent = "Copy URL"; }, 1600);
+};
 $("signin").onclick = () => Clerk.redirectToSignIn({
   signInFallbackRedirectUrl: window.location.href,
   signUpFallbackRedirectUrl: window.location.href,
@@ -1820,6 +2015,17 @@ async function init() {
         signUpFallbackRedirectUrl: window.location.href,
         afterSignOutUrl: window.location.href,
       });
+      CLERK_SESSION_ID = Clerk.session?.id ?? null;
+      Clerk.addListener((resources) => {
+        const nextSessionId = resources.session?.id ?? null;
+        if (nextSessionId === CLERK_SESSION_ID) return;
+        CLERK_SESSION_ID = nextSessionId;
+        // Clerk has already updated its public session before notifying
+        // listeners. Clear synchronously so stale identity-scoped data cannot
+        // be repainted while the replacement identity is being fetched.
+        showGate("");
+        void load();
+      });
     } catch (e) {
       return showGate("Clerk could not initialize: " + e.message);
     }

package/src/version.ts

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.7.1";
+export const CONNECTA_VERSION = "0.7.4";