@opengeni/api-router 4.3.3-canary.39786771332001 → 4.4.1

package/dist/index.js

@@ -20,7 +20,7 @@ import {
   startSlackInteractionPump,
   startTemporalScheduleCleanupPump,
   withAccessGrantSessionRlsContext
-} from "./chunk-S5VJ3GVR.js";
+} from "./chunk-3KRHXJPM.js";
 import "./chunk-OGQDXVXY.js";
 
 // src/index.ts

package/dist/mcp/user-setup-card.d.ts

@@ -0,0 +1,21 @@
+import { type UserSetupBlocker } from "@opengeni/contracts";
+export { sessionChatUrl } from "@opengeni/contracts";
+type ToolRefusal = {
+    code?: string | undefined;
+    reason?: string | undefined;
+};
+export type UserSetupCardPost = (blocker: UserSetupBlocker) => Promise<{
+    eventId: string | null;
+    chatUrl: string | null;
+} | null>;
+/**
+ * Post the setup card when a tool was refused for something the person can fix
+ * themselves (USER_SETUP_BLOCKERS), and tell the agent it is posted. Every
+ * other result is returned unchanged. Posting is best effort: if it cannot be
+ * posted, the original refusal still stands.
+ */
+export declare function withUserSetupCard<T extends ToolRefusal>(result: T, post: UserSetupCardPost): Promise<T & {
+    card?: "shown";
+    cardEventId?: string | null;
+    chatUrl?: string;
+}>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/api-router",
-  "version": "4.3.3-canary.39786771332001",
+  "version": "4.4.1",
   "description": "Opengeni HTTP surface: the Hono adapter/router (createApp), routes, MCP HTTP transport, and HTTP access adapters over @opengeni/core. An engine-distribution surface — its runtime closure includes engine-internal packages.",
   "license": "Apache-2.0",
   "repository": {
@@ -45,29 +45,29 @@
     "@keeper-security/secrets-manager-core": "17.6.0",
     "@llamaindex/liteparse": "2.14.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opengeni/agent-proto": "4.3.3-canary.39786771332001",
-    "@opengeni/artifact-tool": "4.3.3-canary.39786771332001",
-    "@opengeni/capabilities": "4.3.3-canary.39786771332001",
-    "@opengeni/codemode": "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/core": "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/github": "4.3.3-canary.39786771332001",
-    "@opengeni/interaction": "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/tool-gateway": "4.3.3-canary.39786771332001",
-    "@opengeni/vaults": "4.3.3-canary.39786771332001",
-    "@opengeni/vaults-keeper": "4.3.3-canary.39786771332001",
-    "@opengeni/vaults-onepassword": "4.3.3-canary.39786771332001",
-    "@opengeni/vaults-protonpass": "4.3.3-canary.39786771332001",
-    "@opengeni/xai-subscription": "4.3.3-canary.39786771332001",
+    "@opengeni/agent-proto": "4.4.1",
+    "@opengeni/artifact-tool": "4.4.1",
+    "@opengeni/capabilities": "4.4.1",
+    "@opengeni/codemode": "4.4.1",
+    "@opengeni/codex": "4.4.1",
+    "@opengeni/config": "4.4.1",
+    "@opengeni/contracts": "4.4.1",
+    "@opengeni/core": "4.4.1",
+    "@opengeni/db": "4.4.1",
+    "@opengeni/documents": "4.4.1",
+    "@opengeni/events": "4.4.1",
+    "@opengeni/github": "4.4.1",
+    "@opengeni/interaction": "4.4.1",
+    "@opengeni/network": "4.4.1",
+    "@opengeni/observability": "4.4.1",
+    "@opengeni/runtime": "4.4.1",
+    "@opengeni/storage": "4.4.1",
+    "@opengeni/tool-gateway": "4.4.1",
+    "@opengeni/vaults": "4.4.1",
+    "@opengeni/vaults-keeper": "4.4.1",
+    "@opengeni/vaults-onepassword": "4.4.1",
+    "@opengeni/vaults-protonpass": "4.4.1",
+    "@opengeni/xai-subscription": "4.4.1",
     "@temporalio/client": "^1.17.0",
     "ajv": "^8.20.0",
     "better-auth": "^1.6.14",

package/src/mcp/server.ts

@@ -18,11 +18,7 @@ import { enableMachineScreenControl, enrollmentAccess } from "../sandbox/screen-
 import { registerNotificationTools } from "./notification-tools";
 import { excelAddinSetup, registerExcelTools } from "./excel-tools";
 import { capabilityAccountReadiness } from "./capability-account-readiness";
-import {
-  sessionChatUrl,
-  withMachinePermissionCard,
-  type MachinePermissionCardPost,
-} from "./machine-permission-card";
+import { sessionChatUrl, withUserSetupCard, type UserSetupCardPost } from "./user-setup-card";
 import {
   prepareWorkspaceArtifactUpload,
   prepareWorkspaceArtifactPublication,
@@ -215,6 +211,7 @@ import {
   CONNECTED_MACHINE_CAPABILITY_ID,
   EXCEL_ADDIN_CAPABILITY_ID,
   nativeConnectionCapabilityRecommendations,
+  userSetupCardPayload,
   OPENGENI_BROWSER_EXTENSION_URL,
   requireLiveAgentAttemptAuthorization,
   requireSessionAuthorization,
@@ -4323,23 +4320,23 @@ function registerFleetTools(
     };
   };
 
-  // A refusal that only the owner's permission can resolve posts the Connected
-  // Machine card right away, in the agent's own turn, so the person can allow
-  // the machine without the agent having to find and call the card tool. Only
-  // exact agent attempts post it. The card names the machine the agent asked
-  // for, so it can lead with allowing that machine. A repeated refusal for the
-  // same machine in the same turn reuses that turn's card; the lookup and
-  // append run atomically under the attempt fence so parallel refusals cannot
-  // stack copies. Cards for every other capability are never limited.
-  const machinePermissionCard =
-    (toolName: string, target: string): MachinePermissionCardPost =>
-    async () => {
+  // A refusal the person can fix themselves (USER_SETUP_BLOCKERS, for example
+  // the owner not having allowed this chat to use their machine yet) posts the
+  // setup card right away, in the agent's own turn, so the person sees the fix
+  // without the agent having to find and call the card tool. Only exact agent
+  // attempts post it. A machine card names the machine the agent asked for, so
+  // it can lead with allowing that machine. A repeated refusal for the same
+  // machine in the same turn reuses that turn's card; the lookup and append run
+  // atomically under the attempt fence so parallel refusals cannot stack
+  // copies. Cards for every other capability are never limited.
+  const userSetupCard =
+    (toolName: string, target: string): UserSetupCardPost =>
+    async (blocker) => {
       const requestedSandboxId = UUID_TARGET.test(target) ? target.toLowerCase() : null;
       if (!exactAgentAttemptClaims(grant)) return null;
       const claims = exactAgentCommandContext(grant, sessionId);
-      const item = nativeConnectionCapabilityRecommendations({ connectedMachines: true }).find(
-        (candidate) => candidate.id === CONNECTED_MACHINE_CAPABILITY_ID,
-      )!;
+      const payload = userSetupCardPayload(blocker, { toolName, requestedSandboxId });
+      if (!payload) return null;
       const appended = await appendTurnCapabilityCardOnce(
         deps.db,
         grant.workspaceId,
@@ -4347,23 +4344,13 @@ function registerFleetTools(
         claims.callerTurnId,
         claims.callerExecutionGeneration,
         claims.callerAttemptId,
-        item.id,
-        {
-          type: "tool.auth_needed",
-          payload: {
-            ...capabilityCardPayload(item, {
-              action: "connect",
-              rationale: "Allow this chat to use your computer.",
-              toolName,
-            }),
-            ...(requestedSandboxId ? { requestedSandboxId } : {}),
-          },
-        },
+        blocker.capabilityId,
+        { type: "tool.auth_needed", payload },
         requestedSandboxId,
       );
       await publishDurableSessionEvents(deps.bus, grant.workspaceId, sessionId, appended.events);
       if (!appended.accepted) {
-        throw new Error("The calling turn was replaced before the machine card committed.");
+        throw new Error("The calling turn was replaced before the setup card committed.");
       }
       return {
         eventId: appended.existingEventId ?? appended.events[0]?.id ?? null,
@@ -4398,9 +4385,9 @@ function registerFleetTools(
     },
     async ({ target }) =>
       json(
-        await withMachinePermissionCard(
+        await withUserSetupCard(
           await swapActiveSandbox(services, await fleetContext(), target),
-          machinePermissionCard("sandbox_attach", target),
+          userSetupCard("sandbox_attach", target),
         ),
       ),
   );
@@ -4414,9 +4401,9 @@ function registerFleetTools(
     },
     async ({ target }) =>
       json(
-        await withMachinePermissionCard(
+        await withUserSetupCard(
           await swapActiveSandbox(services, await fleetContext(), target),
-          machinePermissionCard("sandbox_swap", target),
+          userSetupCard("sandbox_swap", target),
         ),
       ),
   );
@@ -4458,12 +4445,12 @@ function registerFleetTools(
             )
           : null;
       return json(
-        await withMachinePermissionCard(
+        await withUserSetupCard(
           await runOnSandbox(services, await fleetContext(), target, typedOp, {
             ...(transientExecEnvironment ? { transientExecEnvironment } : {}),
             ...(secretResolver ? { secretResolver } : {}),
           }),
-          machinePermissionCard("run_on", target),
+          userSetupCard("run_on", target),
         ),
       );
     },

package/src/mcp/user-setup-card.ts

@@ -0,0 +1,42 @@
+import {
+  type UserSetupBlocker,
+  userSetupBlocker,
+  userSetupCardShownMessage,
+} from "@opengeni/contracts";
+
+export { sessionChatUrl } from "@opengeni/contracts";
+
+type ToolRefusal = { code?: string | undefined; reason?: string | undefined };
+
+export type UserSetupCardPost = (blocker: UserSetupBlocker) => Promise<{
+  eventId: string | null;
+  chatUrl: string | null;
+} | null>;
+
+/**
+ * Post the setup card when a tool was refused for something the person can fix
+ * themselves (USER_SETUP_BLOCKERS), and tell the agent it is posted. Every
+ * other result is returned unchanged. Posting is best effort: if it cannot be
+ * posted, the original refusal still stands.
+ */
+export async function withUserSetupCard<T extends ToolRefusal>(
+  result: T,
+  post: UserSetupCardPost,
+): Promise<T & { card?: "shown"; cardEventId?: string | null; chatUrl?: string }> {
+  const blocker = userSetupBlocker(result.code);
+  if (!blocker) return result;
+  let posted: Awaited<ReturnType<UserSetupCardPost>>;
+  try {
+    posted = await post(blocker);
+  } catch {
+    return result;
+  }
+  if (!posted) return result;
+  return {
+    ...result,
+    reason: userSetupCardShownMessage(blocker, posted.chatUrl),
+    card: "shown",
+    cardEventId: posted.eventId,
+    ...(posted.chatUrl ? { chatUrl: posted.chatUrl } : {}),
+  };
+}

package/src/sandbox-file-artifacts.ts

@@ -461,7 +461,9 @@ export function sandboxArtifactRelativePath(value: string, workspaceRoot = "/wor
   }
   if (!relative) {
     throw new HTTPException(400, {
-      message: "sandbox artifact path must name a file inside the active workspace root",
+      // Say which root: on a connected machine the file may exist outside it,
+      // and copying it in is the way forward.
+      message: `sandbox artifact path must name a file inside this session's workspace root ${workspaceRoot}; ${path} is outside it, so copy the file into the workspace first and use that path`,
     });
   }
   if (absolute.length > SANDBOX_ARTIFACT_ABSOLUTE_PATH_MAX_CHARS) {

package/dist/mcp/machine-permission-card.d.ts

@@ -1,33 +0,0 @@
-/** The one refusal a card can resolve: the owner just has not allowed this chat. */
-export declare const MACHINE_PERMISSION_REQUIRED_CODE = "personal_machine_permission_required";
-/**
- * What the agent reads after the card was posted for it. The card is posted in
- * this chat's Opengeni timeline; the person may instead be reading the chat in
- * Slack, or this may be a worker or scheduled chat, so the text names the chat
- * link rather than promising the card is in front of them. Choosing the
- * machine on the card sends a message that continues the chat, so the agent
- * has nothing to wait for and nothing to retry.
- */
-export declare function machinePermissionCardShownReason(chatUrl: string | null): string;
-type MachineRefusal = {
-    code?: string | undefined;
-    reason?: string | undefined;
-};
-export type MachinePermissionCardPost = () => Promise<{
-    eventId: string | null;
-    chatUrl: string | null;
-} | null>;
-/**
- * Post the Connected Machine card when a swap or one-off command was refused
- * only because the machine's owner has not allowed this chat yet, and tell the
- * agent it is posted. Every other result is returned unchanged. Posting is best
- * effort: if it cannot be posted, the original refusal still stands.
- */
-export declare function withMachinePermissionCard<T extends MachineRefusal>(result: T, post: MachinePermissionCardPost): Promise<T & {
-    card?: "shown";
-    cardEventId?: string | null;
-    chatUrl?: string;
-}>;
-/** The Opengeni console link for a chat, or null when no safe web base is configured. */
-export declare function sessionChatUrl(base: string | null | undefined, workspaceId: string, sessionId: string): string | null;
-export {};

package/src/mcp/machine-permission-card.ts

@@ -1,78 +0,0 @@
-/** The one refusal a card can resolve: the owner just has not allowed this chat. */
-export const MACHINE_PERMISSION_REQUIRED_CODE = "personal_machine_permission_required";
-
-/**
- * What the agent reads after the card was posted for it. The card is posted in
- * this chat's Opengeni timeline; the person may instead be reading the chat in
- * Slack, or this may be a worker or scheduled chat, so the text names the chat
- * link rather than promising the card is in front of them. Choosing the
- * machine on the card sends a message that continues the chat, so the agent
- * has nothing to wait for and nothing to retry.
- */
-export function machinePermissionCardShownReason(chatUrl: string | null): string {
-  const elsewhere = chatUrl
-    ? `If they are reading this chat somewhere else (for example Slack, or this is a worker or scheduled chat), give them this link to allow it: ${chatUrl}. `
-    : "If they are reading this chat somewhere else (for example Slack, or this is a worker or scheduled chat), tell them to open this chat in Opengeni to allow it. ";
-  return (
-    "This is a personal (Only me) machine, and its owner has not allowed this chat to use it yet. " +
-    "A card where the owner can allow it is now posted in this chat in Opengeni. " +
-    "If they are reading this chat in Opengeni, tell them in one short sentence that they can allow it there; do not describe buttons or steps. " +
-    elsewhere +
-    "Do not wait for it and do not retry: when they allow it, their message continues this chat."
-  );
-}
-
-type MachineRefusal = { code?: string | undefined; reason?: string | undefined };
-
-export type MachinePermissionCardPost = () => Promise<{
-  eventId: string | null;
-  chatUrl: string | null;
-} | null>;
-
-/**
- * Post the Connected Machine card when a swap or one-off command was refused
- * only because the machine's owner has not allowed this chat yet, and tell the
- * agent it is posted. Every other result is returned unchanged. Posting is best
- * effort: if it cannot be posted, the original refusal still stands.
- */
-export async function withMachinePermissionCard<T extends MachineRefusal>(
-  result: T,
-  post: MachinePermissionCardPost,
-): Promise<T & { card?: "shown"; cardEventId?: string | null; chatUrl?: string }> {
-  if (result.code !== MACHINE_PERMISSION_REQUIRED_CODE) return result;
-  let posted: Awaited<ReturnType<MachinePermissionCardPost>>;
-  try {
-    posted = await post();
-  } catch {
-    return result;
-  }
-  if (!posted) return result;
-  return {
-    ...result,
-    reason: machinePermissionCardShownReason(posted.chatUrl),
-    card: "shown",
-    cardEventId: posted.eventId,
-    ...(posted.chatUrl ? { chatUrl: posted.chatUrl } : {}),
-  };
-}
-
-/** The Opengeni console link for a chat, or null when no safe web base is configured. */
-export function sessionChatUrl(
-  base: string | null | undefined,
-  workspaceId: string,
-  sessionId: string,
-): string | null {
-  if (!base) return null;
-  try {
-    const url = new URL(
-      `/workspaces/${encodeURIComponent(workspaceId)}/sessions/${encodeURIComponent(sessionId)}`,
-      base,
-    );
-    if ((url.protocol !== "https:" && url.protocol !== "http:") || url.username || url.password) {
-      return null;
-    }
-    return url.toString();
-  } catch {
-    return null;
-  }
-}