@opengeni/capabilities 0.2.0 → 0.3.1-canary.0

package/dist/integration-definitions.d.ts

@@ -43,7 +43,6 @@ export interface IntegrationFacetDefinition {
     readonly capabilities: Readonly<Record<string, unknown>>;
 }
 export declare const GOOGLE_DRIVE_INTEGRATION_DEFINITION: IntegrationDefinition;
-export declare const GOOGLE_GMAIL_INTEGRATION_DEFINITION: IntegrationDefinition;
 export declare const MICROSOFT_GRAPH_OPENAPI_URL = "https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/openapi/v1.0/openapi.yaml";
 export declare const MICROSOFT_GRAPH_BASE_URL = "https://graph.microsoft.com/v1.0";
 export declare const MICROSOFT_OUTLOOK_MAIL_INTEGRATION_DEFINITION: IntegrationDefinition;

package/dist/integration-presentations.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Reviewed consent copy for the core API integration definitions.
+ *
+ * Presentation only: nothing here grants a scope, selects a connection, or
+ * replaces server-side authorization. The copy used to live hardcoded in the
+ * web bundle (`REVIEWED_INTEGRATION_EXPERIENCES`); it is served with the
+ * definition now so polishing a consent screen is a data change, not a
+ * frontend release. The web keeps its generic fallback for any definition or
+ * field missing here. Gmail's reviewed presentation lives on its catalog row
+ * instead (`data/catalog/curated.json`): Gmail is a Connector, not one of
+ * these API integration definitions.
+ *
+ * MCP connectors carry the same shape on their curated catalog row
+ * (`presentation` in `data/catalog/curated.json` -> importer ->
+ * `capability_catalog_items.metadata.presentation`).
+ */
+export type IntegrationPresentationIcon = "calendar" | "cloud" | "contacts" | "files" | "mail";
+export type IntegrationPresentationCopy = {
+    readonly providerName?: string;
+    readonly icon?: IntegrationPresentationIcon;
+    readonly introduction?: string;
+    readonly capabilities?: readonly {
+        readonly title: string;
+        readonly description: string;
+    }[];
+    readonly permissionSummary?: string;
+    readonly scopeLabels?: Readonly<Record<string, {
+        readonly label: string;
+        readonly description: string;
+    }>>;
+};
+export declare const INTEGRATION_DEFINITION_PRESENTATIONS: Readonly<Record<string, IntegrationPresentationCopy>>;

package/dist/mcp-bridge.d.ts

@@ -0,0 +1,41 @@
+import type { MCPServer } from "@openai/agents";
+export declare const LOCAL_MCP_BRIDGE_CONTRACT_VERSION: 1;
+export type LocalMcpBridgeAuthority = "connection" | "host" | "none";
+export type LocalMcpBridgeToolSurface = "static_reviewed";
+export type LocalMcpBridgeDestination = Readonly<{
+    origin: string;
+    pathPrefix: string;
+}>;
+/**
+ * Secret-free description of an in-process provider-to-MCP adapter.
+ *
+ * This is observability and registration metadata, not authorization. The
+ * adapter must still revalidate its named authority before each physical
+ * provider request and keep credentials outside tool results and schemas.
+ */
+export type LocalMcpBridgeDescriptor = Readonly<{
+    contractVersion: typeof LOCAL_MCP_BRIDGE_CONTRACT_VERSION;
+    adapterId: string;
+    providerId: string;
+    catalogIdentity: string;
+    transport: "in_process";
+    authority: LocalMcpBridgeAuthority;
+    toolSurface: LocalMcpBridgeToolSurface;
+    mutationReplay: "safe_reads_only";
+    destinations: readonly LocalMcpBridgeDestination[];
+}>;
+export interface LocalMcpBridgeServer extends MCPServer {
+    readonly bridge: LocalMcpBridgeDescriptor;
+}
+export interface LocalMcpBridgeAdapter<TConfig, TContext> {
+    readonly adapterId: string;
+    matches(config: TConfig): boolean;
+    create(config: TConfig, context: TContext): LocalMcpBridgeServer;
+}
+export declare function defineLocalMcpBridgeDescriptor(input: Omit<LocalMcpBridgeDescriptor, "contractVersion" | "transport">): LocalMcpBridgeDescriptor;
+export declare function isLocalMcpBridgeServer(server: MCPServer): server is LocalMcpBridgeServer;
+/**
+ * Select exactly one adapter for a runtime catalog row. Ambiguous matches fail
+ * closed so adding a bridge cannot silently replace another provider route.
+ */
+export declare function createLocalMcpBridgeFromAdapters<TConfig, TContext>(adapters: readonly LocalMcpBridgeAdapter<TConfig, TContext>[], config: TConfig, context: TContext): LocalMcpBridgeServer | null;

package/dist/types.d.ts

@@ -30,6 +30,8 @@ export interface IntegrationCredentialAudience {
 export interface ResolvedIntegrationCredential {
     readonly audience: IntegrationCredentialAudience;
     readonly placements: readonly IntegrationCredentialPlacement[];
+    /** Exact accepted-attempt fence invoked immediately before one HTTP request. */
+    readonly authorizeProviderRequest?: () => Promise<boolean>;
     readonly expiresAt?: string;
     readonly scope?: readonly string[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/capabilities",
-  "version": "0.2.0",
+  "version": "0.3.1-canary.0",
   "description": "Protocol-neutral capability integration compilers and local MCP adapters for OpenGeni.",
   "license": "Apache-2.0",
   "repository": {
@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@openai/agents": "0.14.3",
-    "@opengeni/network": "^0.2.2",
+    "@opengeni/network": "^0.2.3-canary.0",
     "graphql": "^16.12.0",
     "js-yaml": "4.1.1"
   },

package/src/graphql.ts

@@ -428,6 +428,22 @@ async function sendGraphqlRequest(
   headers.set("accept", "application/json");
   headers.set("content-type", "application/json");
   if (credential) applyCredentialPlacements(endpoint, headers, credential);
+  if (credential?.authorizeProviderRequest) {
+    let authorized = false;
+    try {
+      authorized = await credential.authorizeProviderRequest();
+    } catch {
+      authorized = false;
+    }
+    if (!authorized) {
+      throw new IntegrationInvocationError(
+        "authorization_rejected",
+        "The connected account is no longer authorized for this operation",
+        "not_started",
+        false,
+      );
+    }
+  }
   return await fetchWithDeadline(
     options.transport,
     endpoint,

package/src/index.ts

@@ -2,7 +2,9 @@ export * from "./auth";
 export * from "./graphql";
 export * from "./http";
 export * from "./mcp-manifest";
+export * from "./mcp-bridge";
 export * from "./openapi";
 export * from "./integration-definitions";
+export * from "./integration-presentations";
 export * from "./revision";
 export * from "./types";

package/src/integration-definitions.ts

@@ -123,7 +123,7 @@ const driveKnowledgeFacet = (
 });
 
 const mailboxFacets = (
-  provider: "google-gmail" | "microsoft-outlook-mail",
+  provider: "microsoft-outlook-mail",
 ): readonly IntegrationFacetDefinition[] => [
   {
     facetKey: "mail-inbox",
@@ -140,7 +140,7 @@ const mailboxFacets = (
       provider,
       connectionRequired: true,
       delivery: "poll",
-      cursor: provider === "google-gmail" ? "history_id" : "delta_link",
+      cursor: "delta_link",
     },
   },
   {
@@ -160,7 +160,7 @@ const mailboxFacets = (
       delivery: "email",
     },
   },
-  accountIdentityFacet(provider === "google-gmail" ? "google" : "microsoft"),
+  accountIdentityFacet("microsoft"),
 ];
 
 const googleDiscoveryUrl = (service: string, version: string): string =>
@@ -191,22 +191,6 @@ export const GOOGLE_DRIVE_INTEGRATION_DEFINITION: IntegrationDefinition = {
   facets: [driveKnowledgeFacet("google-drive"), accountIdentityFacet("google")],
 };
 
-export const GOOGLE_GMAIL_INTEGRATION_DEFINITION: IntegrationDefinition = {
-  id: "google-gmail",
-  name: "Gmail",
-  summary: "Messages, threads, labels, drafts, and sending mail.",
-  protocol: "openapi",
-  provider: { id: "google", domain: "gmail.googleapis.com" },
-  source: { kind: "google_discovery", url: googleDiscoveryUrl("gmail", "v1") },
-  baseUrl: "https://gmail.googleapis.com/",
-  authentication: googleOAuth(["https://mail.google.com/"]),
-  healthCheck: {
-    operationKey: "gmail.users.labels.list",
-    arguments: { path: { userId: "me" } },
-  },
-  facets: mailboxFacets("google-gmail"),
-};
-
 export const MICROSOFT_GRAPH_OPENAPI_URL =
   "https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/openapi/v1.0/openapi.yaml";
 export const MICROSOFT_GRAPH_BASE_URL = "https://graph.microsoft.com/v1.0";
@@ -338,7 +322,6 @@ export const MICROSOFT_ONEDRIVE_INTEGRATION_DEFINITION: IntegrationDefinition =
 
 export const CORE_INTEGRATION_DEFINITIONS: readonly IntegrationDefinition[] = [
   GOOGLE_DRIVE_INTEGRATION_DEFINITION,
-  GOOGLE_GMAIL_INTEGRATION_DEFINITION,
   MICROSOFT_OUTLOOK_MAIL_INTEGRATION_DEFINITION,
   MICROSOFT_OUTLOOK_CALENDAR_INTEGRATION_DEFINITION,
   MICROSOFT_OUTLOOK_CONTACTS_INTEGRATION_DEFINITION,
@@ -480,23 +463,23 @@ function collectGoogleMethods(
     const path = stringValue(rawMethod.path);
     const httpMethod = stringValue(rawMethod.httpMethod)?.toLowerCase();
     if (!path || !httpMethod) continue;
-    const parameters = Object.entries(
-      isRecord(rawMethod.parameters) ? rawMethod.parameters : {},
-    ).flatMap(([name, rawParameter]): Record<string, unknown>[] => {
-      if (!isRecord(rawParameter)) return [];
-      const location = rawParameter.location === "path" ? "path" : "query";
-      return [
-        {
-          name,
-          in: location,
-          required: location === "path" || rawParameter.required === true,
-          ...(stringValue(rawParameter.description)
-            ? { description: stringValue(rawParameter.description) }
-            : {}),
-          schema: convertGoogleSchema(rawParameter),
-        },
-      ];
-    });
+    const parameters = Object.entries(isRecord(rawMethod.parameters) ? rawMethod.parameters : {})
+      .sort(([left], [right]) => left.localeCompare(right))
+      .flatMap(([name, rawParameter]): Record<string, unknown>[] => {
+        if (!isRecord(rawParameter)) return [];
+        const location = rawParameter.location === "path" ? "path" : "query";
+        return [
+          {
+            name,
+            in: location,
+            required: location === "path" || rawParameter.required === true,
+            ...(stringValue(rawParameter.description)
+              ? { description: stringValue(rawParameter.description) }
+              : {}),
+            schema: convertGoogleSchema(rawParameter),
+          },
+        ];
+      });
     const requestRef = isRecord(rawMethod.request)
       ? stringValue(rawMethod.request.$ref)
       : undefined;
@@ -505,7 +488,10 @@ function collectGoogleMethods(
       : undefined;
     const operation: Record<string, unknown> = {
       operationId: stringValue(rawMethod.id) ?? fallbackId,
-      summary: stringValue(rawMethod.description) ?? stringValue(rawMethod.id) ?? fallbackId,
+      // Discovery descriptions are often full documentation paragraphs. Keep
+      // them as descriptions and use the stable method identity for the short
+      // OpenGeni tool display name.
+      summary: stringValue(rawMethod.id) ?? fallbackId,
       description: stringValue(rawMethod.description),
       parameters,
       responses: {

package/src/integration-presentations.ts

@@ -0,0 +1,185 @@
+/**
+ * Reviewed consent copy for the core API integration definitions.
+ *
+ * Presentation only: nothing here grants a scope, selects a connection, or
+ * replaces server-side authorization. The copy used to live hardcoded in the
+ * web bundle (`REVIEWED_INTEGRATION_EXPERIENCES`); it is served with the
+ * definition now so polishing a consent screen is a data change, not a
+ * frontend release. The web keeps its generic fallback for any definition or
+ * field missing here. Gmail's reviewed presentation lives on its catalog row
+ * instead (`data/catalog/curated.json`): Gmail is a Connector, not one of
+ * these API integration definitions.
+ *
+ * MCP connectors carry the same shape on their curated catalog row
+ * (`presentation` in `data/catalog/curated.json` -> importer ->
+ * `capability_catalog_items.metadata.presentation`).
+ */
+
+export type IntegrationPresentationIcon = "calendar" | "cloud" | "contacts" | "files" | "mail";
+
+export type IntegrationPresentationCopy = {
+  readonly providerName?: string;
+  readonly icon?: IntegrationPresentationIcon;
+  readonly introduction?: string;
+  readonly capabilities?: readonly { readonly title: string; readonly description: string }[];
+  readonly permissionSummary?: string;
+  readonly scopeLabels?: Readonly<
+    Record<string, { readonly label: string; readonly description: string }>
+  >;
+};
+
+export const INTEGRATION_DEFINITION_PRESENTATIONS: Readonly<
+  Record<string, IntegrationPresentationCopy>
+> = {
+  "google-drive": {
+    providerName: "Google",
+    icon: "files",
+    introduction: "Let agents work with files in the Google Drive account you choose.",
+    capabilities: [
+      {
+        title: "Find files and folders",
+        description: "Browse and search content in My Drive and shared drives.",
+      },
+      {
+        title: "Create and update content",
+        description: "Work with files and folders through the reviewed Drive tools.",
+      },
+      {
+        title: "Manage sharing",
+        description: "Review and update links, permissions, and shared-drive content.",
+      },
+    ],
+    permissionSummary:
+      "Google asks for access to the Drive account you approve, including files shared with that account.",
+    scopeLabels: {
+      "https://www.googleapis.com/auth/drive": {
+        label: "Work with Google Drive files",
+        description: "See, create, edit, organize, and share files available to this account.",
+      },
+    },
+  },
+  "microsoft-outlook-mail": {
+    providerName: "Microsoft",
+    icon: "mail",
+    introduction: "Let agents work with mail in the Microsoft account you choose.",
+    capabilities: [
+      {
+        title: "Find and understand mail",
+        description: "Search messages, folders, and attachments for useful context.",
+      },
+      {
+        title: "Draft and send messages",
+        description: "Prepare, update, and send mail through the reviewed Outlook tools.",
+      },
+      {
+        title: "Manage mailbox settings",
+        description: "Work with supported folders, classifications, and mailbox preferences.",
+      },
+    ],
+    permissionSummary:
+      "Microsoft asks for mail and mailbox-setting access for the account you approve.",
+    scopeLabels: {
+      "Mail.ReadWrite": {
+        label: "Read and update mail",
+        description: "Work with messages, folders, and attachments in this mailbox.",
+      },
+      "Mail.Send": {
+        label: "Send mail",
+        description: "Send messages as the connected Microsoft account.",
+      },
+      "MailboxSettings.ReadWrite": {
+        label: "Manage mailbox settings",
+        description: "Read and update supported Outlook mailbox preferences.",
+      },
+    },
+  },
+  "microsoft-outlook-calendar": {
+    providerName: "Microsoft",
+    icon: "calendar",
+    introduction: "Let agents help coordinate the calendars in your Microsoft account.",
+    capabilities: [
+      {
+        title: "Understand your schedule",
+        description: "Review calendars, events, availability, and reminders.",
+      },
+      {
+        title: "Plan meetings",
+        description: "Find suitable times and coordinate calendar activity.",
+      },
+      {
+        title: "Manage events",
+        description: "Create and update events through the reviewed calendar tools.",
+      },
+    ],
+    permissionSummary:
+      "Microsoft asks for permission to view and manage calendars for the account you approve.",
+    scopeLabels: {
+      "Calendars.ReadWrite": {
+        label: "View and manage calendars",
+        description: "Read, create, update, and organize calendar events.",
+      },
+    },
+  },
+  "microsoft-outlook-contacts": {
+    providerName: "Microsoft",
+    icon: "contacts",
+    introduction: "Let agents work with contacts in your Microsoft account.",
+    capabilities: [
+      {
+        title: "Find people",
+        description: "Look up contacts and relevant people suggestions.",
+      },
+      {
+        title: "Organize contacts",
+        description: "Work with contacts and contact folders.",
+      },
+      {
+        title: "Keep details current",
+        description: "Create or update contact information through reviewed tools.",
+      },
+    ],
+    permissionSummary:
+      "Microsoft asks for contact access and people suggestions for the account you approve.",
+    scopeLabels: {
+      "Contacts.ReadWrite": {
+        label: "View and manage contacts",
+        description: "Read, create, update, and organize contacts and contact folders.",
+      },
+      "People.Read.All": {
+        label: "Find relevant people",
+        description: "Use people suggestions available to the connected account.",
+      },
+    },
+  },
+  "microsoft-onedrive": {
+    providerName: "Microsoft",
+    icon: "cloud",
+    introduction: "Let agents work with files in the Microsoft account you choose.",
+    capabilities: [
+      {
+        title: "Find files and folders",
+        description: "Browse drives, folders, shared items, and sites available to the account.",
+      },
+      {
+        title: "Create and update content",
+        description: "Work with OneDrive and SharePoint files through reviewed tools.",
+      },
+      {
+        title: "Manage sharing",
+        description: "Review and update sharing links and permissions.",
+      },
+    ],
+    permissionSummary:
+      "Microsoft asks for file and site access anywhere the connected account already has access.",
+    scopeLabels: {
+      "Files.ReadWrite.All": {
+        label: "Work with accessible files",
+        description: "Read, create, update, and organize files available to this account.",
+      },
+      "Sites.ReadWrite.All": {
+        label: "Work with accessible sites",
+        description: "Read and update files in SharePoint sites available to this account.",
+      },
+    },
+  },
+};

package/src/mcp-bridge.ts

@@ -0,0 +1,117 @@
+import type { MCPServer } from "@openai/agents";
+
+export const LOCAL_MCP_BRIDGE_CONTRACT_VERSION = 1 as const;
+
+export type LocalMcpBridgeAuthority = "connection" | "host" | "none";
+export type LocalMcpBridgeToolSurface = "static_reviewed";
+
+export type LocalMcpBridgeDestination = Readonly<{
+  origin: string;
+  pathPrefix: string;
+}>;
+
+/**
+ * Secret-free description of an in-process provider-to-MCP adapter.
+ *
+ * This is observability and registration metadata, not authorization. The
+ * adapter must still revalidate its named authority before each physical
+ * provider request and keep credentials outside tool results and schemas.
+ */
+export type LocalMcpBridgeDescriptor = Readonly<{
+  contractVersion: typeof LOCAL_MCP_BRIDGE_CONTRACT_VERSION;
+  adapterId: string;
+  providerId: string;
+  catalogIdentity: string;
+  transport: "in_process";
+  authority: LocalMcpBridgeAuthority;
+  toolSurface: LocalMcpBridgeToolSurface;
+  mutationReplay: "safe_reads_only";
+  destinations: readonly LocalMcpBridgeDestination[];
+}>;
+
+export interface LocalMcpBridgeServer extends MCPServer {
+  readonly bridge: LocalMcpBridgeDescriptor;
+}
+
+export interface LocalMcpBridgeAdapter<TConfig, TContext> {
+  readonly adapterId: string;
+  matches(config: TConfig): boolean;
+  create(config: TConfig, context: TContext): LocalMcpBridgeServer;
+}
+
+export function defineLocalMcpBridgeDescriptor(
+  input: Omit<LocalMcpBridgeDescriptor, "contractVersion" | "transport">,
+): LocalMcpBridgeDescriptor {
+  const adapterId = boundedIdentity(input.adapterId, "adapterId");
+  const providerId = boundedIdentity(input.providerId, "providerId");
+  const catalogIdentity = boundedIdentity(input.catalogIdentity, "catalogIdentity", 512);
+  if (input.destinations.length === 0 || input.destinations.length > 32) {
+    throw new Error("Local MCP bridge must declare 1-32 provider destinations");
+  }
+  const destinations = input.destinations.map((destination) => {
+    const url = new URL(destination.origin);
+    if (url.protocol !== "https:" || url.origin !== destination.origin) {
+      throw new Error("Local MCP bridge destinations must be exact HTTPS origins");
+    }
+    if (
+      !destination.pathPrefix.startsWith("/") ||
+      destination.pathPrefix.includes("\\") ||
+      destination.pathPrefix.includes("?") ||
+      destination.pathPrefix.includes("#") ||
+      new URL(destination.pathPrefix, url.origin).pathname !== destination.pathPrefix
+    ) {
+      throw new Error("Local MCP bridge destination pathPrefix must be an absolute URL path");
+    }
+    return Object.freeze({ origin: url.origin, pathPrefix: destination.pathPrefix });
+  });
+  return Object.freeze({
+    contractVersion: LOCAL_MCP_BRIDGE_CONTRACT_VERSION,
+    adapterId,
+    providerId,
+    catalogIdentity,
+    transport: "in_process",
+    authority: input.authority,
+    toolSurface: input.toolSurface,
+    mutationReplay: input.mutationReplay,
+    destinations: Object.freeze(destinations),
+  });
+}
+
+export function isLocalMcpBridgeServer(server: MCPServer): server is LocalMcpBridgeServer {
+  const bridge = (server as Partial<LocalMcpBridgeServer>).bridge;
+  return (
+    bridge?.contractVersion === LOCAL_MCP_BRIDGE_CONTRACT_VERSION &&
+    bridge.transport === "in_process"
+  );
+}
+
+/**
+ * Select exactly one adapter for a runtime catalog row. Ambiguous matches fail
+ * closed so adding a bridge cannot silently replace another provider route.
+ */
+export function createLocalMcpBridgeFromAdapters<TConfig, TContext>(
+  adapters: readonly LocalMcpBridgeAdapter<TConfig, TContext>[],
+  config: TConfig,
+  context: TContext,
+): LocalMcpBridgeServer | null {
+  const matches = adapters.filter((adapter) => adapter.matches(config));
+  if (matches.length === 0) return null;
+  if (matches.length > 1) {
+    throw new Error(
+      `Multiple local MCP bridge adapters matched: ${matches.map((entry) => entry.adapterId).join(", ")}`,
+    );
+  }
+  const adapter = matches[0]!;
+  const server = adapter.create(config, context);
+  if (server.bridge.adapterId !== adapter.adapterId) {
+    throw new Error(`Local MCP bridge adapter ${adapter.adapterId} returned mismatched metadata`);
+  }
+  return server;
+}
+
+function boundedIdentity(value: string, name: string, max = 128): string {
+  if (value.length === 0 || value.length > max || /[\u0000-\u001f\u007f]/u.test(value)) {
+    throw new Error(`Local MCP bridge ${name} is invalid`);
+  }
+  return value;
+}

package/src/openapi.ts

@@ -426,6 +426,22 @@ async function sendOpenApiRequest(
   const headers = buildOperationHeaders(binding, args);
   const body = buildOperationBody(binding, args, headers);
   if (credential) applyCredentialPlacements(url, headers, credential);
+  if (credential?.authorizeProviderRequest) {
+    let authorized = false;
+    try {
+      authorized = await credential.authorizeProviderRequest();
+    } catch {
+      authorized = false;
+    }
+    if (!authorized) {
+      throw new IntegrationInvocationError(
+        "authorization_rejected",
+        "The connected account is no longer authorized for this operation",
+        "not_started",
+        false,
+      );
+    }
+  }
   return await fetchWithDeadline(
     options.transport,
     url,

package/src/types.ts

@@ -37,6 +37,8 @@ export interface IntegrationCredentialAudience {
 export interface ResolvedIntegrationCredential {
   readonly audience: IntegrationCredentialAudience;
   readonly placements: readonly IntegrationCredentialPlacement[];
+  /** Exact accepted-attempt fence invoked immediately before one HTTP request. */
+  readonly authorizeProviderRequest?: () => Promise<boolean>;
   readonly expiresAt?: string;
   readonly scope?: readonly string[];
 }