@opengeni/core 4.3.3-canary.39786771332001 → 4.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/core",
-  "version": "4.3.3-canary.39786771332001",
+  "version": "4.5.0",
   "description": "Opengeni framework-agnostic core: the domain, access, and billing layers (neutral access, off-HTTP V2 surface). Behavior-preserving extraction from apps/api — keeps Hono's HTTPException for error throwing (typed-errors cleanup deferred).",
   "license": "Apache-2.0",
   "repository": {
@@ -51,18 +51,18 @@
   "dependencies": {
     "@modelcontextprotocol/client": "2.3.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opengeni/capabilities": "4.3.3-canary.39786771332001",
-    "@opengeni/codex": "4.3.3-canary.39786771332001",
-    "@opengeni/config": "4.3.3-canary.39786771332001",
-    "@opengeni/contracts": "4.3.3-canary.39786771332001",
-    "@opengeni/db": "4.3.3-canary.39786771332001",
-    "@opengeni/documents": "4.3.3-canary.39786771332001",
-    "@opengeni/events": "4.3.3-canary.39786771332001",
-    "@opengeni/network": "4.3.3-canary.39786771332001",
-    "@opengeni/observability": "4.3.3-canary.39786771332001",
-    "@opengeni/runtime": "4.3.3-canary.39786771332001",
-    "@opengeni/storage": "4.3.3-canary.39786771332001",
-    "@opengeni/vaults": "4.3.3-canary.39786771332001",
+    "@opengeni/capabilities": "4.5.0",
+    "@opengeni/codex": "4.5.0",
+    "@opengeni/config": "4.5.0",
+    "@opengeni/contracts": "4.5.0",
+    "@opengeni/db": "4.5.0",
+    "@opengeni/documents": "4.5.0",
+    "@opengeni/events": "4.5.0",
+    "@opengeni/network": "4.5.0",
+    "@opengeni/observability": "4.5.0",
+    "@opengeni/runtime": "4.5.0",
+    "@opengeni/storage": "4.5.0",
+    "@opengeni/vaults": "4.5.0",
     "hono": "^4.12.18",
     "zod": "^4.2.1"
   },

package/src/domain/capabilities.ts

@@ -25,6 +25,8 @@ import {
   type McpPersonalConnectionDelegation,
   assertOrganizationIntegrationAllowed,
   type SocialConnection,
+  ToolAuthNeededPayload,
+  type UserSetupBlocker,
 } from "@opengeni/contracts";
 import {
   CODEX_APPS_MCP_SERVER_ID,
@@ -1666,6 +1668,20 @@ function onePasswordCatalogItem(connections: ConnectionMetadata[]): CapabilityCa
   });
 }
 
+/** How people and agents name the deployment's Chrome extension, and where it is installed. */
+export type BrowserExtension = { name: string; installUrl: string };
+
+/** The deployment's configured Chrome extension, else Opengeni Browser. */
+export function browserExtension(settings: {
+  browserExtensionName?: string | undefined;
+  browserExtensionInstallUrl?: string | undefined;
+}): BrowserExtension {
+  return {
+    name: settings.browserExtensionName ?? "Opengeni Browser",
+    installUrl: settings.browserExtensionInstallUrl ?? OPENGENI_BROWSER_EXTENSION_URL,
+  };
+}
+
 /** The catalog id of the Excel add-in tile and its in-chat install card. */
 export const EXCEL_ADDIN_CAPABILITY_ID = "api:excel-addin";
 
@@ -1791,8 +1807,9 @@ export const CONNECTED_MACHINE_CAPABILITY_ID = "api:connected-machine";
 export { OPENGENI_BROWSER_EXTENSION_URL };
 
 export function nativeConnectionCapabilityRecommendations(
-  options: { connectedMachines?: boolean } = {},
+  options: { connectedMachines?: boolean; browserExtension?: BrowserExtension } = {},
 ): CapabilityCatalogItem[] {
+  const extensionUrl = options.browserExtension?.installUrl ?? OPENGENI_BROWSER_EXTENSION_URL;
   const items = [
     CapabilityCatalogItem.parse({
       id: "api:github-app",
@@ -1863,7 +1880,7 @@ export function nativeConnectionCapabilityRecommendations(
         tools: [{ kind: "mcp", id: "opengeni" }],
         runtime: {
           available: true,
-          notes: `The person sets up their machine from the chat card. The Chrome browser extension (${OPENGENI_BROWSER_EXTENSION_URL}) works only after the machine is connected.`,
+          notes: `The person sets up their machine from the chat card. The Chrome browser extension (${extensionUrl}) works only after the machine is connected.`,
         },
         lifecycle: {
           status: "available",
@@ -1880,7 +1897,7 @@ export function nativeConnectionCapabilityRecommendations(
             "connected_machine_enroll_token",
             "connected_machine_enable_screen_control",
           ],
-          browserExtensionUrl: OPENGENI_BROWSER_EXTENSION_URL,
+          browserExtensionUrl: extensionUrl,
           recommendationOnly: true,
         },
       }),
@@ -1889,6 +1906,41 @@ export function nativeConnectionCapabilityRecommendations(
   return items;
 }
 
+/**
+ * The `tool.auth_needed` payload of the setup card that fixes a person-fixable
+ * tool refusal (see USER_SETUP_BLOCKERS). Every tool and route that hits such a
+ * refusal posts this same card in the calling turn, so the person sees the fix
+ * on the first attempt. Null when the blocker's capability is not a native
+ * card this deployment can show.
+ */
+export function userSetupCardPayload(
+  blocker: UserSetupBlocker,
+  options: { toolName: string; requestedSandboxId?: string | null },
+): ToolAuthNeededPayload | null {
+  const item = nativeConnectionCapabilityRecommendations({ connectedMachines: true }).find(
+    (candidate) => candidate.id === blocker.capabilityId,
+  );
+  if (!item) return null;
+  return ToolAuthNeededPayload.parse({
+    serverId: "opengeni",
+    toolName: options.toolName,
+    // Built-in capabilities are Opengeni's own; a blank domain must not fail the card.
+    providerDomain: item.providerDomain?.trim() || "opengeni.local",
+    reason: "missing_connection",
+    capability: {
+      id: item.id,
+      name: item.name,
+      kind: item.kind,
+      source: item.source,
+      action: "connect",
+      rationale: blocker.rationale,
+      requiredVariables: [],
+    },
+    ...(options.requestedSandboxId ? { requestedSandboxId: options.requestedSandboxId } : {}),
+    ...(blocker.purpose ? { purpose: blocker.purpose } : {}),
+  });
+}
+
 function socialConnectionCounts(
   connections: SocialConnection[],
   provider: "x" | "reddit",