@zackbart/connecta 0.5.0 → 0.6.1

package/src/server.ts

@@ -10,9 +10,17 @@ import type {
   ActivityStore,
 } from "./activity.js";
 import { InvalidActivityCursorError } from "./activity.js";
+import {
+  credentialTestRule,
+  describeCredentialTestMismatch,
+} from "./credentials.js";
 import type { CredentialVault } from "./credentials.js";
 import { ScopedRegistry, type Registry, type RegistryView } from "./registry.js";
-import { TOOLKIT_NAME_RE, type Toolkit } from "./toolkits.js";
+import {
+  resolveIdentityBinding,
+  TOOLKIT_NAME_RE,
+  type Toolkit,
+} from "./toolkits.js";
 import type {
   ConnectorCredentialConfig,
   ConnectorCredentialValues,
@@ -20,6 +28,7 @@ import type {
   Executor,
   InboundAuth,
   Logger,
+  ToolkitBinding,
 } from "./types.js";
 import { CONNECTA_FAVICON_ICO } from "./favicon.js";
 import {
@@ -36,6 +45,35 @@ const CORS_HEADERS = {
     "Content-Type, Authorization, mcp-protocol-version, mcp-session-id",
 };
 
+/**
+ * Headers that make an operator-supplied favicon body inert on this origin.
+ * The SVG route is the sharp one: `image/svg+xml` is an *active* content type,
+ * so a `<script>` inside a branding SVG would run on the deployment origin the
+ * moment anyone navigated straight to `/favicon.svg` — strictly more powerful
+ * than the `favicon.href` vector the branding gates close, because the payload
+ * is same-origin. Neutralizing the response rather than inspecting the body
+ * keeps every valid static SVG (the built-in mark included) byte-identical:
+ *
+ * - `sandbox` (no tokens ⇒ every restriction) drops the document into an opaque
+ *   origin with scripting off, so even a script that ran would have nothing to
+ *   reach.
+ * - `default-src 'none'` denies script, network, and framing outright.
+ * - `style-src 'unsafe-inline'` is the single allowance: the default mark styles
+ *   itself inline to follow the OS colour scheme, and CSS cannot script.
+ * - `nosniff` keeps the declared type authoritative in both directions — an SVG
+ *   can never be re-read as HTML, and `.ico` bytes can never be re-read as SVG.
+ *
+ * `.ico` bodies are deliberately in scope: they are inert bytes rather than
+ * active content, so they are still served verbatim, but they carry the same
+ * headers so the invariant is "every favicon route is neutralized" rather than
+ * "whichever route got attention".
+ */
+const INERT_ICON_HEADERS = {
+  "Content-Security-Policy":
+    "default-src 'none'; style-src 'unsafe-inline'; sandbox",
+  "X-Content-Type-Options": "nosniff",
+};
+
 export interface ServerOptions {
   registry: Registry;
   auth: InboundAuth[];
@@ -161,16 +199,29 @@ function html(
   );
 }
 
+/**
+ * Refusal for an identity whose toolkit binding cannot be trusted — a malformed
+ * declaration, or a malformed per-identity binding out of `authorize`. The
+ * caller is authenticated, so this is a 403, and it is deliberately opaque: the
+ * cause is an operator bug, and the operator reads it in the log, not the client.
+ */
+function unusableBinding(): Response {
+  return privateJson({ error: "forbidden" }, { status: 403 });
+}
+
 async function authorize(
   request: Request,
   baseUrl: string,
   auth: InboundAuth[],
+  logger: Logger,
 ): Promise<
   | {
       ok: true;
       actor: ActivityActor;
       providerKind?: string;
       userId?: string;
+      /** The admitting identity's toolkit binding, if it has one (§16). */
+      toolkitBinding?: ToolkitBinding;
     }
   | { ok: false; response: Response }
 > {
@@ -182,6 +233,24 @@ async function authorize(
     const result = await provider.authorize(request, baseUrl);
     if (result.ok) {
       const subjectId = result.subjectId ?? result.userId;
+      // Re-validate both halves and cap the per-identity one by the provider's
+      // declaration (see resolveIdentityBinding). A binding that does not
+      // type-check at runtime refuses the request rather than evaporating:
+      // dropping it would hand the caller the full registry, which is the one
+      // outcome a binding exists to prevent.
+      const binding = resolveIdentityBinding(
+        provider.toolkitBinding,
+        result.toolkitBinding,
+      );
+      if (!binding.ok) {
+        logger.warn(
+          `[connecta] refused a request admitted by inbound auth provider ` +
+            `"${provider.kind}" with 403: ${binding.reason}. Until it is fixed ` +
+            "this provider cannot admit anyone, because connecta cannot tell " +
+            "which toolkits the identity may use.",
+        );
+        return { ok: false, response: unusableBinding() };
+      }
       return {
         ok: true,
         actor: {
@@ -190,6 +259,7 @@ async function authorize(
         },
         providerKind: provider.kind,
         ...(result.userId ? { userId: result.userId } : {}),
+        ...(binding.binding ? { toolkitBinding: binding.binding } : {}),
       };
     }
     lastResponse = result.response;
@@ -266,12 +336,23 @@ async function authorizeUiAdmin(
   request: Request,
   baseUrl: string,
   auth: InboundAuth[],
+  logger: Logger,
 ): Promise<{ ok: true; userId: string } | { ok: false; response: Response }> {
-  // Credential mutation is intentionally narrower than /mcp and /ui/data:
-  // only the interactive Clerk provider may admit it. A static bearer token is
-  // useful for headless tool calls but must not become a vault-admin key.
-  const provider = auth.find((candidate) => candidate.uiAuth?.kind === "clerk");
-  if (!provider) {
+  // Credential mutation is intentionally narrower than /mcp and /ui/data: only
+  // an interactive Clerk provider may admit it. A static bearer token is useful
+  // for headless tool calls but must not become a vault-admin key.
+  //
+  // EVERY Clerk provider gets a turn, the way the /mcp gate does, because the
+  // documented per-team pattern is several `clerkAuth(...)`s that differ only in
+  // `gate` and `toolkits` (§16). Stopping at the first would make admission
+  // depend on config order: the team-bound provider listed first would refuse
+  // the operator outright, and a refusal here — a failed gate, a missing user, a
+  // toolkit-bound identity — is exactly the case where a later provider is the
+  // one meant to admit. The last refusal is returned if none do.
+  const providers = auth.filter(
+    (candidate) => candidate.uiAuth?.kind === "clerk",
+  );
+  if (providers.length === 0) {
     return {
       ok: false,
       response: privateJson(
@@ -280,18 +361,46 @@ async function authorizeUiAdmin(
       ),
     };
   }
-  const result = await provider.authorize(request, baseUrl);
-  if (!result.ok) return result;
-  if (!result.userId) {
-    return {
-      ok: false,
-      response: privateJson(
+  let lastResponse: Response | null = null;
+  for (const provider of providers) {
+    const result = await provider.authorize(request, baseUrl);
+    if (!result.ok) {
+      lastResponse = result.response;
+      continue;
+    }
+    if (!result.userId) {
+      lastResponse = privateJson(
         { error: "authenticated user required" },
         { status: 403 },
-      ),
-    };
+      );
+      continue;
+    }
+    const binding = resolveIdentityBinding(
+      provider.toolkitBinding,
+      result.toolkitBinding,
+    );
+    if (!binding.ok) {
+      logger.warn(
+        `[connecta] refused a credential-API request admitted by inbound auth ` +
+          `provider "${provider.kind}" with 403: ${binding.reason}.`,
+      );
+      lastResponse = unusableBinding();
+      continue;
+    }
+    // A toolkit-bound identity is a team's credential, not a vault admin key:
+    // credentials are deployment-wide, so writing one reaches every toolkit.
+    if (isToolkitRestricted(binding.binding)) {
+      lastResponse = restrictedOperatorSurface();
+      continue;
+    }
+    return { ok: true, userId: result.userId };
   }
-  return { ok: true, userId: result.userId };
+  return {
+    ok: false,
+    response:
+      lastResponse ??
+      privateJson({ error: "forbidden" }, { status: 403 }),
+  };
 }
 
 function isSameOrigin(request: Request, baseUrl: string): boolean {
@@ -424,7 +533,12 @@ async function handleCredentialRequest(
       { status: 403 },
     );
   }
-  const admin = await authorizeUiAdmin(request, baseUrl, opts.auth);
+  const admin = await authorizeUiAdmin(
+    request,
+    baseUrl,
+    opts.auth,
+    opts.logger,
+  );
   if (!admin.ok) return admin.response;
 
   const connector = opts.registry.getConnector(connectorId);
@@ -436,16 +550,25 @@ async function handleCredentialRequest(
     if (request.method !== "POST") {
       return privateJson({ error: "method not allowed" }, { status: 405 });
     }
-    if (!connector.testCredential && !connector.testCredentials) {
+    // The declared credential shape picks the hook — the same single rule /ui
+    // asks for its Test affordance, so a shown button always reaches a hook
+    // that reads the shape the credential was stored in.
+    const rule = credentialTestRule(connector);
+    if (!rule.mode) {
       return privateJson(
-        { error: "this connector does not support credential testing" },
+        {
+          error: rule.mismatch
+            ? "this connector cannot test its credential: " +
+              describeCredentialTestMismatch(rule.mismatch)
+            : "this connector does not support credential testing",
+        },
         { status: 400 },
       );
     }
     try {
       const ctx = opts.registry.contextFor(connectorId, baseUrl);
       let result;
-      if (connector.testCredentials) {
+      if (rule.mode === "multiple") {
         const values = await opts.credentialVault.getAll(connectorId);
         if (!values) {
           return privateJson(
@@ -453,7 +576,7 @@ async function handleCredentialRequest(
             { status: 409 },
           );
         }
-        result = await connector.testCredentials(values, ctx);
+        result = await connector.testCredentials!(values, ctx);
       } else {
         const value = await opts.credentialVault.get(connectorId);
         if (!value) {
@@ -464,6 +587,13 @@ async function handleCredentialRequest(
         }
         result = await connector.testCredential!(value, ctx);
       }
+      // The operator just ran the very check the liveness sweep runs; record it
+      // so the cached status surfaces agree with what /ui just showed them.
+      await opts.registry.recordCredentialHealth(connectorId, {
+        state: result.ok ? "ok" : "auth_required",
+        checkedAt: new Date().toISOString(),
+        ...(result.message ? { message: result.message } : {}),
+      });
       return privateJson(result);
     } catch (err) {
       return privateJson({ ok: false, message: msg(err) });
@@ -491,6 +621,9 @@ async function handleCredentialRequest(
               admin.userId,
             );
       opts.registry.invalidate(connectorId);
+      // The credential the last verdict judged is gone; judging its replacement
+      // is the next check's job, not this one's.
+      await opts.registry.clearCredentialHealth(connectorId);
       return privateJson({ credential: metadata });
     } catch (err) {
       return privateJson({ error: msg(err) }, { status: 400 });
@@ -500,6 +633,7 @@ async function handleCredentialRequest(
   if (request.method === "DELETE") {
     await opts.credentialVault.delete(connectorId);
     opts.registry.invalidate(connectorId);
+    await opts.registry.clearCredentialHealth(connectorId);
     return new Response(null, {
       status: 204,
       headers: {
@@ -523,35 +657,150 @@ interface McpScope {
 }
 
 /**
- * Resolve `?toolkit=<name>` into the registry view this connection may see.
+ * Bounded, escaped form of a caller-influenced value (a rejected toolkit name,
+ * an identity id) for the operator log. Goes through JSON.stringify so a
+ * caller-controlled newline or control character cannot forge a log line, plus a
+ * hand-rolled escape for U+2028/U+2029, which JSON.stringify leaves raw even
+ * though a log reader treats them as line terminators. Truncated to the same
+ * length the response body echoes at, so an oversized value cannot flood the log
+ * either.
+ */
+function loggableValue(requested: string): string {
+  const bounded = requested.slice(0, MAX_ECHOED_TOOLKIT_NAME);
+  const escaped = JSON.stringify(bounded).replace(
+    /[\u2028\u2029]/g,
+    (ch) => `\\u${ch.charCodeAt(0).toString(16)}`,
+  );
+  return escaped + (bounded.length < requested.length ? " (truncated)" : "");
+}
+
+/** The one refusal a bound identity ever sees. Constant on purpose — see below. */
+const TOOLKIT_FORBIDDEN_BODY = JSON.stringify({
+  jsonrpc: "2.0",
+  id: null,
+  error: {
+    code: -32600,
+    message:
+      "Not permitted to use the requested toolkit. This credential is bound " +
+      "to a specific toolkit — check the ?toolkit= value in this deployment's " +
+      "MCP endpoint URL with the operator.",
+  },
+});
+
+/**
+ * 403 for every binding refusal, with a body that does not depend on WHY.
+ *
+ * A bound identity asking for a toolkit it may not open, for a toolkit that does
+ * not exist, or for no toolkit at all gets byte-identical responses, so a team
+ * credential cannot be used to enumerate the org's other teams — the boundary
+ * would leak the very structure it exists to hide. The operator log below is
+ * where the three cases are told apart.
+ */
+function toolkitForbidden(): Response {
+  return new Response(TOOLKIT_FORBIDDEN_BODY, {
+    status: 403,
+    headers: {
+      "Content-Type": "application/json",
+      "Cache-Control": "no-store",
+    },
+  });
+}
+
+/** How a rejected connection is named in the operator log. */
+function identityLabel(actor: ActivityActor): string {
+  return actor.id ? `${actor.kind} ${loggableValue(actor.id)}` : actor.kind;
+}
+
+/**
+ * Resolve `?toolkit=<name>` into the registry view this connection may see,
+ * enforcing the caller's toolkit binding (§16) on the way.
+ *
+ * For an UNBOUND identity (no binding configured — the pre-#37 shape):
  *
  * - absent → the full registry, byte-identical to a deployment with no toolkits
- * - known → a `ScopedRegistry` over that toolkit (the one enforcement point)
+ * - known → a `ScopedRegistry` over that toolkit (the one visibility boundary)
  * - anything else, including `?toolkit=` with an empty value → an explicit
- *   error. Never a silent fallback to the full registry.
+ *   404. Never a silent fallback to the full registry.
  *
- * The error deliberately does not enumerate the configured toolkits: the name
- * selects a scope, so a wrong guess gets a flat "unknown", not a directory.
+ * For a BOUND identity, membership is checked FIRST and refusal is a flat 403:
+ * a toolkit outside the binding, an unknown name, and (without `unscoped`) an
+ * omitted `?toolkit=` are all refused before any `ScopedRegistry` is built, and
+ * all three produce the same response.
+ *
+ * Neither error enumerates the configured toolkits: the name selects a scope, so
+ * a wrong guess gets a flat refusal, not a directory.
+ *
+ * Because of that — and because SDK clients treat a 404/403 on the transport
+ * endpoint as a transport failure and discard the body — every rejection is also
+ * logged operator-side (issue #47), which is the channel that actually reaches a
+ * human. The log line may name the configured or bound toolkits; the response
+ * still may not.
  */
 function resolveToolkitScope(
   url: URL,
   registry: Registry,
   toolkits: ReadonlyMap<string, Toolkit> | undefined,
+  logger: Logger,
+  identity: { actor: ActivityActor; binding?: ToolkitBinding },
 ):
   | { ok: true; scope: McpScope }
   | { ok: false; response: Response } {
   const requested = url.searchParams.get("toolkit");
+  const binding = identity.binding;
+  const scopeFor = (toolkit: Toolkit) => ({
+    ok: true as const,
+    scope: {
+      registry: new ScopedRegistry(registry, toolkit),
+      toolkitId: toolkit.name,
+    },
+  });
+
+  if (binding) {
+    const who = identityLabel(identity.actor);
+    const bound = `Bound toolkits: ${binding.toolkits.join(", ") || "(none)"}${
+      binding.unscoped ? ", plus unscoped access" : ""
+    }.`;
+    if (requested === null) {
+      if (binding.unscoped) return { ok: true, scope: { registry } };
+      logger.warn(
+        `[connecta] refused an unscoped /mcp connection from ${who} with 403: ` +
+          "its toolkit binding does not allow the full registry. " +
+          bound +
+          " The client sees a transport-level failure and never the reason, so " +
+          "give it an MCP endpoint URL with a ?toolkit= value it is bound to.",
+      );
+      return { ok: false, response: toolkitForbidden() };
+    }
+    const permitted = binding.toolkits.includes(requested);
+    const toolkit = permitted ? toolkits?.get(requested) : undefined;
+    if (toolkit) return scopeFor(toolkit);
+    logger.warn(
+      `[connecta] refused an /mcp connection from ${who} with 403: it asked ` +
+        `for toolkit ${loggableValue(requested)}, which ` +
+        (permitted
+          ? "its binding allows but this deployment does not configure"
+          : "its toolkit binding does not include") +
+        ". " +
+        bound +
+        " The client sees a transport-level failure and never the reason, so " +
+        "check the ?toolkit= value in its MCP endpoint URL.",
+    );
+    return { ok: false, response: toolkitForbidden() };
+  }
+
   if (requested === null) return { ok: true, scope: { registry } };
   const toolkit = toolkits?.get(requested);
-  if (toolkit) {
-    return {
-      ok: true,
-      scope: {
-        registry: new ScopedRegistry(registry, toolkit),
-        toolkitId: toolkit.name,
-      },
-    };
-  }
+  if (toolkit) return scopeFor(toolkit);
+  const configured = toolkits && toolkits.size > 0 ? [...toolkits.keys()] : [];
+  logger.warn(
+    "[connecta] rejected an /mcp connection asking for unknown toolkit " +
+      `${loggableValue(requested)} with 404. ` +
+      (configured.length > 0
+        ? `Configured toolkits: ${configured.join(", ")}.`
+        : "This deployment configures no toolkits, so no ?toolkit= value is accepted.") +
+      " The client sees a transport-level failure and never the reason, so " +
+      "check the ?toolkit= value in its MCP endpoint URL.",
+  );
   const label =
     requested.length <= MAX_ECHOED_TOOLKIT_NAME &&
     TOOLKIT_NAME_RE.test(requested)
@@ -581,6 +830,29 @@ function resolveToolkitScope(
   };
 }
 
+/**
+ * True when this identity is confined to one or more toolkits — bound, without
+ * `unscoped`. Such a credential belongs to a team's agent, not to the operator
+ * running the deployment, so the deployment-wide operator surfaces (`/ui/data`,
+ * `/ui/activity`, the credential API) refuse it: their payloads describe every
+ * connector in the org, which is exactly what the binding exists to withhold.
+ */
+function isToolkitRestricted(binding: ToolkitBinding | undefined): boolean {
+  return Boolean(binding && !binding.unscoped);
+}
+
+/** The refusal the deployment-wide operator surfaces give a bound identity. */
+function restrictedOperatorSurface(): Response {
+  return privateJson(
+    {
+      error:
+        "this credential is bound to a toolkit and may not read " +
+        "deployment-wide operator data",
+    },
+    { status: 403 },
+  );
+}
+
 async function serveMcp(
   request: Request,
   opts: ServerOptions,
@@ -666,6 +938,10 @@ async function handleOAuthCallback(
   try {
     await connector.finishAuth(code, context);
     await registry.invalidateStored(id);
+    // Recovery, without a restart: the grant this connector was reported dead
+    // for has just been replaced, so drop the verdict rather than let a stale
+    // `auth_required` survive until the next scheduled check.
+    await registry.clearCredentialHealth(id);
     return html(
       `Connected "${id}". You can close this window.`,
       200,
@@ -691,6 +967,35 @@ export function createFetchHandler(
     const url = new URL(request.url);
     const baseUrl = publicUrl ?? url.origin;
     const path = url.pathname;
+
+    /**
+     * Piggyback a DUE credential liveness sweep on traffic that has already been
+     * authenticated (issue #24). Started beside the request and never awaited by
+     * it: it must not add latency or change a result, so it is handed to
+     * `ctx.waitUntil` where the runtime has one (Workers, and the Node adapter's
+     * shim) to settle after the response. The registry answers `undefined`
+     * unless a sweep is actually due, so the ordinary request pays nothing.
+     */
+    const sweepCredentials = (): void => {
+      // Belt and braces: a rejected sweep is already absorbed below, and this
+      // catches the synchronous half — arming the gate, or a connector list that
+      // 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);
+        if (!sweep) return;
+        const settled = sweep.then(
+          () => {},
+          (err) => {
+            opts.logger.warn("[connecta] credential health sweep failed", err);
+          },
+        );
+        if (runtimeContext?.waitUntil) runtimeContext.waitUntil(settled);
+        else void settled;
+      } catch (err) {
+        opts.logger.warn("[connecta] credential health sweep failed", err);
+      }
+    };
     // Container and orchestrator probes reach /health over plain HTTP on
     // loopback, where no proxy has set X-Forwarded-Proto. Redirecting them to
     // the public origin would make an internal liveness check depend on
@@ -770,6 +1075,7 @@ export function createFetchHandler(
           headers: {
             "Content-Type": "image/svg+xml",
             "Cache-Control": "public, max-age=86400",
+            ...INERT_ICON_HEADERS,
           },
         });
       }
@@ -779,6 +1085,7 @@ export function createFetchHandler(
           headers: {
             "Content-Type": "image/x-icon",
             "Cache-Control": "public, max-age=86400",
+            ...INERT_ICON_HEADERS,
           },
         });
       }
@@ -807,8 +1114,14 @@ export function createFetchHandler(
       }
 
       if (path === "/ui/data") {
-        const authz = await authorize(request, baseUrl, auth);
+        const authz = await authorize(request, baseUrl, auth, opts.logger);
         if (!authz.ok) return authz.response;
+        if (isToolkitRestricted(authz.toolkitBinding)) {
+          return restrictedOperatorSurface();
+        }
+        // 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 data = await buildUiData(
           registry,
           baseUrl,
@@ -827,8 +1140,11 @@ export function createFetchHandler(
         if (request.method !== "GET") {
           return privateJson({ error: "method not allowed" }, { status: 405 });
         }
-        const authz = await authorize(request, baseUrl, auth);
+        const authz = await authorize(request, baseUrl, auth, opts.logger);
         if (!authz.ok) return authz.response;
+        if (isToolkitRestricted(authz.toolkitBinding)) {
+          return restrictedOperatorSurface();
+        }
         if (
           opts.activityReadGate &&
           !(await opts.activityReadGate(authz.actor))
@@ -866,10 +1182,22 @@ export function createFetchHandler(
       if (path === "/mcp") {
         // Authenticate BEFORE resolving ?toolkit=: an unauthenticated caller
         // must not be able to probe which toolkit names exist.
-        const authz = await authorize(request, baseUrl, auth);
+        const authz = await authorize(request, baseUrl, auth, opts.logger);
         if (!authz.ok) return withMcpCors(authz.response);
-        const selected = resolveToolkitScope(url, registry, opts.toolkits);
+        const selected = resolveToolkitScope(
+          url,
+          registry,
+          opts.toolkits,
+          opts.logger,
+          {
+            actor: authz.actor,
+            ...(authz.toolkitBinding
+              ? { binding: authz.toolkitBinding }
+              : {}),
+          },
+        );
         if (!selected.ok) return withMcpCors(selected.response);
+        sweepCredentials();
         return withMcpCors(
           await serveMcp(
             request,

package/src/skills.ts

@@ -16,7 +16,7 @@ export const USAGE_SKILL = `# Connecta usage
 - Truncated result: retry with \`fields\` when possible; otherwise page it with \`get_result\`.
 - \`auth_required\`: use \`authorize_connector\`, have the operator complete consent, then confirm with \`list_connectors\`.
 
-Use \`list_connectors({ probe: false })\` for a fast inventory. Use \`probe: true\` only when diagnosing live health or authorization.
+Use \`list_connectors({ probe: false })\` for a fast inventory. Use \`probe: true\` only when diagnosing live health or authorization. The fast inventory already reports a connector whose stored credential failed a proactive check as \`auth_required\` (with \`credentialCheck\` and the URL to open), so trust it and authorize up front rather than probing to confirm.
 
 ## Code mode
 
@@ -235,12 +235,12 @@ export function resolveSkill(
     return {
       found: false,
       message: connectorGuide(bare)
-        ? `Unknown skill "${name}". Connector guides are fetched as "${connectorSkillName(name)}". Available: ${available()}.`
+        ? `Unknown skill "${name}". Connector guides are fetched as "${connectorSkillName(name)}". Available skills: ${available()}.`
         : `Connector "${name}" has no usage guide. Available skills: ${available()}.`,
     };
   }
   return {
     found: false,
-    message: `Unknown skill "${name}". Available: ${available()}.`,
+    message: `Unknown skill "${name}". Available skills: ${available()}.`,
   };
 }

package/src/timeout.ts

@@ -0,0 +1,49 @@
+// The deadline vocabulary shared by every non-call downstream probe: the
+// discovery meta-tools' catalog fan-out (src/meta-tools.ts) and the credential
+// liveness checks (src/credential-health.ts). One definition so a "probe" means
+// the same thing, and is bounded the same way, wherever one is issued.
+
+/**
+ * Generous default bound for a single downstream probe/catalog call. High enough
+ * to trip only on a pathological hang, not a realistically slow probe.
+ */
+export const DEFAULT_PROBE_TIMEOUT_MS = 30_000;
+
+/** A finite, positive integer number of milliseconds, or undefined. */
+export function normalizeTimeoutMs(
+  value: number | undefined,
+): number | undefined {
+  if (value === undefined || !Number.isFinite(value) || !(value > 0)) {
+    return undefined;
+  }
+  return Math.max(1, Math.trunc(value));
+}
+
+/**
+ * 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.
+ */
+export function withTimeout<T>(
+  promise: Promise<T>,
+  ms: number,
+  label: string,
+): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`${label} timed out after ${ms}ms`));
+    }, ms);
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (err) => {
+        clearTimeout(timer);
+        reject(err);
+      },
+    );
+  });
+}