@opengeni/core 4.3.3-canary.39786771332001 → 4.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/core",
-  "version": "4.3.3-canary.39786771332001",
+  "version": "4.4.1",
   "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.4.1",
+    "@opengeni/codex": "4.4.1",
+    "@opengeni/config": "4.4.1",
+    "@opengeni/contracts": "4.4.1",
+    "@opengeni/db": "4.4.1",
+    "@opengeni/documents": "4.4.1",
+    "@opengeni/events": "4.4.1",
+    "@opengeni/network": "4.4.1",
+    "@opengeni/observability": "4.4.1",
+    "@opengeni/runtime": "4.4.1",
+    "@opengeni/storage": "4.4.1",
+    "@opengeni/vaults": "4.4.1",
     "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,
@@ -1889,6 +1891,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",