@zackbart/connecta 0.4.0 → 0.5.0

package/src/server.ts

@@ -11,7 +11,8 @@ import type {
 } from "./activity.js";
 import { InvalidActivityCursorError } from "./activity.js";
 import type { CredentialVault } from "./credentials.js";
-import type { Registry } from "./registry.js";
+import { ScopedRegistry, type Registry, type RegistryView } from "./registry.js";
+import { TOOLKIT_NAME_RE, type Toolkit } from "./toolkits.js";
 import type {
   ConnectorCredentialConfig,
   ConnectorCredentialValues,
@@ -49,18 +50,33 @@ export interface ServerOptions {
   deploymentInfo?: Record<string, unknown>;
   /** Deadline for call_tool/batch_call calls that pass no timeoutMs. Off when unset. */
   defaultToolTimeoutMs?: number;
+  /** Per-connector deadline for the list/search/describe probe fan-out. Default 30_000. */
+  probeTimeoutMs?: number;
   /** When set, the execute_code meta-tool is registered on top of the nine. */
   executor?: Executor;
   /** Encrypted connector-credential storage backing the authenticated /ui controls. */
   credentialVault?: CredentialVault;
   /** Optional browser UI and OAuth result-page labels. */
   branding?: ConnectaBranding;
+  /**
+   * Validated named scopes, selected per connection with `?toolkit=<name>` on
+   * `/mcp`. Omit (or leave empty) and every connection sees the full registry.
+   */
+  toolkits?: ReadonlyMap<string, Toolkit>;
 }
 
 function msg(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
+/** Per-request base64 nonce for the /ui page's inline scripts (Node 20+ and Workers). */
+function uiScriptNonce(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
 function escapeHtml(s: string): string {
   return s
     .replaceAll("&", "&amp;")
@@ -231,9 +247,12 @@ function withSecurityHeaders(
     headers.set("Strict-Transport-Security", "max-age=31536000");
   }
   if (path === "/ui") {
-    // A directive-only CSP does not interfere with the UI's existing scripts,
-    // while preventing the authenticated operator surface from being framed.
-    headers.set("Content-Security-Policy", "frame-ancestors 'none'");
+    // The /ui GET response ships its own nonce-based script CSP (which already
+    // includes frame-ancestors 'none'); only fall back to the framing-only
+    // directive when no CSP is present (e.g. HTTPS redirects, error responses).
+    if (!headers.has("Content-Security-Policy")) {
+      headers.set("Content-Security-Policy", "frame-ancestors 'none'");
+    }
     headers.set("X-Frame-Options", "DENY");
   }
   return new Response(response.body, {
@@ -493,11 +512,81 @@ async function handleCredentialRequest(
   return privateJson({ error: "method not allowed" }, { status: 405 });
 }
 
+/** Length beyond which a rejected toolkit name is not echoed back. */
+const MAX_ECHOED_TOOLKIT_NAME = 64;
+
+/** What one MCP connection may see: the full registry, or one toolkit's view. */
+interface McpScope {
+  registry: RegistryView;
+  /** Set only under `?toolkit=`; recorded on activity events. */
+  toolkitId?: string;
+}
+
+/**
+ * Resolve `?toolkit=<name>` into the registry view this connection may see.
+ *
+ * - absent → the full registry, byte-identical to a deployment with no toolkits
+ * - known → a `ScopedRegistry` over that toolkit (the one enforcement point)
+ * - anything else, including `?toolkit=` with an empty value → an explicit
+ *   error. 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.
+ */
+function resolveToolkitScope(
+  url: URL,
+  registry: Registry,
+  toolkits: ReadonlyMap<string, Toolkit> | undefined,
+):
+  | { ok: true; scope: McpScope }
+  | { ok: false; response: Response } {
+  const requested = url.searchParams.get("toolkit");
+  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,
+      },
+    };
+  }
+  const label =
+    requested.length <= MAX_ECHOED_TOOLKIT_NAME &&
+    TOOLKIT_NAME_RE.test(requested)
+      ? `"${requested}"`
+      : "requested";
+  return {
+    ok: false,
+    response: new Response(
+      JSON.stringify({
+        jsonrpc: "2.0",
+        id: null,
+        error: {
+          code: -32600,
+          message:
+            `Unknown toolkit ${label}. Check the ?toolkit= value in this ` +
+            "deployment's MCP endpoint URL with the operator.",
+        },
+      }),
+      {
+        status: 404,
+        headers: {
+          "Content-Type": "application/json",
+          "Cache-Control": "no-store",
+        },
+      },
+    ),
+  };
+}
+
 async function serveMcp(
   request: Request,
   opts: ServerOptions,
   baseUrl: string,
   actor: ActivityActor,
+  scope: McpScope,
   runtimeContext?: RuntimeExecutionContext,
 ): Promise<Response> {
   // Fresh McpServer + transport per request (SDK ≥1.26 requirement), stateless.
@@ -513,19 +602,24 @@ async function serveMcp(
         ...(opts.activityDeploymentId
           ? { deploymentId: opts.activityDeploymentId }
           : {}),
+        ...(scope.toolkitId ? { toolkitId: scope.toolkitId } : {}),
         ...(runtimeContext?.waitUntil
           ? { defer: runtimeContext.waitUntil.bind(runtimeContext) }
           : {}),
         logger: opts.logger,
       }
     : undefined;
-  registerMetaTools(server, opts.registry, {
+  // `scope.registry` is the connection's VIEW — the full registry, or one
+  // toolkit's ScopedRegistry. Nothing below may reach for `opts.registry`.
+  const registry = scope.registry;
+  registerMetaTools(server, registry, {
     baseUrl,
     activity,
     defaultToolTimeoutMs: opts.defaultToolTimeoutMs,
+    probeTimeoutMs: opts.probeTimeoutMs,
   });
   if (opts.executor) {
-    registerExecuteTool(server, opts.registry, {
+    registerExecuteTool(server, registry, {
       baseUrl,
       executor: opts.executor,
       logger: opts.logger,
@@ -693,9 +787,22 @@ export function createFetchHandler(
         // Open shell — carries no data; data comes only from the gated /ui/data.
         const uiAuth = auth.find((provider) => provider.uiAuth)?.uiAuth;
         const mcpUrl = new URL("/mcp", baseUrl).toString();
-        return new Response(renderUiHtml(uiAuth, mcpUrl, opts.branding), {
+        // Nonce the page's inline script (and the Clerk loader). 'strict-dynamic'
+        // lets scripts the nonced Clerk loader injects at runtime execute; the
+        // https:/'unsafe-inline' fallbacks are ignored by CSP3 browsers that
+        // honour the nonce and only cover legacy ones. No default-src, so Clerk's
+        // style/font/network needs and the page's inline <style> stay unrestricted
+        // — only script execution, the XSS sink, is gated.
+        const nonce = uiScriptNonce();
+        return new Response(renderUiHtml(uiAuth, mcpUrl, opts.branding, nonce), {
           status: 200,
-          headers: { "Content-Type": "text/html; charset=utf-8" },
+          headers: {
+            "Content-Type": "text/html; charset=utf-8",
+            "Content-Security-Policy":
+              `script-src 'nonce-${nonce}' 'strict-dynamic' https: 'unsafe-inline'; ` +
+              "object-src 'none'; base-uri 'none'; frame-ancestors 'none'",
+            "X-Content-Type-Options": "nosniff",
+          },
         });
       }
 
@@ -757,11 +864,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 response = authz.ok
-          ? await serveMcp(request, opts, baseUrl, authz.actor, runtimeContext)
-          : authz.response;
-        return withMcpCors(response);
+        if (!authz.ok) return withMcpCors(authz.response);
+        const selected = resolveToolkitScope(url, registry, opts.toolkits);
+        if (!selected.ok) return withMcpCors(selected.response);
+        return withMcpCors(
+          await serveMcp(
+            request,
+            opts,
+            baseUrl,
+            authz.actor,
+            selected.scope,
+            runtimeContext,
+          ),
+        );
       }
 
       // Connector-owned public routes, dispatched last: a connector can add a

package/src/skills.ts

@@ -1,3 +1,5 @@
+import type { Connector } from "./types.js";
+
 export const CONNECTA_INSTRUCTIONS =
   'Connecta exposes many integrations behind meta-tools. When an address is unknown, start with search_tools and includeSchemas="compact"; use describe_tools only when that schema is insufficient. Use call_tool for one explicitly read-only call, batch_call for 2–10 independent explicitly read-only calls, and execute_code (when available) only for dependent read-only steps, loops, joins, or reducing large results. Unannotated, write-capable, and destructive tools must use call_destructive_tool individually. Use authorize_connector only after auth_required and get_result only for truncated results. For the detailed workflow, call skills({ name: "usage" }) once per task.';
 
@@ -53,11 +55,192 @@ async () => {
 \`\`\`
 `;
 
+/**
+ * Appended to USAGE_SKILL only when the deployment actually has at least one
+ * connector guide. A deployment with none — every deployment that has not
+ * adopted the feature — keeps the base guide byte-for-byte, rather than paying
+ * context for an instruction to fetch guides that do not exist.
+ */
+export const CONNECTOR_GUIDES_SECTION = `
+## Per-connector guides
+
+Some connectors here ship their own usage guide — preferred tools, address quirks, pagination conventions, rate-limit etiquette, query patterns. \`skills({})\` lists each one as \`connector:<connectorId>\`; fetch it with \`skills({ name: "connector:<connectorId>" })\`. \`search_tools\` and \`describe_tools\` set \`guide\` on matches whose connector has one. Read a connector's guide before working with it for the first time in a task.
+`;
+
+/** True when at least one of `connectors` carries a usage guide. */
+export function hasConnectorGuides(connectors: readonly Connector[]): boolean {
+  return connectors.some(
+    (connector) => connectorGuide(connector) !== undefined,
+  );
+}
+
+/** The built-in usage guide, plus the guides section when there is one to point at. */
+export function usageSkill(connectors: readonly Connector[]): string {
+  return hasConnectorGuides(connectors)
+    ? USAGE_SKILL + CONNECTOR_GUIDES_SECTION
+    : USAGE_SKILL;
+}
+
 export const AVAILABLE_SKILLS = [
   {
     name: "usage",
     description:
       "How to choose among Connecta discovery, direct, batch, destructive, and code-mode tools.",
-    content: USAGE_SKILL,
+    content: usageSkill,
   },
 ] as const;
+
+/**
+ * Namespace for operator-authored per-connector guides. Built-in skill names
+ * are bare identifiers and never contain ":", so `connector:<id>` cannot
+ * collide with one — not even when a connector's id is literally "usage".
+ * The prefixed form is the ONLY way to reach a connector guide: a bare
+ * connector id is never resolved, so nothing shadows anything silently.
+ */
+export const CONNECTOR_SKILL_PREFIX = "connector:";
+
+/** The skill name that fetches `connector`'s guide. */
+export function connectorSkillName(connectorId: string): string {
+  return `${CONNECTOR_SKILL_PREFIX}${connectorId}`;
+}
+
+/** The connector's guide, or undefined when it declares none (or a blank one). */
+export function connectorGuide(connector: Connector): string | undefined {
+  const guide = connector.usageGuide;
+  return guide && guide.trim() !== "" ? guide : undefined;
+}
+
+const SUMMARY_LENGTH = 120;
+
+/** A `---`/`***`/`___` rule, which also opens and closes YAML frontmatter. */
+const RULE_RE = /^\s*(?:-{3,}|\*{3,}|_{3,})\s*$/;
+
+/** A fenced code block's delimiter. */
+const FENCE_RE = /^\s*(?:```|~~~)/;
+
+/**
+ * Markup that carries no summary text of its own: horizontal rules, HTML
+ * comments, and table rows. Skipped so a guide that opens with one is
+ * summarized by its first real line instead of by punctuation.
+ */
+const NOT_SUMMARY_RE = /^\s*(?:<!--|\|)|^\s*(?:-{3,}|\*{3,}|_{3,})\s*$/;
+
+/** Drop a leading YAML frontmatter block — metadata, not summary text. */
+function withoutFrontmatter(lines: string[]): string[] {
+  let start = 0;
+  while (start < lines.length && lines[start].trim() === "") start++;
+  if (start >= lines.length || !RULE_RE.test(lines[start])) return lines;
+  const close = lines.findIndex((line, i) => i > start && RULE_RE.test(line));
+  return close === -1 ? lines : lines.slice(close + 1);
+}
+
+/**
+ * One line describing a guide, for the cheap list view: the guide's first
+ * meaningful line (heading marks and list bullets stripped), falling back to
+ * the connector's own description when the guide opens with nothing but
+ * markup.
+ */
+function summarizeGuide(connector: Connector, guide: string): string {
+  let inFence = false;
+  for (const raw of withoutFrontmatter(guide.split("\n"))) {
+    if (FENCE_RE.test(raw)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    if (raw.trim() === "" || NOT_SUMMARY_RE.test(raw)) continue;
+    const line = raw
+      // `\s*` (not `\s+`) so a bare `#` strips to nothing and is skipped, and
+      // an unspaced `#Heading` is still read as a heading.
+      .replace(/^\s*#{1,6}\s*/, "")
+      .replace(/^\s*[-*+]\s+/, "")
+      .replace(/\s+/g, " ")
+      .trim();
+    if (line === "") continue;
+    return line.length <= SUMMARY_LENGTH
+      ? line
+      : `${line.slice(0, SUMMARY_LENGTH - 1).trimEnd()}…`;
+  }
+  return connector.description ?? `Usage guide for "${connector.id}".`;
+}
+
+export interface SkillListing {
+  name: string;
+  description: string;
+}
+
+/**
+ * Every fetchable skill: the built-in guides plus one entry per connector that
+ * carries a usage guide. Derived from the connector list passed in — the single
+ * place guide visibility is decided. The `skills` meta-tool passes its
+ * connection's `registry.listConnectors()`, so a toolkit-scoped session lists
+ * only in-scope guides, and `resolveSkill` below reports an out-of-scope
+ * `connector:<id>` exactly as it reports an unknown connector.
+ */
+export function listSkills(connectors: readonly Connector[]): SkillListing[] {
+  const listing: SkillListing[] = AVAILABLE_SKILLS.map((skill) => ({
+    name: skill.name,
+    description: skill.description,
+  }));
+  for (const connector of connectors) {
+    const guide = connectorGuide(connector);
+    if (!guide) continue;
+    listing.push({
+      name: connectorSkillName(connector.id),
+      description: summarizeGuide(connector, guide),
+    });
+  }
+  return listing;
+}
+
+export type SkillLookup =
+  { found: true; content: string } | { found: false; message: string };
+
+/**
+ * Resolve one skill name. Built-in names match exactly; connector guides are
+ * reachable only through the `connector:` prefix. Every miss — unknown name,
+ * unknown connector, connector without a guide — is an explicit error, never a
+ * silent fallback to the generic guide.
+ */
+export function resolveSkill(
+  name: string,
+  connectors: readonly Connector[],
+): SkillLookup {
+  const builtIn = AVAILABLE_SKILLS.find((skill) => skill.name === name);
+  if (builtIn) return { found: true, content: builtIn.content(connectors) };
+  const available = () =>
+    listSkills(connectors)
+      .map((skill) => skill.name)
+      .join(", ");
+  if (name.startsWith(CONNECTOR_SKILL_PREFIX)) {
+    const id = name.slice(CONNECTOR_SKILL_PREFIX.length);
+    const connector = connectors.find((c) => c.id === id);
+    if (!connector) {
+      return {
+        found: false,
+        message: `Unknown connector "${id}". Available skills: ${available()}.`,
+      };
+    }
+    const guide = connectorGuide(connector);
+    if (!guide) {
+      return {
+        found: false,
+        message: `Connector "${id}" has no usage guide. Available skills: ${available()}.`,
+      };
+    }
+    return { found: true, content: guide };
+  }
+  const bare = connectors.find((c) => c.id === name);
+  if (bare) {
+    return {
+      found: false,
+      message: connectorGuide(bare)
+        ? `Unknown skill "${name}". Connector guides are fetched as "${connectorSkillName(name)}". Available: ${available()}.`
+        : `Connector "${name}" has no usage guide. Available skills: ${available()}.`,
+    };
+  }
+  return {
+    found: false,
+    message: `Unknown skill "${name}". Available: ${available()}.`,
+  };
+}

package/src/storage/file.ts

@@ -1,4 +1,5 @@
 import {
+  chmodSync,
   existsSync,
   mkdirSync,
   readFileSync,
@@ -28,8 +29,20 @@ export function fileStorage(
   opts: FileStorageOptions = {},
 ): KVStorage {
   const logger: Logger = opts.logger ?? console;
+  // The state file holds downstream OAuth access/refresh tokens in cleartext,
+  // so keep it owner-only. Repair is best-effort: chmod is a no-op or throws on
+  // non-POSIX filesystems, and a loose mode must never keep the store from
+  // starting.
+  const tighten = () => {
+    try {
+      chmodSync(path, 0o600);
+    } catch {
+      // Non-POSIX filesystem or a race on the file — leave the mode as-is.
+    }
+  };
   let data: Record<string, Entry> = {};
   if (existsSync(path)) {
+    tighten();
     try {
       data = JSON.parse(readFileSync(path, "utf8")) as Record<string, Entry>;
     } catch (error) {
@@ -60,10 +73,13 @@ export function fileStorage(
   }
   const persist = () => {
     const dir = dirname(path);
-    if (dir) mkdirSync(dir, { recursive: true });
+    if (dir) mkdirSync(dir, { recursive: true, mode: 0o700 });
     const tmp = `${path}.tmp`;
-    writeFileSync(tmp, JSON.stringify(data));
+    // 0o600 on the tmp file; the atomic rename below preserves it, so the live
+    // state file is never briefly world-readable.
+    writeFileSync(tmp, JSON.stringify(data), { mode: 0o600 });
     renameSync(tmp, path);
+    tighten();
   };
   const fresh = (key: string): Entry | null => {
     const e = data[key];

package/src/toolkits.ts

@@ -0,0 +1,215 @@
+// Toolkits: named, operator-defined scoped views over one deployment's
+// registry, selected per client connection with `?toolkit=<name>` on /mcp.
+//
+// A connecta deployment belongs to an ORG; a toolkit is the view a GROUP OF
+// TEAM MEMBERS inside that org gets — a "support" toolkit seeing Zendesk and
+// Notion, an "exec" toolkit that also sees Gmail. This module only *defines and
+// validates* scopes. Enforcement lives in one place: `ScopedRegistry`
+// (src/registry.ts), which every meta-tool inherits through `RegistryView`.
+
+import type { Connector } from "./types.js";
+
+/** Toolkit names share the connector-id grammar: URL-safe, no separators. */
+export const TOOLKIT_NAME_RE = /^[a-z0-9_-]+$/;
+
+/** One named scope, declared in `ConnectaConfig.toolkits` (config as code). */
+export interface ToolkitDefinition {
+  /** Connector ids this toolkit may see. Required, and at least one. */
+  connectors: string[];
+  /**
+   * Optional finer grain: full tool addresses (`"<connectorId>.<toolName>"`).
+   * Naming ANY address of a connector narrows that connector to exactly the
+   * addresses named; connectors with no entry here keep their whole tool list.
+   */
+  includeTools?: string[];
+  /** Optional tool addresses to hide, applied after `includeTools`. */
+  excludeTools?: string[];
+  /** Operator note. Never sent to clients — this is documentation for config. */
+  description?: string;
+}
+
+/** `ConnectaConfig.toolkits` — toolkit name → definition. */
+export type ToolkitConfig = Record<string, ToolkitDefinition>;
+
+/** A validated toolkit: the visibility predicate the scoped registry consults. */
+export interface Toolkit {
+  readonly name: string;
+  readonly description?: string;
+  /** True when `connectorId` is inside this toolkit's scope. */
+  hasConnector(connectorId: string): boolean;
+  /** True when `<connectorId>.<toolName>` is inside this toolkit's scope. */
+  hasTool(connectorId: string, toolName: string): boolean;
+}
+
+/**
+ * Split `"<connectorId>.<toolName>"` on the FIRST dot — connector ids contain
+ * no dots, so a downstream tool name may. Returns null for a malformed address.
+ */
+export function splitAddress(
+  address: string,
+): { connectorId: string; toolName: string } | null {
+  const dot = address.indexOf(".");
+  if (dot <= 0 || dot === address.length - 1) return null;
+  return {
+    connectorId: address.slice(0, dot),
+    toolName: address.slice(dot + 1),
+  };
+}
+
+/** Group tool addresses by connector id, validating each against the toolkit. */
+function toolFilter(
+  name: string,
+  addresses: string[] | undefined,
+  connectorIds: ReadonlySet<string>,
+  staticTools: ReadonlyMap<string, ReadonlySet<string>>,
+  field: "includeTools" | "excludeTools",
+): Map<string, Set<string>> {
+  const byConnector = new Map<string, Set<string>>();
+  if (addresses !== undefined && !Array.isArray(addresses)) {
+    // A bare string would otherwise iterate character by character and produce
+    // a stream of confusing address errors; anything else would throw "not
+    // iterable" from deep inside the loop. Name the field instead.
+    throw new Error(
+      `Toolkit "${name}" ${field} must be an array of "<connectorId>.<toolName>" addresses.`,
+    );
+  }
+  if (
+    addresses !== undefined &&
+    addresses.length === 0 &&
+    field === "includeTools"
+  ) {
+    // An empty allowlist reads as "only these tools" but would behave as "all
+    // of them" — the one shape here that fails OPEN. (An empty excludeTools is
+    // an honest no-op and is allowed.)
+    throw new Error(
+      `Toolkit "${name}" has an empty includeTools: remove it to expose every tool, or list the addresses this toolkit may use.`,
+    );
+  }
+  for (const address of addresses ?? []) {
+    const parts = splitAddress(address);
+    if (!parts) {
+      throw new Error(
+        `Toolkit "${name}" ${field} entry "${address}" is not a tool address: expected "<connectorId>.<toolName>".`,
+      );
+    }
+    if (!connectorIds.has(parts.connectorId)) {
+      // A typo here would silently do nothing, quietly widening the scope the
+      // operator believes they wrote. Fail at construction instead.
+      throw new Error(
+        `Toolkit "${name}" ${field} entry "${address}" names connector "${parts.connectorId}", which is not in this toolkit's connectors list.`,
+      );
+    }
+    // Static-only, exactly like the registry's convention checks: an in-code
+    // connector's tool list is known now, so a misspelled name — an exclude
+    // that silently excludes nothing — is caught. Remote catalogs are fetched
+    // lazily over the network and cannot be checked at construction.
+    const known = staticTools.get(parts.connectorId);
+    if (known && !known.has(parts.toolName)) {
+      throw new Error(
+        `Toolkit "${name}" ${field} entry "${address}" names no tool on connector "${parts.connectorId}".`,
+      );
+    }
+    const tools = byConnector.get(parts.connectorId) ?? new Set<string>();
+    tools.add(parts.toolName);
+    byConnector.set(parts.connectorId, tools);
+  }
+  return byConnector;
+}
+
+/**
+ * Validate one toolkit definition against the deployment's connectors.
+ *
+ * Structural mistakes THROW at construction rather than warn: a typo'd id in
+ * an allowlist is a scope the operator did not write, and a scope nobody wrote
+ * is not one an operator can reason about. (A toolkit scopes visibility, not
+ * identity — it is not itself an access check; see the module header and
+ * documentation.md §16.) Tool names are checked only for connectors that expose
+ * `staticTools` (i.e. `api()`); a remote connector's catalog is fetched lazily
+ * over the network and is unknown at construction time.
+ */
+function resolveToolkit(
+  name: string,
+  definition: ToolkitDefinition,
+  known: ReadonlySet<string>,
+  staticTools: ReadonlyMap<string, ReadonlySet<string>>,
+): Toolkit {
+  if (!TOOLKIT_NAME_RE.test(name)) {
+    throw new Error(
+      `Invalid toolkit name "${name}": must match ${TOOLKIT_NAME_RE.source}`,
+    );
+  }
+  if (
+    !Array.isArray(definition.connectors) ||
+    definition.connectors.length === 0
+  ) {
+    throw new Error(
+      `Toolkit "${name}" selects no connectors: list at least one connector id in "connectors".`,
+    );
+  }
+  const connectorIds = new Set<string>();
+  for (const id of definition.connectors) {
+    if (!known.has(id)) {
+      throw new Error(
+        `Toolkit "${name}" references unknown connector "${id}".`,
+      );
+    }
+    connectorIds.add(id);
+  }
+  const includes = toolFilter(
+    name,
+    definition.includeTools,
+    connectorIds,
+    staticTools,
+    "includeTools",
+  );
+  const excludes = toolFilter(
+    name,
+    definition.excludeTools,
+    connectorIds,
+    staticTools,
+    "excludeTools",
+  );
+  return {
+    name,
+    ...(definition.description ? { description: definition.description } : {}),
+    hasConnector: (connectorId) => connectorIds.has(connectorId),
+    hasTool: (connectorId, toolName) => {
+      if (!connectorIds.has(connectorId)) return false;
+      const include = includes.get(connectorId);
+      if (include && !include.has(toolName)) return false;
+      return !excludes.get(connectorId)?.has(toolName);
+    },
+  };
+}
+
+/**
+ * Validate every declared toolkit against the connector set. Returns undefined
+ * when no toolkits are configured, so an existing deployment keeps exactly its
+ * current (unscoped) behavior.
+ */
+export function resolveToolkits(
+  toolkits: ToolkitConfig | undefined,
+  connectors: readonly Connector[],
+): ReadonlyMap<string, Toolkit> | undefined {
+  if (!toolkits) return undefined;
+  // Object.entries (not a keyed lookup) so no config key — `__proto__` and
+  // friends included — can ever resolve through the prototype chain. Names are
+  // then held in a Map, which has no prototype to pollute.
+  const entries = Object.entries(toolkits);
+  if (entries.length === 0) return undefined;
+  const known = new Set(connectors.map((connector) => connector.id));
+  const staticTools = new Map<string, ReadonlySet<string>>();
+  for (const connector of connectors) {
+    if (connector.staticTools) {
+      staticTools.set(
+        connector.id,
+        new Set(connector.staticTools.map((tool) => tool.name)),
+      );
+    }
+  }
+  const resolved = new Map<string, Toolkit>();
+  for (const [name, definition] of entries) {
+    resolved.set(name, resolveToolkit(name, definition, known, staticTools));
+  }
+  return resolved;
+}