@opengeni/core 0.4.10 → 0.8.0

package/src/domain/capabilities.ts

@@ -36,6 +36,11 @@ import {
   type EnabledMcpCapabilityServer,
 } from "@opengeni/db";
 import { HTTPException } from "hono/http-exception";
+import {
+  getSkillLibraryEntry,
+  listSkillLibraryEntries,
+  type SkillLibraryEntry,
+} from "@opengeni/runtime/skill-library";
 import { validateVariableSetAttachment } from "./environments";
 import {
   assertPackSandboxImageCompatible,
@@ -65,12 +70,14 @@ export async function buildCapabilityCatalog(input: {
     packInstallations,
     workspacePacks,
     bundledSkills,
+    curatedLibrarySkills,
   ] = await Promise.all([
     listCapabilityCatalogItems(input.db, input.workspaceId),
     listCapabilityInstallations(input.db, input.workspaceId),
     listPackInstallations(input.db, input.workspaceId),
     listWorkspaceCapabilityPacks(input.db, input.workspaceId),
     discoverBundledSkills(),
+    discoverCuratedSkillLibraryItems(),
   ]);
   const capabilityInstallationById = new Map(
     capabilityInstallations.map((installation) => [installation.capabilityId, installation]),
@@ -88,6 +95,7 @@ export async function buildCapabilityCatalog(input: {
     ...configuredMcpCatalogItems(input.settings),
     ...platformApiCatalogItems(),
     ...bundledSkills,
+    ...curatedLibrarySkills,
   ];
   const items = dedupeCatalogItems([...builtIns, ...persistedItems])
     .map((item) =>
@@ -112,8 +120,14 @@ export async function createCatalogItem(input: {
       message: "packs are managed by OpenGeni and cannot be manually created",
     });
   }
+  if (id.startsWith("skill:")) {
+    throw new HTTPException(422, {
+      message: "skill ids are managed by the OpenGeni skill library or runtime adapters",
+    });
+  }
   const source =
     input.payload.source === "built_in" ||
+    input.payload.source === "library" ||
     input.payload.source === "configured" ||
     input.payload.source === "registry"
       ? "manual"
@@ -169,11 +183,49 @@ export async function enableCapability(input: {
   // Credential-header storage is written exclusively by this flow; strip the
   // reserved keys from caller-provided config so the stored shape stays
   // trustworthy and no plaintext credentials sneak in through config.headers.
-  const installationConfig: Record<string, unknown> = { ...input.payload.config };
+  let installationConfig: Record<string, unknown> = { ...input.payload.config };
   delete installationConfig.headers;
   delete installationConfig.headersEncrypted;
   delete installationConfig.headerNames;
   delete installationConfig.connectionRef;
+  if (item.kind === "skill" && item.source === "library") {
+    const libraryId = stringMetadata(item.metadata.libraryId);
+    const catalogVersion = stringMetadata(item.metadata.version);
+    if (!libraryId || !catalogVersion) {
+      throw new HTTPException(422, {
+        message: `skill library metadata is incomplete for ${item.id}`,
+      });
+    }
+    const requestedVersion = input.payload.config.version;
+    if (requestedVersion !== undefined && typeof requestedVersion !== "string") {
+      throw new HTTPException(422, {
+        message: "skill activation config.version must be a string",
+      });
+    }
+    const normalizedVersion = requestedVersion?.trim() || catalogVersion;
+    if (normalizedVersion !== catalogVersion) {
+      throw new HTTPException(422, {
+        message: `skill ${libraryId} only supports immutable version ${catalogVersion}`,
+      });
+    }
+    const entry = getSkillLibraryEntry(libraryId, normalizedVersion);
+    if (!entry) {
+      throw new HTTPException(422, {
+        message: `skill library entry is unavailable: ${libraryId}@${normalizedVersion}`,
+      });
+    }
+    // Skill activation has a deliberately narrow config surface. In
+    // particular, no variable-set, connection, credential-header, MCP, or
+    // provider-routing input is persisted or consulted for a library skill.
+    installationConfig = { version: entry.version };
+    installationMetadata = {
+      libraryId: entry.id,
+      libraryVersion: entry.version,
+      contentSha256: entry.contentSha256,
+      sourceCommit: entry.sourceCommit,
+      provenance: entry.provenance,
+    };
+  }
   if (item.kind === "mcp") {
     const headers = await resolveMcpCredentialHeaders(input, item);
     const connectionRef = input.payload.connectionRef
@@ -381,9 +433,13 @@ async function validateMcpCapabilityConnectionRef(
     providerDomain: ref.providerDomain.trim(),
     subjectScope: "workspace",
     ...(ref.connectionId ? { connectionId: ref.connectionId } : {}),
+    ...(ref.provider ? { provider: ref.provider.trim() } : {}),
     ...(ref.kind ? { kind: ref.kind } : {}),
     ...(ref.scopes ? { scopes: uniqueStrings(ref.scopes) } : {}),
     ...(ref.resource ? { resource: ref.resource } : {}),
+    ...(ref.selectedResources
+      ? { selectedResources: ref.selectedResources.map((resource) => ({ ...resource })) }
+      : {}),
   };
   if (!normalized.providerDomain) {
     throw new HTTPException(422, { message: "connectionRef.providerDomain is required" });
@@ -568,14 +624,23 @@ async function probeStreamableHttpMcpServer(
 function mcpProbeErrorMessage(error: unknown, endpointUrl: string): string {
   const message = error instanceof Error ? error.message : String(error);
   const normalized = message.replace(/\s+/g, " ").trim();
+  const endpoint = safeEndpointLabel(endpointUrl);
   if (
     /404|405|not found|unexpected token|not valid json|invalid json|failed to parse|streamable http error|unable to connect|fetch failed|econnrefused|enotfound|timeout|aborted/i.test(
       normalized,
     )
   ) {
-    return `OpenGeni could not reach a valid Streamable HTTP MCP server at ${endpointUrl}. 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.`;
+}
+
+function safeEndpointLabel(endpointUrl: string): string {
+  try {
+    return new URL(endpointUrl).hostname || "the configured endpoint";
+  } catch {
+    return "the configured endpoint";
   }
-  return `OpenGeni could not initialize ${endpointUrl}: ${normalized.slice(0, 500) || "unknown error"}`;
 }
 
 export async function disableCapability(input: {
@@ -927,6 +992,52 @@ async function discoverBundledSkills(): Promise<CapabilityCatalogItem[]> {
   }
 }
 
+/**
+ * Curated skills are catalogued independently from the always-mounted bundle.
+ * The runtime helper only returns entries whose reviewed artifact is present,
+ * so a deployment that omits optional library assets does not advertise a
+ * skill it cannot materialize.
+ */
+async function discoverCuratedSkillLibraryItems(): Promise<CapabilityCatalogItem[]> {
+  return listSkillLibraryEntries().map((entry) => curatedSkillCatalogItem(entry));
+}
+
+function curatedSkillCatalogItem(entry: SkillLibraryEntry): CapabilityCatalogItem {
+  return CapabilityCatalogItem.parse({
+    id: `skill:${entry.id}`,
+    kind: "skill",
+    source: "library",
+    name: entry.name,
+    description: entry.description,
+    category: entry.category,
+    tags: [...entry.tags],
+    homepageUrl: entry.sourceUrl,
+    provenance: entry.provenance,
+    tier: "verified",
+    runtime: {
+      available: true,
+      notes: "Available as an explicit immutable opt-in skill selection.",
+    },
+    metadata: {
+      libraryId: entry.id,
+      version: entry.version,
+      contentSha256: entry.contentSha256,
+      sourceCommit: entry.sourceCommit,
+      sourceUrl: entry.sourceUrl,
+      provenance: entry.provenance,
+      license: entry.license,
+      documentationUrl: entry.documentationUrl,
+      compatibility: entry.compatibility,
+      upgrade: entry.upgrade,
+      artifactPath: entry.relativePath,
+    },
+  });
+}
+
+function stringMetadata(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
 async function readSkillMetadata(
   url: URL,
   fallbackName: string,
@@ -977,6 +1088,16 @@ export function applyCapabilityEnablement(
       enabledReason: item.source === "configured" ? "configured" : "built in",
     };
   }
+  if (item.source === "library") {
+    const enabled =
+      installation?.status === "active" && skillLibraryInstallationRuntimeReady(item, installation);
+    return {
+      ...item,
+      enabled,
+      enabledReason: enabled ? "explicitly selected" : null,
+      connectionRef: null,
+    };
+  }
   const activeInstallation = installation?.status === "active";
   const enabled = !!activeInstallation && capabilityInstallationRuntimeReady(item, installation);
   return {
@@ -987,6 +1108,42 @@ export function applyCapabilityEnablement(
   };
 }
 
+function skillLibraryInstallationRuntimeReady(
+  item: CapabilityCatalogItem,
+  installation: CapabilityInstallation,
+): boolean {
+  if (item.kind !== "skill" || item.source !== "library" || installation.kind !== "skill") {
+    return false;
+  }
+  const libraryId = stringMetadata(item.metadata.libraryId);
+  const version = stringMetadata(item.metadata.version);
+  const contentSha256 = stringMetadata(item.metadata.contentSha256);
+  const sourceCommit = stringMetadata(item.metadata.sourceCommit);
+  const provenance = stringMetadata(item.metadata.provenance);
+  if (!libraryId || !version || !contentSha256 || !sourceCommit || !provenance) {
+    return false;
+  }
+  const entry = getSkillLibraryEntry(libraryId, version);
+  if (
+    !entry ||
+    item.id !== `skill:${entry.id}` ||
+    installation.capabilityId !== `skill:${entry.id}` ||
+    contentSha256 !== entry.contentSha256 ||
+    sourceCommit !== entry.sourceCommit ||
+    provenance !== entry.provenance
+  ) {
+    return false;
+  }
+  return (
+    installation.config.version === entry.version &&
+    stringMetadata(installation.metadata.libraryId) === entry.id &&
+    stringMetadata(installation.metadata.libraryVersion) === entry.version &&
+    stringMetadata(installation.metadata.contentSha256) === entry.contentSha256 &&
+    stringMetadata(installation.metadata.sourceCommit) === entry.sourceCommit &&
+    stringMetadata(installation.metadata.provenance) === entry.provenance
+  );
+}
+
 /**
  * The connection an installation was enabled with, when the enable-time
  * connectionRef fully resolved to one (config.connectionRef is set only by
@@ -1014,6 +1171,17 @@ function installationConnectionRef(
 function dedupeCatalogItems(items: CapabilityCatalogItem[]): CapabilityCatalogItem[] {
   const byId = new Map<string, CapabilityCatalogItem>();
   for (const item of items) {
+    // Curated library entries are runtime-managed and must not be replaced by
+    // stale/manual rows with the same reserved skill id. Other catalog sources
+    // retain the historical last-write-wins behavior below.
+    if (item.kind === "skill" && item.source === "library" && byId.has(item.id)) {
+      byId.set(item.id, item);
+      continue;
+    }
+    const existing = byId.get(item.id);
+    if (existing?.kind === "skill" && existing.source === "library") {
+      continue;
+    }
     byId.set(item.id, item);
   }
   return [...byId.values()];

package/src/domain/resources.ts

@@ -1,14 +1,21 @@
 import type { Settings } from "@opengeni/config";
 import {
+  gitCredentialBindingIdForRepository,
+  gitCredentialProviderForRepository,
+  defaultRepositoryMountPath,
   mergeResourceRefs as mergeContractResourceRefs,
   mergeToolRefs,
+  normalizeRepositorySubpath,
+  normalizeResourceMountPath,
   resourceIdentityKey,
+  resourceMountPathCollisionKey,
   ResourceRefConflictError,
+  ResourceMountPathError,
   stableJson,
   type ResourceRef,
   type ToolRef,
 } from "@opengeni/contracts";
-import { listGitHubInstallationIdsForWorkspace, requireFile, type Database } from "@opengeni/db";
+import { areGitHubRepositoriesAllowedForWorkspace, requireFile, type Database } from "@opengeni/db";
 import { HTTPException } from "hono/http-exception";
 
 export function validateToolRefs(tools: ToolRef[], settings: Settings): ToolRef[] {
@@ -71,6 +78,7 @@ export function withDefaultEnabledCapabilityMcpTools(
 export function normalizeResources(resources: ResourceRef[]): ResourceRef[] {
   const mountPaths = new Map<string, string>();
   const identities = new Map<string, string>();
+  const credentialBindingProviders = new Map<string, string>();
   const seenResources = new Set<string>();
   const out: ResourceRef[] = [];
   for (const resource of resources) {
@@ -93,14 +101,40 @@ export function normalizeResources(resources: ResourceRef[]): ResourceRef[] {
         throw new HTTPException(422, { message: "repository URL must include owner and repo" });
       }
       const repo = parts.join("/");
-      const mountPath = normalizeMountPath(resource.mountPath ?? `repos/${repo}`);
+      const normalizedUri = `https://${url.host.toLowerCase()}/${repo}.git`;
+      const mountPath = normalizeMountPath(
+        resource.mountPath ?? defaultRepositoryMountPath(normalizedUri),
+      );
+      const credentialProvider = gitCredentialProviderForRepository(resource);
+      const credentialBindingId = gitCredentialBindingIdForRepository(resource, credentialProvider);
+      if (
+        (resource.credentialBindingId || resource.connectionId || resource.access) &&
+        !credentialProvider
+      ) {
+        throw new HTTPException(422, {
+          message: "repository credential bindings and access intent require a Git provider",
+        });
+      }
+      if (credentialProvider && credentialBindingId) {
+        const boundProvider = credentialBindingProviders.get(credentialBindingId);
+        if (boundProvider && boundProvider !== credentialProvider) {
+          throw new HTTPException(422, {
+            message: `credential binding ${credentialBindingId} is assigned to multiple Git providers`,
+          });
+        }
+        credentialBindingProviders.set(credentialBindingId, credentialProvider);
+      }
       normalized = {
         kind: "repository",
-        uri: `https://${url.hostname.toLowerCase()}/${repo}.git`,
+        uri: normalizedUri,
         ref: resource.ref.trim(),
         mountPath,
-        ...(resource.subpath ? { subpath: normalizeMountPath(resource.subpath) } : {}),
+        ...(resource.subpath ? { subpath: normalizeRepositorySubpath(resource.subpath) } : {}),
         ...(resource.provider ? { provider: resource.provider } : {}),
+        ...(resource.credentialBindingId
+          ? { credentialBindingId: resource.credentialBindingId }
+          : {}),
+        ...(resource.access ? { access: resource.access } : {}),
         ...(resource.repositoryId !== undefined ? { repositoryId: resource.repositoryId } : {}),
         ...(resource.installationId !== undefined
           ? { installationId: resource.installationId }
@@ -114,14 +148,17 @@ export function normalizeResources(resources: ResourceRef[]): ResourceRef[] {
       };
     }
     const key = stableJson(normalized);
-    const mounted = normalized.mountPath ? mountPaths.get(normalized.mountPath) : undefined;
+    const mountCollisionKey = normalized.mountPath
+      ? resourceMountPathCollisionKey(normalized.mountPath)
+      : undefined;
+    const mounted = mountCollisionKey ? mountPaths.get(mountCollisionKey) : undefined;
     if (mounted && mounted !== key) {
       throw new HTTPException(422, {
         message: `duplicate resource mount path: ${normalized.mountPath}`,
       });
     }
     if (normalized.mountPath) {
-      mountPaths.set(normalized.mountPath, key);
+      mountPaths.set(mountCollisionKey!, key);
     }
     const identity = resourceIdentityKey(normalized);
     const seenIdentity = identities.get(identity);
@@ -153,8 +190,29 @@ export function mergeResourceRefs(
   }
 }
 
+export function validateGitHubRepositorySelectionShapes(resources: ResourceRef[]): number[] {
+  const selected = gitHubRepositorySelections(resources);
+  if (selected.length === 0) {
+    return [];
+  }
+  return [...new Set(selected.map((item) => item.installationId))];
+}
+
+/** @deprecated Use validateGitHubRepositorySelectionShapes for multi-installation sessions. */
 export function validateGitHubRepositorySelectionShape(resources: ResourceRef[]): number | null {
-  const selected = resources.flatMap((resource) => {
+  const installationIds = validateGitHubRepositorySelectionShapes(resources);
+  if (installationIds.length > 1) {
+    throw new HTTPException(422, {
+      message: "GitHub App repository resources must belong to one installation",
+    });
+  }
+  return installationIds[0] ?? null;
+}
+
+function gitHubRepositorySelections(
+  resources: ResourceRef[],
+): Array<{ installationId: number; repositoryId: number }> {
+  return resources.flatMap((resource) => {
     if (resource.kind !== "repository") {
       return [];
     }
@@ -180,16 +238,6 @@ export function validateGitHubRepositorySelectionShape(resources: ResourceRef[])
     }
     return [{ installationId, repositoryId }];
   });
-  if (selected.length === 0) {
-    return null;
-  }
-  const installationId = selected[0]!.installationId;
-  if (selected.some((item) => item.installationId !== installationId)) {
-    throw new HTTPException(422, {
-      message: "GitHub App repository resources must belong to one installation",
-    });
-  }
-  return installationId;
 }
 
 export async function validateGitHubRepositorySelection(
@@ -197,18 +245,28 @@ export async function validateGitHubRepositorySelection(
   workspaceId: string,
   resources: ResourceRef[],
 ): Promise<void> {
-  const installationId = validateGitHubRepositorySelectionShape(resources);
-  if (installationId === null) {
+  const installationIds = validateGitHubRepositorySelectionShapes(resources);
+  if (installationIds.length === 0) {
     return;
   }
-  const linkedInstallationIds = new Set(
-    await listGitHubInstallationIdsForWorkspace(db, workspaceId),
-  );
-  if (!linkedInstallationIds.has(installationId)) {
-    throw new HTTPException(422, {
-      message:
-        "GitHub App repository resources must belong to a GitHub App installation linked to this workspace",
-    });
+  const selections = gitHubRepositorySelections(resources);
+  for (const installationId of installationIds) {
+    const repositoryIds = selections
+      .filter((selection) => selection.installationId === installationId)
+      .map((selection) => selection.repositoryId);
+    if (
+      !(await areGitHubRepositoriesAllowedForWorkspace(
+        db,
+        workspaceId,
+        installationId,
+        repositoryIds,
+      ))
+    ) {
+      throw new HTTPException(422, {
+        message:
+          "GitHub App repository resources must be authorized for a GitHub App installation linked to this workspace",
+      });
+    }
   }
 }
 
@@ -239,11 +297,12 @@ export async function validateFileResources(
 }
 
 function normalizeMountPath(path: string): string {
-  const normalized = path.trim().replace(/^\/+|\/+$/g, "");
-  if (!normalized || normalized.includes("..")) {
+  try {
+    return normalizeResourceMountPath(path);
+  } catch (error) {
+    if (!(error instanceof ResourceMountPathError)) throw error;
     throw new HTTPException(422, { message: `invalid resource mount path: ${path}` });
   }
-  return normalized;
 }
 
 function parseResourceUrl(uri: string): URL {