@opengeni/core 3.0.1 → 3.1.2

package/src/domain/capabilities.ts

@@ -1,12 +1,21 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
-import { environmentsEncryptionKeyBytes, type Settings } from "@opengeni/config";
+import { isDeepStrictEqual } from "node:util";
+import { withLockedCapabilityInstallation } from "@opengeni/db/capability-reconciliation";
+import {
+  environmentsEncryptionKeyBytes,
+  findIntegrationsOauthClient,
+  parseIntegrationsOauthClientsJson,
+  type Settings,
+} from "@opengeni/config";
+import { pinnedFetch } from "@opengeni/network";
 import {
   CapabilityCatalogItem,
   capabilityCatalogItemIsTrustedForExposure,
   FIKEN_PROVIDER_DOMAIN,
   FIRST_PARTY_MCP_TOOL_NAMES,
+  OPENGENI_BROWSER_EXTENSION_URL,
   type AccessGrant,
   type CapabilityAction,
   type CapabilityCatalogResponse,
@@ -16,7 +25,7 @@ import {
   type EnableCapabilityRequest,
   type McpServerConnectionRef,
   type McpPersonalConnectionDelegation,
-  OPENGENI_PERSONAL_SLACK_MCP_URL,
+  assertOrganizationIntegrationAllowed,
   type SocialConnection,
 } from "@opengeni/contracts";
 import {
@@ -34,8 +43,12 @@ import {
   getCapabilityCatalogItem,
   getCapabilityInstallation,
   getConnectionMetadata,
-  getCodexAppsCredentialAuthorizationForRun,
-  getWorkspaceGrant,
+  readCodexCutoverDisposition,
+  resolveSubscriptionCoreCodexAppsDesignation,
+  rlsContextForWorkspace,
+  subscriptionCoreCodexAppsRequestAuth,
+  type SubscriptionCoreCodexAppsRequestAuth,
+  type CodexCutoverDisposition,
   getStoredCapabilityHeaderCiphertext,
   listCapabilityCatalogItems,
   listCapabilityInstallations,
@@ -43,7 +56,6 @@ import {
   listEnabledMcpCapabilityServers,
   listInstalledApiIntegrations,
   listInstalledSkills,
-  listPackInstallations,
   listSocialConnections,
   mcpServerIdForCapability,
   upsertCapabilityCatalogItem,
@@ -53,11 +65,15 @@ import {
   type InstalledSkillSummary,
 } from "@opengeni/db";
 import { HTTPException } from "hono/http-exception";
-import { hasPermission } from "../access";
+import {
+  withOrganizationIntegrationAcquisition,
+  withOrganizationIntegrationPolicyFence,
+} from "@opengeni/db/organization-integration-policy";
+
 import { isFikenConnection, preferredFikenConnection } from "./fiken";
+import { isOnePasswordConnection, onePasswordConnectionMetadata } from "./vaults/provider-registry";
 import { listSkillLibraryEntries, type SkillLibraryEntry } from "@opengeni/runtime/skill-library";
-import { listCapabilityPacks, listWorkspaceCapabilityPacks } from "./packs";
-import { assertHostMcpAuthoritySourceAdmissionEnabled } from "./host-mcp-authority-source-admission";
+import { assertNativeMcpConnectionRef } from "./native-mcp-connection-admission";
 
 const officialMcpRegistryUrl = "https://registry.modelcontextprotocol.io";
 const firstPartyMcpServerIds = new Set(["opengeni", "files", "docs"]);
@@ -66,7 +82,6 @@ const mcpRegistryMaxPages = 3;
 const mcpCapabilityProbeTimeoutMs = 15000;
 const maxMcpCredentialHeaders = 16;
 const maxMcpCredentialHeaderValueLength = 4096;
-const officialGmailMcpUrl = "https://gmailmcp.googleapis.com/mcp/v1";
 // RFC 9110 field-name token characters.
 const mcpCredentialHeaderName = /^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/;
 
@@ -75,30 +90,36 @@ export async function buildCapabilityCatalog(input: {
   workspaceId: string;
   settings: Settings;
   subjectId?: string | null;
+  /** The workspace's organization, when the caller knows it (skips a lookup). */
+  accountId?: string;
 }): Promise<CapabilityCatalogResponse> {
   const [
     persistedItems,
     capabilityInstallations,
-    packInstallations,
-    workspacePacks,
     socialConnections,
     workspaceConnections,
     curatedLibrarySkills,
     installedSkills,
-    codexAppsCredentialId,
+    codexAppsDesignation,
+    runnableMcpServers,
   ] = await Promise.all([
     listCapabilityCatalogItems(input.db, input.workspaceId),
     listCapabilityInstallations(input.db, input.workspaceId),
-    listPackInstallations(input.db, input.workspaceId),
-    listWorkspaceCapabilityPacks(input.db, input.workspaceId),
     listSocialConnections(input.db, input.workspaceId, 500, input.subjectId),
     listConnectionsMetadata(input.db, input.workspaceId, null),
     discoverCuratedSkillLibraryItems(),
     listInstalledSkills(input.db, input.workspaceId),
     input.settings.codexConnectedAppsEnabled
-      ? resolveCodexAppsCredentialIdForRun(input.db, input.workspaceId)
+      ? resolveCodexAppsDesignationForRun(
+          input.db,
+          input.workspaceId,
+          input.accountId ? { accountId: input.accountId } : {},
+        )
       : Promise.resolve(null),
+    listEnabledMcpCapabilityServers(input.db, input.workspaceId),
   ]);
+  const runnableCapabilityIds = new Set(runnableMcpServers.map((server) => server.capabilityId));
+  const operatorOAuthClientConfigured = operatorOAuthClientResolver(input.settings);
   const catalogInstallations = capabilityInstallations.filter(
     (installation) => installation.kind === "mcp",
   );
@@ -110,19 +131,11 @@ export async function buildCapabilityCatalog(input: {
       .filter((skill) => skill.owners.some((owner) => owner.kind === "direct"))
       .map((skill) => [skill.capabilityId, skill]),
   );
-  const activePackIds = new Set(
-    packInstallations
-      .filter((installation) => installation.status === "active")
-      .map((installation) => installation.packId),
-  );
-  const builtInPackIds = new Set(listCapabilityPacks().map((pack) => pack.id));
   const builtIns = [
-    ...workspacePacks.map((pack) =>
-      packCatalogItem(pack, builtInPackIds.has(pack.id) ? "built_in" : "manual"),
-    ),
     ...configuredMcpCatalogItems(input.settings),
     ...providerIntegrationCatalogItems(socialConnections),
     fikenCatalogItem(workspaceConnections.filter(isFikenConnection)),
+    onePasswordCatalogItem(workspaceConnections.filter(isOnePasswordConnection)),
     ...curatedLibrarySkills.filter((item) => installedSkillById.has(item.id)),
     ...installedSkills
       .filter(
@@ -132,7 +145,7 @@ export async function buildCapabilityCatalog(input: {
       .map(installedSkillCatalogItem),
   ];
   const codexApps = input.settings.codexConnectedAppsEnabled
-    ? codexAppsCatalogItem(codexAppsCredentialId !== null)
+    ? codexAppsCatalogItem(codexAppsDesignation !== null)
     : null;
   const items = dedupeCatalogItems([
     ...builtIns,
@@ -151,8 +164,28 @@ export async function buildCapabilityCatalog(input: {
       const projected =
         item.kind === "skill"
           ? applyInstalledSkillEnablement(item, installedSkillById.get(item.id))
-          : applyCapabilityEnablement(item, capabilityInstallationById.get(item.id), activePackIds);
-      return applyCapabilityLifecycle(projected);
+          : applyCapabilityEnablement(item, capabilityInstallationById.get(item.id));
+      // An installed connector can become unrunnable after a lifecycle or
+      // ownership change. Use the execution registry rather than presenting
+      // its stale catalog definition as a selectable tool.
+      const runtimeProjected =
+        projected.kind === "mcp" &&
+        projected.enabled &&
+        projected.source !== "configured" &&
+        projected.source !== "built_in" &&
+        !runnableCapabilityIds.has(projected.id)
+          ? {
+              ...projected,
+              runtime: {
+                ...projected.runtime,
+                available: false,
+                notes: "This installed connection is unavailable. Review its connection settings.",
+              },
+            }
+          : projected;
+      return applyCapabilityLifecycle(
+        applyOperatorOAuthClientRequirement(runtimeProjected, operatorOAuthClientConfigured),
+      );
     })
     .sort(compareCatalogItems);
   return {
@@ -161,6 +194,40 @@ export async function buildCapabilityCatalog(input: {
   };
 }
 
+/**
+ * `metadata.oauthClientRequirement` is stamped by the catalog import from
+ * `data/catalog/oauth-client-requirements.json` for providers that refuse
+ * OAuth self-registration. Whether the row can connect here is a deployment
+ * fact, so the catalog projects it rather than every surface guessing. The
+ * matcher is the one the OAuth start uses to find an operator client.
+ */
+function operatorOAuthClientResolver(settings: Settings): (issuer: string) => boolean {
+  let configured: ReturnType<typeof parseIntegrationsOauthClientsJson> = {};
+  try {
+    configured = parseIntegrationsOauthClientsJson(settings.integrationsOauthClientsJson);
+  } catch {
+    // Startup validates this setting; a malformed value can configure nothing.
+  }
+  return (issuer) => findIntegrationsOauthClient(configured, [issuer]) !== null;
+}
+
+export function applyOperatorOAuthClientRequirement(
+  item: CapabilityCatalogItem,
+  configured: (issuer: string) => boolean,
+): CapabilityCatalogItem {
+  if (item.kind !== "mcp") return item;
+  const requirement = item.metadata.oauthClientRequirement;
+  const issuer =
+    requirement && typeof requirement === "object" && !Array.isArray(requirement)
+      ? (requirement as Record<string, unknown>).issuer
+      : undefined;
+  if (typeof issuer !== "string" || !issuer) return item;
+  return {
+    ...item,
+    runtime: { ...item.runtime, operatorOAuthClient: { configured: configured(issuer) } },
+  };
+}
+
 export async function createCatalogItem(input: {
   db: Database;
   accountId: string;
@@ -168,11 +235,7 @@ export async function createCatalogItem(input: {
   payload: CreateCapabilityCatalogItemRequest;
 }): Promise<CapabilityCatalogItem> {
   const id = input.payload.id?.trim() || generatedCapabilityId(input.payload);
-  if (id.startsWith("pack:")) {
-    throw new HTTPException(422, {
-      message: "packs are managed by OpenGeni and cannot be manually created",
-    });
-  }
+
   if (id.startsWith("skill:")) {
     throw new HTTPException(422, {
       message: "Skills are installed through the Skill library or source import flow",
@@ -240,6 +303,14 @@ type EnableCapabilityInput = {
   capabilityId: string;
   payload: EnableCapabilityRequest;
   probeMcpServer?: McpCapabilityProbe;
+  /** Server-owned receipt from a just-verified native Connect credential.
+   * Never projected into EnableCapabilityRequest or accepted from a client. */
+  verifiedConnection?: {
+    id: string;
+    version: number;
+    endpointUrl: string;
+    connectivity: Record<string, unknown>;
+  };
 };
 
 export async function enableCapability(
@@ -252,6 +323,7 @@ export async function enableCapability(
 /** Probe outside a durable Connect commit; persist the exact prepared settings
  * inside the caller's authorized receipt transaction. Native enable uses this too. */
 export async function prepareCapabilityEnable(input: EnableCapabilityInput) {
+  input = { ...input, payload: structuredClone(input.payload) };
   const item = await requireCatalogItem(
     input.db,
     input.workspaceId,
@@ -277,11 +349,7 @@ export async function prepareCapabilityEnable(input: EnableCapabilityInput) {
       message: "Install Plugins through the Plugin Package flow",
     });
   }
-  if (item.kind === "pack") {
-    throw new HTTPException(409, {
-      message: "Install Packs through the Pack installation preview flow",
-    });
-  }
+
   if (item.kind === "mcp" && !item.runtime.available) {
     throw new HTTPException(422, {
       message: "MCP capabilities need a remote streamable HTTP endpoint before they can be enabled",
@@ -297,16 +365,69 @@ export async function prepareCapabilityEnable(input: EnableCapabilityInput) {
   delete installationConfig.headerNames;
   delete installationConfig.connectionRef;
   if (item.kind === "mcp") {
-    const headers = await resolveMcpCredentialHeaders(input, item);
+    if (
+      item.endpointUrl?.replace(/\/+$/u, "") === "https://gmailmcp.googleapis.com/mcp/v1" &&
+      (input.payload.connectionRef?.subjectScope !== "subject" ||
+        Object.keys(input.payload.headers ?? {}).length > 0)
+    ) {
+      throw new HTTPException(422, {
+        message: "Gmail requires a personal-owned connection reference",
+      });
+    }
+    // This generic, potentially workspace-authored catalog is not proof of a
+    // curated provider identity. Dedicated Connect adapters classify separately.
+    const unchanged = await withOrganizationIntegrationPolicyFence(
+      input.db,
+      input,
+      async (tx, policy) => {
+        const existing = await unchangedMcpInstallation(
+          { ...input, db: tx },
+          item,
+          installationConfig,
+        );
+        if (existing) return existing;
+        assertOrganizationIntegrationAllowed(policy, "custom:mcp");
+        return null;
+      },
+    );
+    if (unchanged) {
+      return {
+        commit: (db: Database) =>
+          withOrganizationIntegrationPolicyFence(db, input, async (tx) => {
+            const current = await unchangedMcpInstallation(
+              { ...input, db: tx },
+              item,
+              installationConfig,
+            );
+            if (!current || !isDeepStrictEqual(current, unchanged)) {
+              throw new HTTPException(409, {
+                message: "Capability installation changed; reload before reconciling",
+              });
+            }
+            return current;
+          }),
+      };
+    }
+    const headers = input.verifiedConnection
+      ? null
+      : await resolveMcpCredentialHeaders(input, item);
     const connectionRef = input.payload.connectionRef
       ? await validateMcpCapabilityConnectionRef(input, item, input.payload.connectionRef)
       : null;
     assertRequiredMcpCredentialHeaders(item, headers, connectionRef);
+    if (input.verifiedConnection) await validateVerifiedMcpConnection(input, item);
     installationMetadata = {
       ...installationMetadata,
-      ...(connectionRef && !headers
-        ? authDeferredMcpConnectivity()
-        : await validateMcpCapabilityConnection(item, input.probeMcpServer, headers ?? undefined)),
+      ...(input.verifiedConnection
+        ? input.verifiedConnection.connectivity
+        : connectionRef && !headers
+          ? authDeferredMcpConnectivity()
+          : await validateMcpCapabilityConnection(
+              item,
+              input.probeMcpServer,
+              headers ?? undefined,
+              input.settings,
+            )),
     };
     if (connectionRef) {
       installationConfig.connectionRef = connectionRef;
@@ -325,8 +446,92 @@ export async function prepareCapabilityEnable(input: EnableCapabilityInput) {
     kind: item.kind,
     config: installationConfig,
     metadata: installationMetadata,
+    ...(input.payload.onlyIfUninstalled ? { onlyIfUninstalled: true } : {}),
+  };
+  return {
+    commit: (db: Database) =>
+      item.kind === "mcp"
+        ? withOrganizationIntegrationAcquisition(db, installation, ["custom:mcp"], async (tx) => {
+            if (input.verifiedConnection)
+              await validateVerifiedMcpConnection({ ...input, db: tx }, item);
+            return enableCapabilityInstallation(tx, installation);
+          })
+        : enableCapabilityInstallation(db, installation),
   };
-  return { commit: (db: Database) => enableCapabilityInstallation(db, installation) };
+}
+
+async function validateVerifiedMcpConnection(
+  input: EnableCapabilityInput,
+  item: CapabilityCatalogItem,
+) {
+  const proof = input.verifiedConnection;
+  const ref = input.payload.connectionRef;
+  if (
+    !proof ||
+    !ref ||
+    item.endpointUrl !== proof.endpointUrl ||
+    ref.resource !== proof.endpointUrl
+  )
+    throw new HTTPException(409, { message: "MCP verification no longer matches the connection" });
+  const connection = await getConnectionMetadata(
+    input.db,
+    input.workspaceId,
+    proof.id,
+    input.grant.subjectId,
+  );
+  if (
+    !connection ||
+    connection.version !== proof.version ||
+    connection.status !== "active" ||
+    connection.providerDomain !== ref.providerDomain ||
+    connection.kind !== ref.kind ||
+    connection.subjectId !== (ref.subjectScope === "subject" ? input.grant.subjectId : null) ||
+    connection.metadata.mcpUrl !== proof.endpointUrl
+  )
+    throw new HTTPException(409, { message: "MCP connection changed after verification" });
+}
+
+/** A no-effect reconciliation is not a new acquisition. Validate ordinary
+ * connection visibility before locking the installation, and compare actual
+ * stored credentials rather than trusting caller-supplied identity hints. */
+async function unchangedMcpInstallation(
+  input: EnableCapabilityInput,
+  item: CapabilityCatalogItem,
+  requestedConfig: Record<string, unknown>,
+): Promise<CapabilityInstallation | null> {
+  const connectionRef = input.payload.connectionRef
+    ? await validateMcpCapabilityConnectionRef(input, item, input.payload.connectionRef)
+    : null;
+  const existing = await withLockedCapabilityInstallation(
+    input.db,
+    input.workspaceId,
+    item.id,
+    (tx) => getCapabilityInstallation(tx, input.workspaceId, item.id),
+  );
+  if (!existing || existing.kind !== "mcp" || existing.status !== "active") return null;
+  const {
+    headerNames: _names,
+    headersEncrypted: _encrypted,
+    headers: _headers,
+    ...storedConfig
+  } = existing.config;
+  const config = { ...requestedConfig, ...(connectionRef ? { connectionRef } : {}) };
+  const { mcpConnectivity: _storedConnectivity, ...storedMetadata } = existing.metadata;
+  const { mcpConnectivity: _requestedConnectivity, ...requestedMetadata } = input.payload.metadata;
+  if (
+    !isDeepStrictEqual(config, storedConfig) ||
+    !isDeepStrictEqual(requestedMetadata, storedMetadata)
+  )
+    return null;
+  const provided = normalizedMcpCredentialHeaders(input.payload.headers);
+  if (provided) {
+    const stored = await resolveMcpCredentialHeaders(
+      { ...input, payload: { ...input.payload, headers: {} } },
+      item,
+    );
+    if (!isDeepStrictEqual(provided, stored)) return null;
+  }
+  return existing;
 }
 
 /**
@@ -425,24 +630,11 @@ async function validateMcpCapabilityConnectionRef(
   ref: McpServerConnectionRef,
 ): Promise<McpServerConnectionRef> {
   const subjectScope = ref.subjectScope ?? "workspace";
-  const endpointUrl = item.endpointUrl?.replace(/\/+$/, "");
-  // Gmail is a consumer mailbox; Slack's hosted MCP issues user tokens only and
-  // shared Slack authority belongs to the OpenGeni workspace bot. Neither may
-  // become a workspace-owned connection reference.
-  const personalOnly =
-    item.metadata.connectionOwnership === "personal_only" ||
-    endpointUrl === officialGmailMcpUrl ||
-    endpointUrl === OPENGENI_PERSONAL_SLACK_MCP_URL;
-  if (personalOnly && subjectScope !== "subject") {
-    throw new HTTPException(422, {
-      message:
-        "this capability requires a personal connection; each workspace member must connect their own account",
-    });
-  }
   const normalized: McpServerConnectionRef = {
     providerDomain: ref.providerDomain.trim(),
     subjectScope,
     ...(ref.connectionId ? { connectionId: ref.connectionId } : {}),
+    ...(ref.accountSelection ? { accountSelection: ref.accountSelection } : {}),
     ...(ref.authoritySource === "host" ? { authoritySource: "host" as const } : {}),
     ...(ref.provider ? { provider: ref.provider.trim() } : {}),
     ...(ref.kind ? { kind: ref.kind } : {}),
@@ -468,7 +660,7 @@ async function validateMcpCapabilityConnectionRef(
     });
   }
   if (normalized.authoritySource === "host") {
-    assertHostMcpAuthoritySourceAdmissionEnabled(input.settings, normalized);
+    assertNativeMcpConnectionRef(normalized);
     return normalized;
   }
 
@@ -480,7 +672,11 @@ async function validateMcpCapabilityConnectionRef(
         input.grant.subjectId,
       )
     : null;
-  if (!connection && subjectScope === "subject" && !normalized.connectionId) {
+  if (
+    !connection &&
+    !normalized.connectionId &&
+    (subjectScope === "subject" || normalized.accountSelection === "all_eligible")
+  ) {
     const visible = await listConnectionsMetadata(
       input.db,
       input.workspaceId,
@@ -489,7 +685,7 @@ async function validateMcpCapabilityConnectionRef(
     connection =
       visible.find(
         (candidate) =>
-          candidate.subjectId === input.grant.subjectId &&
+          candidate.subjectId === (subjectScope === "subject" ? input.grant.subjectId : null) &&
           candidate.providerDomain === normalized.providerDomain &&
           (!normalized.kind || candidate.kind === normalized.kind) &&
           candidate.status === "active",
@@ -589,6 +785,7 @@ export type McpCapabilityProbeInput = {
   url: string;
   timeoutMs: number;
   headers?: Record<string, string>;
+  settings?: Settings;
 };
 
 export type McpCapabilityProbeResult = {
@@ -603,6 +800,7 @@ export async function validateMcpCapabilityConnection(
   item: CapabilityCatalogItem,
   probe: McpCapabilityProbe = probeStreamableHttpMcpServer,
   headers?: Record<string, string>,
+  settings?: Settings,
 ): Promise<Record<string, unknown>> {
   if (item.kind !== "mcp") {
     return {};
@@ -619,6 +817,7 @@ export async function validateMcpCapabilityConnection(
       url: item.endpointUrl,
       timeoutMs: mcpCapabilityProbeTimeoutMs,
       ...(headers ? { headers } : {}),
+      ...(settings ? { settings } : {}),
     });
     return {
       mcpConnectivity: {
@@ -637,6 +836,8 @@ export async function validateMcpCapabilityConnection(
 async function probeStreamableHttpMcpServer(
   input: McpCapabilityProbeInput,
 ): Promise<McpCapabilityProbeResult> {
+  const settings = input.settings;
+  if (!settings) throw new Error("Network policy is unavailable for MCP validation");
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), input.timeoutMs);
   const client = new Client(
@@ -649,6 +850,11 @@ async function probeStreamableHttpMcpServer(
         signal: controller.signal,
         ...(input.headers ? { headers: input.headers } : {}),
       },
+      fetch: (url, init) =>
+        pinnedFetch(url, init, settings, {
+          label: "MCP capability probe",
+          requireHttpsOutsideLocalTest: true,
+        }),
     });
     await client.connect(transport as unknown as Transport, {
       timeout: input.timeoutMs,
@@ -674,9 +880,9 @@ function mcpProbeErrorMessage(error: unknown, endpointUrl: string): string {
       normalized,
     )
   ) {
-    return `OpenGeni could not reach a valid Streamable HTTP MCP server at ${endpoint}. Check the endpoint URL or choose a different catalog entry.`;
+    return `Opengeni could not reach a valid Streamable HTTP MCP server at ${endpoint}. Check the endpoint URL or choose a different catalog entry.`;
   }
-  return `OpenGeni could not initialize ${endpoint}. Check the endpoint configuration or try again.`;
+  return `Opengeni could not initialize ${endpoint}. Check the endpoint configuration or try again.`;
 }
 
 function safeEndpointLabel(endpointUrl: string): string {
@@ -715,11 +921,7 @@ export async function disableCapability(input: {
       message: "Remove Plugins through the Plugin Package flow",
     });
   }
-  if (item.kind === "pack") {
-    throw new HTTPException(409, {
-      message: "Uninstall Packs through the Pack uninstall preview flow",
-    });
-  }
+
   if (item.source === "built_in" || item.source === "configured") {
     throw new HTTPException(409, {
       message:
@@ -742,27 +944,111 @@ export async function settingsWithEnabledCapabilityMcpServers(
     subjectId?: string;
     personalConnectionDelegations?: readonly McpPersonalConnectionDelegation[];
     onResolvedApiIntegrations?: (integrations: readonly ApiIntegrationRuntime[]) => void;
+    /** Every enabled capability server read, before static-id shadowing. */
+    onResolvedCapabilityServers?: (servers: readonly EnabledMcpCapabilityServer[]) => void;
+    /**
+     * The Codex Apps designation the caller already resolves (a claim reads
+     * its cutover once), or what it knows for resolving it here.
+     */
+    codexApps?: Promise<CodexAppsDesignationForRun | null> | CodexAppsRunContext;
+    /**
+     * `db` is one bounded transaction: run the reads one after another, since
+     * its RLS scopes must not overlap.
+     */
+    oneReadAtATime?: boolean;
   },
 ): Promise<Settings> {
-  const apiIntegrationsPromise = options?.subjectId
-    ? listInstalledApiIntegrations(db, workspaceId, options.subjectId)
-    : listInstalledApiIntegrationsForDelegations(
-        db,
-        workspaceId,
-        options?.personalConnectionDelegations ?? [],
-      );
-  const [enabled, apiIntegrations, codexAppsCredentialId] = await Promise.all([
-    listEnabledMcpCapabilityServers(db, workspaceId),
-    apiIntegrationsPromise,
-    resolveCodexAppsCredentialIdForRun(db, workspaceId),
-  ]);
+  const readApiIntegrations = () =>
+    options?.subjectId
+      ? listInstalledApiIntegrations(db, workspaceId, options.subjectId)
+      : listInstalledApiIntegrationsForDelegations(
+          db,
+          workspaceId,
+          options?.personalConnectionDelegations ?? [],
+        );
+  // Registration is dropped below when Apps are off for the deployment, so
+  // resolving the designation then would be pure cost.
+  const readCodexAppsDesignation = () =>
+    !settings.codexConnectedAppsEnabled
+      ? Promise.resolve(null)
+      : options?.codexApps instanceof Promise
+        ? options.codexApps
+        : resolveCodexAppsDesignationForRun(db, workspaceId, options?.codexApps ?? {});
+  let enabled: Awaited<ReturnType<typeof listEnabledMcpCapabilityServers>>;
+  let apiIntegrations: Awaited<ReturnType<typeof readApiIntegrations>>;
+  let codexAppsDesignation: Awaited<ReturnType<typeof readCodexAppsDesignation>>;
+  if (options?.oneReadAtATime) {
+    enabled = await listEnabledMcpCapabilityServers(db, workspaceId);
+    apiIntegrations = await readApiIntegrations();
+    codexAppsDesignation = await readCodexAppsDesignation();
+  } else {
+    // The integration read starts first: callers that pass a transaction rely
+    // on its subject scope being established before the other reads begin.
+    const apiIntegrationsPromise = readApiIntegrations();
+    [enabled, apiIntegrations, codexAppsDesignation] = await Promise.all([
+      listEnabledMcpCapabilityServers(db, workspaceId),
+      apiIntegrationsPromise,
+      readCodexAppsDesignation(),
+    ]);
+  }
   options?.onResolvedApiIntegrations?.(apiIntegrations);
+  options?.onResolvedCapabilityServers?.(enabled);
+  return settingsWithCodexAppsMcpServer(
+    settingsWithApiIntegrationServers(
+      settingsWithMcpCapabilityServers(settings, enabled),
+      apiIntegrations,
+    ),
+    codexAppsDesignation !== null,
+  );
+}
+
+/**
+ * `settingsWithEnabledCapabilityMcpServers` for a live target fence: only the
+ * rows that can produce `serverIds`. That is the capability installations that
+ * produced them at preparation plus any catalog item explicitly claiming one of
+ * those ids (shadowing), integrations with exactly those runtime keys (read
+ * with the same subject visibility), and the Codex designation only when Codex
+ * Apps itself is a target. Static servers come from `settings`, unchanged.
+ * Restricted to `serverIds`, the result equals the complete projection.
+ */
+export async function settingsWithEnabledCapabilityMcpServersForTargets(
+  db: Database,
+  workspaceId: string,
+  settings: Settings,
+  options: {
+    subjectId: string;
+    accountId: string;
+    serverIds: readonly string[];
+    capabilityIds: readonly string[];
+    onResolvedApiIntegrations?: (integrations: readonly ApiIntegrationRuntime[]) => void;
+    /** Checked between reads: a stopped caller starts no further read. */
+    signal?: AbortSignal;
+  },
+): Promise<Settings> {
+  const serverIds = new Set(options.serverIds);
+  // One RLS scope at a time: `db` may be a single bounded transaction.
+  const enabled = (
+    await listEnabledMcpCapabilityServers(db, workspaceId, {
+      capabilityIds: options.capabilityIds,
+      serverIds: [...serverIds],
+    })
+  ).filter((server) => serverIds.has(server.id));
+  options.signal?.throwIfAborted();
+  const apiIntegrations = await listInstalledApiIntegrations(db, workspaceId, options.subjectId, [
+    ...serverIds,
+  ]);
+  options.signal?.throwIfAborted();
+  const codexAppsDesignation =
+    settings.codexConnectedAppsEnabled && serverIds.has(CODEX_APPS_MCP_SERVER_ID)
+      ? await resolveCodexAppsDesignationForRun(db, workspaceId, { accountId: options.accountId })
+      : null;
+  options.onResolvedApiIntegrations?.(apiIntegrations);
   return settingsWithCodexAppsMcpServer(
     settingsWithApiIntegrationServers(
       settingsWithMcpCapabilityServers(settings, enabled),
       apiIntegrations,
     ),
-    codexAppsCredentialId !== null,
+    codexAppsDesignation !== null,
   );
 }
 
@@ -773,7 +1059,7 @@ export function apiIntegrationsMatchingDelegations(
   const exact = new Set(
     delegations.map((delegation) =>
       [
-        delegation.serverId,
+        delegation.canonicalServerId ?? delegation.serverId,
         delegation.connectionId,
         delegation.providerDomain.toLowerCase(),
         delegation.kind ?? "",
@@ -842,19 +1128,77 @@ export function settingsWithApiIntegrationServers(
 }
 
 /**
- * Resolve executable Apps authority. The connector must remain active and its
- * exact owner must still hold workspace connection-management permission.
+ * The workspace's executable Codex Apps designation. Without a Codex cutover
+ * row this is the legacy designation (`resolveCodexAppsCredentialIdForRun`).
+ * With an enabled cutover it is the core designation, which the database
+ * rechecks (designated shared Codex connection, still in the workspace's
+ * scope, active). A disabled cutover row designates nothing and reads no
+ * legacy Codex table.
+ */
+export type CodexAppsDesignationForRun = {
+  source: "core";
+  accountId: string;
+  connectionId: string;
+};
+
+/**
+ * What the caller already knows, so the resolver does not read it again: the
+ * workspace's organization (skips the workspace lookup) and the organization's
+ * Codex cutover disposition (skips the cutover read; a claim has read it).
+ */
+export type CodexAppsRunContext = {
+  accountId?: string;
+  disposition?: CodexCutoverDisposition | Promise<CodexCutoverDisposition>;
+};
+
+export async function resolveCodexAppsDesignationForRun(
+  db: Database,
+  workspaceId: string,
+  known: CodexAppsRunContext = {},
+): Promise<CodexAppsDesignationForRun | null> {
+  let owner = known.accountId;
+  const accountId = async () =>
+    (owner ??= (await rlsContextForWorkspace(db, workspaceId)).accountId);
+  const disposition =
+    known.disposition !== undefined
+      ? await known.disposition
+      : await readCodexCutoverDisposition(db, await accountId(), workspaceId);
+  if (disposition === "maintenance") return null;
+  const coreAccountId = await accountId();
+  const designation = await resolveSubscriptionCoreCodexAppsDesignation(db, {
+    accountId: coreAccountId,
+    workspaceId,
+  });
+  return designation?.status === "active"
+    ? { source: "core", accountId: coreAccountId, connectionId: designation.connectionId }
+    : null;
+}
+
+/** Runtime Apps authentication for whichever designation `resolveCodexAppsDesignationForRun` returned. */
+export function codexAppsRequestAuthForDesignation(
+  db: Database,
+  settings: Settings,
+  workspaceId: string,
+  designation: CodexAppsDesignationForRun,
+): SubscriptionCoreCodexAppsRequestAuth {
+  return subscriptionCoreCodexAppsRequestAuth(db, settings, {
+    accountId: designation.accountId,
+    workspaceId,
+    connectionId: designation.connectionId,
+  });
+}
+
+/**
+ * Resolve the legacy executable Apps authority. Organizations with a Codex
+ * cutover row (enabled or disabled) have none here: their designation lives
+ * on the core (`resolveCodexAppsDesignationForRun`).
  */
 export async function resolveCodexAppsCredentialIdForRun(
   db: Database,
   workspaceId: string,
 ): Promise<string | null> {
-  const authorization = await getCodexAppsCredentialAuthorizationForRun(db, workspaceId);
-  if (!authorization) return null;
-  const grant = await getWorkspaceGrant(db, authorization.ownerSubjectId, workspaceId);
-  return grant && hasPermission(grant.permissions, "connections:write")
-    ? authorization.credentialId
-    : null;
+  const designation = await resolveCodexAppsDesignationForRun(db, workspaceId);
+  return designation?.connectionId ?? null;
 }
 
 /**
@@ -1055,56 +1399,10 @@ async function requireCatalogItem(
   return item;
 }
 
-function packCatalogItem(
-  pack: ReturnType<typeof listCapabilityPacks>[number],
-  source: "built_in" | "manual",
-): CapabilityCatalogItem {
-  const customMetadata = { ...pack.metadata };
-  for (const key of [
-    "packId",
-    "version",
-    "connectors",
-    "knowledge",
-    "scheduledTaskTemplates",
-    "sandboxImage",
-    "sandboxProviderImages",
-    "skills",
-  ]) {
-    delete customMetadata[key];
-  }
-  return CapabilityCatalogItem.parse({
-    id: `pack:${pack.id}`,
-    kind: "pack",
-    source,
-    name: pack.name,
-    description: pack.description,
-    category: pack.category,
-    tags: [pack.role, pack.category, "pack"],
-    tools: pack.tools,
-    runtime: {
-      available: true,
-      notes: "Enables role-scoped tools, connectors, knowledge, and scheduled-task templates.",
-    },
-    metadata: {
-      ...customMetadata,
-      packId: pack.id,
-      version: pack.version,
-      connectors: pack.connectors,
-      knowledge: pack.knowledge,
-      scheduledTaskTemplates: pack.scheduledTaskTemplates,
-      ...(pack.variableSet ? { variableSet: pack.variableSet } : {}),
-      // Runtime composition surface only: skill names, never file content.
-      ...(pack.sandboxImage ? { sandboxImage: pack.sandboxImage } : {}),
-      ...(pack.sandboxProviderImages ? { sandboxProviderImages: pack.sandboxProviderImages } : {}),
-      ...(pack.skills.length > 0 ? { skills: pack.skills.map((skill) => skill.name) } : {}),
-    },
-  });
-}
-
 function configuredMcpCatalogItems(settings: Settings): CapabilityCatalogItem[] {
   return (
     settings.mcpServers
-      // OpenGeni, Files, and Document Search are native runtime surfaces. They
+      // Opengeni, Files, and Document Search are native runtime surfaces. They
       // remain available to sessions through configuration, but are not things a
       // user installs, connects, or enables in the Capabilities control center.
       .filter(
@@ -1121,12 +1419,23 @@ function configuredMcpCatalogItems(settings: Settings): CapabilityCatalogItem[]
           category: "configured",
           tags: ["mcp", ...(server.allowedTools?.length ? ["limited-tools"] : [])],
           endpointUrl: server.url,
+          authKind:
+            server.connectionRef?.authoritySource !== "host" &&
+            server.connectionRef?.kind === "oauth2"
+              ? "oauth2"
+              : null,
+          // Deployment-managed personal selectors need the same account picker
+          // as installed connectors. Fixed bindings remain server-resolved.
+          connectionRef:
+            server.connectionRef?.subjectScope === "subject" && !server.connectionRef.connectionId
+              ? installationConnectionRef({ connectionRef: server.connectionRef })
+              : null,
           tools: [{ kind: "mcp", id: server.id }],
           runtime: {
             available: true,
             mcpServerId: server.id,
             transport: "streamable-http",
-            notes: "Managed by this OpenGeni deployment through OPENGENI_MCP_SERVERS.",
+            notes: "Managed by this Opengeni deployment through OPENGENI_MCP_SERVERS.",
           },
           metadata: {
             mcpServerId: server.id,
@@ -1262,7 +1571,7 @@ function fikenCatalogItem(fikenConnections: ConnectionMetadata[]): CapabilityCat
     runtime: {
       available: true,
       mcpServerId: "opengeni",
-      notes: "Fiken access is provided through OpenGeni's first-party fiken tools.",
+      notes: "Fiken access is provided through Opengeni's first-party fiken tools.",
     },
     enabled: fikenEnabled,
     enabledReason: fikenEnabled
@@ -1273,6 +1582,7 @@ function fikenCatalogItem(fikenConnections: ConnectionMetadata[]): CapabilityCat
     metadata: {
       connectorMode: "first_party_fiken",
       ownership: "workspace",
+      connectionStatus: fikenConnection?.status ?? null,
       // Derived from the contracts catalog so a new fiken_* tool cannot be
       // registered without also appearing on the capability tile.
       firstPartyMcpTools: FIRST_PARTY_MCP_TOOL_NAMES.filter((name) => name.startsWith("fiken_")),
@@ -1280,6 +1590,52 @@ function fikenCatalogItem(fikenConnections: ConnectionMetadata[]): CapabilityCat
   });
 }
 
+/**
+ * The 1Password tile (design §10.9). Connecting a service account happens in
+ * Settings > Secrets (`POST /connections/1password/install`); its vaults are
+ * then reached through secret references and the secrets tools, not MCP.
+ * Enabled while a workspace-shared 1Password connection is active.
+ */
+function onePasswordCatalogItem(connections: ConnectionMetadata[]): CapabilityCatalogItem {
+  const active = connections.filter((connection) => connection.status === "active");
+  const enabled = active.length > 0;
+  return CapabilityCatalogItem.parse({
+    id: "api:1password",
+    kind: "api",
+    source: "built_in",
+    name: "1Password",
+    description:
+      "Connect a 1Password service account so its vaults appear as read-only or read-write secret vaults.",
+    category: "security",
+    tags: ["api", "1password", "password-manager", "secrets", "vaults"],
+    homepageUrl: "https://1password.com",
+    authModel: "service_account_token",
+    providerDomain: "1password.com",
+    surfaceType: "first_party_onepassword",
+    authKind: "api_key",
+    tools: [],
+    runtime: {
+      available: true,
+      notes: "1Password vaults are used through secret references and the secrets tools.",
+    },
+    enabled,
+    enabledReason: enabled
+      ? `${active.length === 1 ? "1Password connection" : `${active.length} 1Password connections`} active`
+      : null,
+    metadata: {
+      connectorMode: "first_party_onepassword",
+      connectionCount: connections.length,
+      planTiers: [
+        ...new Set(
+          connections.map(
+            (connection) => onePasswordConnectionMetadata(connection.metadata)?.planTier,
+          ),
+        ),
+      ].filter(Boolean),
+    },
+  });
+}
+
 function providerIntegrationCatalogItems(
   socialConnections: SocialConnection[],
 ): CapabilityCatalogItem[] {
@@ -1304,11 +1660,11 @@ function providerIntegrationCatalogItems(
         available: true,
         mcpServerId: "opengeni",
         notes:
-          "OpenGeni's social provider adapter routes every call through an exact visible account Connection.",
+          "Opengeni's social provider adapter routes every call through an exact visible account Connection.",
       },
       enabled,
       enabledReason: socialConnectionSummary(counts),
-      provenance: "OpenGeni provider adapter",
+      provenance: "Opengeni provider adapter",
       metadata: {
         providerAdapter: "social",
         provider: definition.provider,
@@ -1326,14 +1682,21 @@ function providerIntegrationCatalogItems(
  * recommend the owning product flow without manufacturing an enabled catalog
  * row for GitHub resources, Documents, schedules, or other platform features.
  */
-export function nativeConnectionCapabilityRecommendations(): CapabilityCatalogItem[] {
-  return [
+/** The in-chat card id for connecting a person's own computer. */
+export const CONNECTED_MACHINE_CAPABILITY_ID = "api:connected-machine";
+
+export { OPENGENI_BROWSER_EXTENSION_URL };
+
+export function nativeConnectionCapabilityRecommendations(
+  options: { connectedMachines?: boolean } = {},
+): CapabilityCatalogItem[] {
+  const items = [
     CapabilityCatalogItem.parse({
       id: "api:github-app",
       kind: "api",
       source: "built_in",
       name: "GitHub App",
-      description: "Connect repositories through OpenGeni's GitHub resource picker.",
+      description: "Connect repositories through Opengeni's GitHub resource picker.",
       category: "source-control",
       tags: ["github", "repositories", "source-control"],
       homepageUrl: "https://github.com",
@@ -1361,6 +1724,66 @@ export function nativeConnectionCapabilityRecommendations(): CapabilityCatalogIt
       },
     }),
   ];
+  if (options.connectedMachines) {
+    items.push(
+      CapabilityCatalogItem.parse({
+        id: CONNECTED_MACHINE_CAPABILITY_ID,
+        kind: "api",
+        source: "built_in",
+        name: "Connected Machine",
+        description:
+          "Run this chat on the person's own computer or server (Mac, Linux or Windows), and optionally let agents use their Chrome through the Opengeni Browser extension.",
+        category: "compute",
+        tags: [
+          "machine",
+          "computer",
+          "laptop",
+          "desktop",
+          "mac",
+          "macbook",
+          "linux",
+          "windows",
+          "server",
+          "gpu",
+          "local",
+          "self-hosted",
+          "chrome",
+          "browser",
+          "extension",
+          "terminal",
+        ],
+        homepageUrl: null,
+        providerDomain: "opengeni.ai",
+        authModel: "connected_machine_enrollment",
+        authKind: "none",
+        surfaceType: "first_party_connected_machine",
+        tools: [{ kind: "mcp", id: "opengeni" }],
+        runtime: {
+          available: true,
+          notes: `The person runs a one-line connect command on their machine from the chat card. The Opengeni Browser Chrome extension (${OPENGENI_BROWSER_EXTENSION_URL}) works only after the machine is connected.`,
+        },
+        lifecycle: {
+          status: "available",
+          readiness: "setup_required",
+          detail: "Connect a machine from the chat card.",
+          managedBy: "platform",
+        },
+        actions: ["connect", "inspect"],
+        metadata: {
+          firstPartyMcpTools: [
+            "sandboxes_list",
+            "sandbox_swap",
+            "run_on",
+            "connected_machine_enroll_token",
+            "connected_machine_enable_screen_control",
+          ],
+          browserExtensionUrl: OPENGENI_BROWSER_EXTENSION_URL,
+          recommendationOnly: true,
+        },
+      }),
+    );
+  }
+  return items;
 }
 
 function socialConnectionCounts(
@@ -1521,31 +1944,21 @@ function socialProviderConnectionCounts(item: CapabilityCatalogItem): {
 export function applyCapabilityEnablement(
   item: CapabilityCatalogItem,
   installation: CapabilityInstallation | undefined,
-  activePackIds: Set<string>,
 ): CapabilityCatalogItem {
+  if (item.surfaceType === "first_party_fiken" || item.surfaceType === "first_party_onepassword") {
+    // Fiken and 1Password are API items with connection-derived state, not
+    // generic API installations. Preserve that state before the non-MCP fallback below.
+    return { ...item, connectionRef: null };
+  }
   if (item.kind === "skill" || item.kind === "api" || item.kind === "plugin") {
     return { ...item, enabled: false, enabledReason: null, connectionRef: null };
   }
-  if (item.kind === "pack") {
-    const enabled = activePackIds.has(packIdFromCapabilityId(item.id));
-    return {
-      ...item,
-      enabled,
-      enabledReason: enabled ? "enabled" : null,
-    };
-  }
   if (isSocialProviderIntegration(item)) {
     // Provider-integration state is derived from every authoritative visible
     // social Connection while the catalog is built. The catalog summary never
     // publishes a personal connection UUID or collapses many accounts to one.
     return { ...item, connectionRef: null };
   }
-  if (item.surfaceType === "first_party_fiken") {
-    // Fiken connector state is derived from the authoritative workspace
-    // connection row while the catalog is built; browseable never means an
-    // account is already connected.
-    return { ...item, connectionRef: null };
-  }
   if (item.surfaceType === "codex_apps") {
     // Unlike ordinary built-ins, Apps availability is derived from the exact
     // active workspace designation above. Do not overwrite it with the
@@ -1557,7 +1970,7 @@ export function applyCapabilityEnablement(
       ...item,
       enabled: true,
       enabledReason: "managed by deployment",
-      connectionRef: null,
+      connectionRef: item.connectionRef,
     };
   }
   if (item.source === "built_in") {
@@ -1568,11 +1981,17 @@ export function applyCapabilityEnablement(
   }
   const activeInstallation = installation?.status === "active";
   const enabled = !!activeInstallation && capabilityInstallationRuntimeReady(item, installation);
+  const connectionRef =
+    enabled && installation ? installationConnectionRef(installation.config) : null;
   return {
     ...item,
+    // Older custom entries recorded the native credential kind on the
+    // installation only. Project it without guessing from a URL or overwriting
+    // an explicit catalog authentication contract.
+    authKind: item.authKind ?? (connectionRef?.kind === "oauth2" ? "oauth2" : null),
     enabled,
     enabledReason: enabled ? "enabled" : null,
-    connectionRef: enabled && installation ? installationConnectionRef(installation.config) : null,
+    connectionRef,
   };
 }
 
@@ -1599,7 +2018,10 @@ function applyCapabilityLifecycle(item: CapabilityCatalogItem): CapabilityCatalo
         detail: item.runtime.notes,
         managedBy: item.source === "built_in" ? "platform" : null,
       },
-      actions: ["inspect"],
+      actions:
+        item.enabled && item.kind === "mcp" && item.source !== "built_in"
+          ? ["disconnect", "inspect"]
+          : ["inspect"],
     };
   }
 
@@ -1638,7 +2060,7 @@ function applyCapabilityLifecycle(item: CapabilityCatalogItem): CapabilityCatalo
 
   const installed = item.enabled;
   const actions: CapabilityAction[] = installed
-    ? item.kind === "pack" || item.kind === "skill" || item.kind === "plugin"
+    ? item.kind === "skill" || item.kind === "plugin"
       ? ["configure", "update", "uninstall", "inspect"]
       : ["configure", "disconnect", "inspect"]
     : item.kind === "mcp" || item.kind === "api"
@@ -1701,24 +2123,34 @@ function installationConnectionRef(
   if (!ref || typeof ref !== "object") {
     return null;
   }
-  const { authoritySource, connectionId, providerDomain, kind, subjectScope } = ref as Record<
-    string,
-    unknown
-  >;
+  const { authoritySource, connectionId, providerDomain, kind, subjectScope, accountSelection } =
+    ref as Record<string, unknown>;
   if (typeof providerDomain !== "string" || typeof kind !== "string") {
     return null;
   }
   if (authoritySource === "host") {
     // The internal installation/runtime ref retains the exact host binding.
     // Public capability catalogs use the existing null representation for an
-    // enabled capability without a native OpenGeni connection, so indefinitely
+    // enabled capability without a native Opengeni connection, so indefinitely
     // open old browser bundles cannot treat a host UUID as native OAuth state.
     return null;
   }
+  if (accountSelection === "all_eligible" && connectionId === undefined) {
+    return {
+      providerDomain,
+      kind,
+      accountSelection,
+      ...(subjectScope === "subject" ? { subjectScope } : {}),
+    };
+  }
   if (subjectScope === "subject") {
     // Never project a native personal connection UUID through workspace-visible
     // capability configuration, including legacy rows that still contain one.
-    return { providerDomain, kind, subjectScope: "subject" };
+    return {
+      providerDomain,
+      kind,
+      subjectScope: "subject",
+    };
   }
   if (typeof connectionId !== "string") {
     return null;
@@ -1753,13 +2185,42 @@ export type CapabilityCatalogSearchMatch = {
   item: CapabilityCatalogItem;
   score: number;
   matchedOn: Array<"name" | "provider" | "tag" | "category" | "description" | "id">;
+  /**
+   * True when the item matched only through the typo-tolerant tier (an edit
+   * distance hit), never through an exact, prefix, or substring hit.
+   */
+  approximate: boolean;
+};
+
+export type CapabilityCatalogSuggestion = {
+  item: CapabilityCatalogItem;
+  /** Name similarity to the query in [0, 1]; 1 means identical once normalized. */
+  similarity: number;
 };
 
+// Typo tolerance stays deterministic and bounded: tokens shorter than four
+// characters never fuzz, compared strings are capped, and only identity fields
+// (name, provider domain, tags) participate in the fuzzy tier.
+const FUZZY_MIN_TOKEN_LENGTH = 4;
+const FUZZY_PREFIX_MIN_TOKEN_LENGTH = 5;
+const FUZZY_MAX_COMPARED_LENGTH = 48;
+const FUZZY_MAX_TOKENS = 8;
+const FUZZY_FIELDS = new Set<CapabilityCatalogSearchMatch["matchedOn"][number]>([
+  "name",
+  "provider",
+  "tag",
+]);
+
 /**
  * Deterministically rank the already-merged workspace catalog for an agent.
  * The caller still owns live authorization checks (GitHub binding, OAuth row,
  * and so on); this function searches metadata only and never probes a provider
  * or exposes credential/setup prose to the model.
+ *
+ * Exact word, prefix, and substring hits rank first. A typo-tolerant tier
+ * (bounded Damerau-Levenshtein on name, provider-domain, and tag words, plus
+ * the space-stripped name against the space-stripped query) contributes a
+ * smaller score so a one-letter spelling difference still finds the entry.
  */
 export function searchCapabilityCatalogItems(
   items: readonly CapabilityCatalogItem[],
@@ -1769,11 +2230,13 @@ export function searchCapabilityCatalogItems(
   const phrase = normalizeCapabilitySearchText(query);
   const tokens = [...new Set(phrase.split(" ").filter(Boolean))].slice(0, 24);
   if (tokens.length === 0) return [];
+  const compactPhrase = phrase.replaceAll(" ", "");
+  const fuzzyTokens = tokens.slice(0, FUZZY_MAX_TOKENS);
   const boundedLimit = Math.min(20, Math.max(1, Math.trunc(limit)));
   const weightedFields = (item: CapabilityCatalogItem) =>
     [
       ["name", item.name, 100],
-      ["provider", item.providerDomain ?? "", 80],
+      ["provider", capabilityCatalogSearchProviderDomain(item) ?? "", 80],
       ["tag", item.tags.join(" "), 50],
       ["category", item.category, 30],
       ["id", item.id, 25],
@@ -1784,25 +2247,54 @@ export function searchCapabilityCatalogItems(
     .filter((item) => capabilityCatalogItemIsTrustedForExposure(item))
     .flatMap((item): CapabilityCatalogSearchMatch[] => {
       let score = 0;
+      let approximate = true;
       const matchedOn = new Set<CapabilityCatalogSearchMatch["matchedOn"][number]>();
+      const hit = (
+        field: CapabilityCatalogSearchMatch["matchedOn"][number],
+        points: number,
+        fuzzy = false,
+      ) => {
+        score += points;
+        matchedOn.add(field);
+        if (!fuzzy) approximate = false;
+      };
       for (const [field, raw, weight] of weightedFields(item)) {
         const value = normalizeCapabilitySearchText(raw);
         if (!value) continue;
         const words = value.split(" ");
+        const fuzzyField = FUZZY_FIELDS.has(field);
         if (value.includes(phrase)) {
-          score += Math.round(weight * 1.5);
-          matchedOn.add(field);
+          hit(field, Math.round(weight * 1.5));
+        } else if (fuzzyField && compactPhrase.length >= FUZZY_MIN_TOKEN_LENGTH) {
+          // Compare with separators removed so "wispr flow" meets "WisprFlow"
+          // and "wisprflow" meets "Wispr Flow"; a near miss is typo-tolerant.
+          const compactValue = value.replaceAll(" ", "");
+          const budget = fuzzyEditBudget(compactPhrase.length);
+          if (compactValue.includes(compactPhrase)) {
+            hit(field, weight);
+          } else {
+            const distance = boundedEditDistance(compactPhrase, compactValue, budget);
+            if (distance.whole <= budget) {
+              hit(field, Math.round(weight * 0.5), true);
+            } else if (
+              compactPhrase.length >= FUZZY_PREFIX_MIN_TOKEN_LENGTH &&
+              distance.prefix <= budget
+            ) {
+              hit(field, Math.round(weight * 0.3), true);
+            }
+          }
         }
         for (const token of tokens) {
           if (words.includes(token)) {
-            score += weight;
-            matchedOn.add(field);
+            hit(field, weight);
           } else if (words.some((word) => word.startsWith(token) || token.startsWith(word))) {
-            score += Math.round(weight * 0.7);
-            matchedOn.add(field);
+            hit(field, Math.round(weight * 0.7));
           } else if (value.includes(token)) {
-            score += Math.round(weight * 0.4);
-            matchedOn.add(field);
+            hit(field, Math.round(weight * 0.4));
+          } else if (fuzzyField && fuzzyTokens.includes(token)) {
+            const fuzzy = fuzzyWordMatch(token, words);
+            if (fuzzy === "word") hit(field, Math.round(weight * 0.3), true);
+            else if (fuzzy === "prefix") hit(field, Math.round(weight * 0.2), true);
           }
         }
       }
@@ -1810,7 +2302,7 @@ export function searchCapabilityCatalogItems(
       if (item.enabled) score += 12;
       if (item.tier === "verified") score += 8;
       if (item.source === "built_in") score += 6;
-      return [{ item, score, matchedOn: [...matchedOn] }];
+      return [{ item, score, matchedOn: [...matchedOn], approximate }];
     })
     .sort(
       (left, right) =>
@@ -1822,6 +2314,167 @@ export function searchCapabilityCatalogItems(
     .slice(0, boundedLimit);
 }
 
+/**
+ * Closest catalog names for a query that matched nothing. A miss must never
+ * read as "this integration does not exist" while the workspace has entries,
+ * so callers surface these as explicitly labelled suggestions. An empty
+ * (all-punctuation) query returns the first entries by name for browsing.
+ */
+export function suggestCapabilityCatalogItems(
+  items: readonly CapabilityCatalogItem[],
+  query: string,
+  limit = 5,
+): CapabilityCatalogSuggestion[] {
+  const boundedLimit = Math.min(20, Math.max(1, Math.trunc(limit)));
+  const compactPhrase = normalizeCapabilitySearchText(query)
+    .replaceAll(" ", "")
+    .slice(0, FUZZY_MAX_COMPARED_LENGTH);
+  return items
+    .filter((item) => capabilityCatalogItemIsTrustedForExposure(item))
+    .map((item): CapabilityCatalogSuggestion => {
+      if (!compactPhrase) return { item, similarity: 0 };
+      let best = 0;
+      for (const raw of [item.name, capabilityCatalogSearchProviderDomain(item) ?? ""]) {
+        const candidate = normalizeCapabilitySearchText(raw)
+          .replaceAll(" ", "")
+          .slice(0, FUZZY_MAX_COMPARED_LENGTH);
+        if (!candidate) continue;
+        const distance = boundedEditDistance(compactPhrase, candidate, FUZZY_MAX_COMPARED_LENGTH);
+        best = Math.max(
+          best,
+          1 - distance.whole / Math.max(compactPhrase.length, candidate.length),
+          // A query that resembles the start of a longer name ("wspr" for
+          // "Whisprflow") is as informative as a whole-name resemblance.
+          1 - distance.prefix / compactPhrase.length,
+        );
+      }
+      return { item, similarity: Math.round(Math.max(0, best) * 100) / 100 };
+    })
+    .sort(
+      (left, right) =>
+        right.similarity - left.similarity ||
+        Number(right.item.enabled) - Number(left.item.enabled) ||
+        left.item.name.localeCompare(right.item.name) ||
+        left.item.id.localeCompare(right.item.id),
+    )
+    .slice(0, boundedLimit);
+}
+
+/**
+ * The vendor domain search may match. A stored providerDomain wins. Workspace
+ * and operator entries (manual, configured, built-in) without one fall back to
+ * the registrable domain of their endpoint (api.wisprflow.ai -> wisprflow.ai).
+ * Registry rows do not: their endpoints may sit on a third-party host. This is
+ * a search-only projection and never changes the stored item or any
+ * connection/authority matching.
+ */
+export function capabilityCatalogSearchProviderDomain(item: CapabilityCatalogItem): string | null {
+  const stored = item.providerDomain?.trim();
+  if (stored) return stored;
+  if (item.source === "registry" || item.source === "public_registry") return null;
+  for (const candidate of [item.endpointUrl, item.mcpUrl, item.homepageUrl]) {
+    if (!candidate) continue;
+    const domain = registrableDomain(candidate);
+    if (domain) return domain;
+  }
+  return null;
+}
+
+// Common two-label public suffixes. Without a full public-suffix list this
+// keeps hosts such as api.example.co.uk on example.co.uk rather than co.uk.
+const TWO_LABEL_PUBLIC_SUFFIXES = new Set([
+  "ac.uk",
+  "co.uk",
+  "gov.uk",
+  "org.uk",
+  "com.au",
+  "net.au",
+  "org.au",
+  "co.nz",
+  "co.jp",
+  "co.kr",
+  "co.in",
+  "co.za",
+  "com.br",
+  "com.cn",
+  "com.mx",
+  "com.sg",
+  "com.tr",
+]);
+
+function registrableDomain(url: string): string | null {
+  let hostname: string;
+  try {
+    hostname = new URL(url).hostname.toLowerCase().replace(/\.$/, "");
+  } catch {
+    return null;
+  }
+  if (!hostname || hostname.includes(":") || /^\d+(\.\d+){3}$/.test(hostname)) return null;
+  const labels = hostname.split(".").filter(Boolean);
+  if (labels.length <= 2) return labels.join(".") || null;
+  const lastTwo = labels.slice(-2).join(".");
+  return TWO_LABEL_PUBLIC_SUFFIXES.has(lastTwo) ? labels.slice(-3).join(".") : lastTwo;
+}
+
+function fuzzyEditBudget(length: number): number {
+  if (length < FUZZY_MIN_TOKEN_LENGTH) return 0;
+  return length >= 8 ? 2 : 1;
+}
+
+function fuzzyWordMatch(token: string, words: readonly string[]): "word" | "prefix" | null {
+  const budget = fuzzyEditBudget(token.length);
+  if (budget === 0 || token.length > FUZZY_MAX_COMPARED_LENGTH) return null;
+  let prefixHit = false;
+  for (const word of words) {
+    const lengthGap = Math.abs(word.length - token.length);
+    const prefixCandidate =
+      token.length >= FUZZY_PREFIX_MIN_TOKEN_LENGTH && word.length > token.length;
+    if (lengthGap > budget && !prefixCandidate) continue;
+    const distance = boundedEditDistance(token, word, budget);
+    if (lengthGap <= budget && distance.whole <= budget) return "word";
+    if (prefixCandidate && distance.prefix <= budget) prefixHit = true;
+  }
+  return prefixHit ? "prefix" : null;
+}
+
+/**
+ * Optimal-string-alignment (restricted Damerau-Levenshtein) distance from
+ * `source` to all of `target` (`whole`) and to its closest prefix (`prefix`).
+ * Both inputs are capped at FUZZY_MAX_COMPARED_LENGTH, and the computation
+ * stops early once every cell of a row exceeds `budget`, returning budget + 1.
+ */
+function boundedEditDistance(
+  source: string,
+  target: string,
+  budget: number,
+): { whole: number; prefix: number } {
+  const a = source.slice(0, FUZZY_MAX_COMPARED_LENGTH);
+  const b = target.slice(0, FUZZY_MAX_COMPARED_LENGTH);
+  const over = budget + 1;
+  const width = b.length + 1;
+  let previousPrevious = new Array<number>(width).fill(0);
+  let previous = Array.from({ length: width }, (_, index) => index);
+  let current = new Array<number>(width).fill(0);
+  for (let i = 1; i <= a.length; i += 1) {
+    current[0] = i;
+    let rowMinimum = current[0];
+    for (let j = 1; j <= b.length; j += 1) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      let value = Math.min(previous[j]! + 1, current[j - 1]! + 1, previous[j - 1]! + cost);
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        value = Math.min(value, previousPrevious[j - 2]! + 1);
+      }
+      current[j] = value;
+      if (value < rowMinimum) rowMinimum = value;
+    }
+    if (rowMinimum > budget) return { whole: over, prefix: over };
+    [previousPrevious, previous, current] = [previous, current, previousPrevious];
+  }
+  let prefix = previous[0]!;
+  for (let j = 1; j <= b.length; j += 1) prefix = Math.min(prefix, previous[j]!);
+  return { whole: Math.min(previous[b.length]!, over), prefix: Math.min(prefix, over) };
+}
+
 function normalizeCapabilitySearchText(value: string): string {
   return value
     .normalize("NFKD")
@@ -1844,10 +2497,6 @@ function publicRegistryCapabilityId(name: string, version: string, endpointUrl:
   return `mcp-registry:${slugify(name)}-${shortHash(`${name}:${version}:${endpointUrl}`)}`;
 }
 
-function packIdFromCapabilityId(capabilityId: string): string {
-  return capabilityId.replace(/^pack:/, "");
-}
-
 function uniqueTags(tags: string[]): string[] {
   return [...new Set(tags.map((tag) => tag.trim()).filter(Boolean))];
 }