@opengeni/worker-bundle 0.28.3 → 0.28.4-canary.1

package/src/activities/mcp-credentials.ts

@@ -1,5 +1,6 @@
 import type { Settings } from "@opengeni/config";
 import type { ConnectionCredentialsPort } from "@opengeni/contracts";
+import type { HostMcpAcceptedAuthority } from "@opengeni/contracts/host-mcp-bindings";
 import {
   buildConnectionTokenResolver,
   buildHostConnectionTokenResolver,
@@ -13,6 +14,7 @@ import {
   type SessionTurnForExecution,
 } from "@opengeni/db";
 import { recordTenancyCompatibilityLaneUse, type Observability } from "@opengeni/observability";
+import { mcpOperationAuthorityDigest } from "./mcp-operation-authority";
 
 const OPENGENI_CONNECTION_ID_PATTERN =
   /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
@@ -39,46 +41,78 @@ export function connectionTokenResolverForTurn(input: {
   const readHostTurn = input.getHostTurnForAttempt ?? getSessionTurnForAttempt;
   const hostDb = input.db;
   const nativeResolver = buildConnectionTokenResolver(input.db, input.settings);
+  const recoveryEnabled = (serverId: string) =>
+    input.settings.mcpServers.some(
+      (server) =>
+        server.id === serverId &&
+        "operationRecovery" in server &&
+        server.operationRecovery !== undefined &&
+        Object.keys(server.operationRecovery ?? {}).length > 0,
+    );
   const configuredResolver = hostResolver
-    ? buildHostConnectionTokenResolver(hostResolver, {
-        accountId: input.accountId,
-        workspaceId: input.workspaceId,
-        sessionId: input.sessionId,
-        rootSessionId: input.rootSessionId,
-        turnId: input.turn.id,
-        attemptId: input.attemptId,
-        executionGeneration: input.turn.executionGeneration,
-        initiator: input.turn.initiator,
-        initiatorContext: input.turn.initiatorContext,
-        surface: "model",
-        // Only immutable captured direct-turn authority is currently supported.
-        // Direct, scheduled and exact causal/child snapshots are validated;
-        // no authority follows merely from a binding or creator identity.
-        authorizeDurableBinding: (request) => authorizeDirectHostMcpUse(hostDb, request),
-        authorizeExecution: async (request) => {
-          // Native UUID references already pass the accepted-use boundary below.
-          // Legacy opaque host IDs retain their compatibility path, but not a
-          // right to execute after their accepted attempt has stopped.
-          if (
-            request.connectionRef.authoritySource !== "host" &&
-            (!request.connectionRef.connectionId ||
-              OPENGENI_CONNECTION_ID_PATTERN.test(request.connectionRef.connectionId))
-          )
-            return true;
-          if (!request.attemptId) return false;
-          const current = await readHostTurn(
-            hostDb,
-            request.workspaceId,
-            request.sessionId,
-            request.attemptId,
-          );
-          return (
-            current !== null &&
-            current.id === request.turnId &&
-            current.executionGeneration === request.executionGeneration
-          );
-        },
-      })
+    ? async (
+        credentialRequest: ResolveConnectionCredentialInput,
+      ): Promise<ResolveConnectionCredentialResult> => {
+        let authorizedSnapshot: HostMcpAcceptedAuthority | undefined;
+        const wantsDigest = recoveryEnabled(credentialRequest.serverId);
+        const resolver = buildHostConnectionTokenResolver(hostResolver, {
+          accountId: input.accountId,
+          workspaceId: input.workspaceId,
+          sessionId: input.sessionId,
+          rootSessionId: input.rootSessionId,
+          turnId: input.turn.id,
+          attemptId: input.attemptId,
+          executionGeneration: input.turn.executionGeneration,
+          initiator: input.turn.initiator,
+          initiatorContext: input.turn.initiatorContext,
+          surface: "model",
+          // Only immutable captured direct-turn authority is currently supported.
+          // Direct, scheduled and exact causal/child snapshots are validated;
+          // no authority follows merely from a binding or creator identity.
+          authorizeDurableBinding: (request) =>
+            authorizeDirectHostMcpUse(
+              hostDb,
+              request,
+              wantsDigest
+                ? (snapshot) => {
+                    authorizedSnapshot = snapshot;
+                  }
+                : undefined,
+            ),
+          authorizeExecution: async (request) => {
+            // Native UUID references already pass the accepted-use boundary below.
+            // Legacy opaque host IDs retain their compatibility path, but not a
+            // right to execute after their accepted attempt has stopped.
+            if (
+              request.connectionRef.authoritySource !== "host" &&
+              (!request.connectionRef.connectionId ||
+                OPENGENI_CONNECTION_ID_PATTERN.test(request.connectionRef.connectionId))
+            )
+              return true;
+            if (!request.attemptId) return false;
+            const current = await readHostTurn(
+              hostDb,
+              request.workspaceId,
+              request.sessionId,
+              request.attemptId,
+            );
+            return (
+              current !== null &&
+              current.id === request.turnId &&
+              current.executionGeneration === request.executionGeneration
+            );
+          },
+        });
+        const result = await resolver(credentialRequest);
+        return result.status === "ok" && authorizedSnapshot
+          ? {
+              ...result,
+              operationAuthorityDigest: mcpOperationAuthorityDigest(credentialRequest, {
+                host: authorizedSnapshot,
+              }),
+            }
+          : result;
+      }
     : nativeResolver;
   const baseResolver = (request: ResolveConnectionCredentialInput) =>
     input.connectionCredentials?.mcpAuthoritySource === "host" &&
@@ -229,10 +263,30 @@ export function connectionTokenResolverForTurn(input: {
       });
     const withProviderRequestAuthorization = (
       result: ResolveConnectionCredentialResult,
+      attribution = result.status === "ok" ? result.connectionUseAttribution : undefined,
     ): ResolveConnectionCredentialResult => {
       if (result.status !== "ok") return result;
       return {
         ...result,
+        ...(attribution && recoveryEnabled(request.serverId)
+          ? {
+              operationAuthorityDigest: mcpOperationAuthorityDigest(request, {
+                native: attribution,
+                // Match the canonical DB recovery principal: a causal human
+                // survives goal/service continuations. These fields come from
+                // the accepted turn, never request.subjectId or caller JSON.
+                principal: input.turn.initiatingHumanSubjectId
+                  ? { kind: "subject", subjectId: input.turn.initiatingHumanSubjectId }
+                  : {
+                      kind: input.turn.initiator.kind,
+                      ...(input.turn.initiator.kind === "subject" ||
+                      input.turn.initiator.kind === "service"
+                        ? { subjectId: input.turn.initiator.subjectId }
+                        : {}),
+                    },
+              }),
+            }
+          : {}),
         authorizeProviderRequest: async () => {
           const authorization = await authorize({
             ...credentialUseContext,
@@ -286,7 +340,7 @@ export function connectionTokenResolverForTurn(input: {
         ? { subjectId: authorization.attribution.ownerSubjectId }
         : {}),
     });
-    return withProviderRequestAuthorization(result);
+    return withProviderRequestAuthorization(result, authorization.attribution);
   };
 }
 

package/src/activities/mcp-operation-authority.ts

@@ -0,0 +1,76 @@
+import { createHash } from "node:crypto";
+import { stableJson } from "@opengeni/contracts";
+import type { ConnectionUseAttribution } from "@opengeni/contracts/connection-authority";
+import type { HostMcpAcceptedAuthority } from "@opengeni/contracts/host-mcp-bindings";
+import type { ResolveConnectionCredentialInput } from "@opengeni/db";
+
+/** Metadata only. Callers must obtain authority from a current live fence.
+ * This equality key is never authorization and never replaces physical-use checks. */
+export function mcpOperationAuthorityDigest(
+  request: ResolveConnectionCredentialInput,
+  authority:
+    | {
+        native: ConnectionUseAttribution;
+        host?: never;
+        principal?: { kind: string; subjectId?: string };
+      }
+    | { host: HostMcpAcceptedAuthority; native?: never },
+): string {
+  const n = authority.native;
+  const h = authority.host;
+  const ref = request.connectionRef;
+  const metadata = {
+    version: 1,
+    serverId: request.serverId,
+    destinationUrl: request.destinationUrl,
+    credentialTarget: request.credentialTarget ?? "mcp",
+    connectionRef: {
+      authoritySource: ref.authoritySource,
+      connectionId: ref.connectionId,
+      provider: ref.provider,
+      providerDomain: ref.providerDomain,
+      kind: ref.kind,
+      subjectScope: ref.subjectScope,
+      hostBinding: ref.hostBinding,
+      scopes: ref.scopes ? [...ref.scopes].sort() : undefined,
+      resource: ref.resource,
+      selectedResources: ref.selectedResources
+        ? [...ref.selectedResources].sort((a, b) =>
+            stableJson(a) < stableJson(b) ? -1 : stableJson(a) > stableJson(b) ? 1 : 0,
+          )
+        : undefined,
+    },
+    native: n
+      ? {
+          organizationId: n.organizationId,
+          workspaceId: n.workspaceId,
+          sessionId: n.sessionId,
+          connectionId: n.connectionId,
+          connectionGeneration: n.connectionGeneration,
+          scope: n.scope,
+          ownerSubjectId: n.ownerSubjectId,
+          authorityId: n.authorityId,
+          grantId: n.grantId,
+          principal: "principal" in authority ? authority.principal : undefined,
+        }
+      : undefined,
+    host: h
+      ? {
+          accountId: h.accountId,
+          workspaceId: h.workspaceId,
+          targetSessionId: h.targetSessionId,
+          targetSessionVisibility: h.targetSessionVisibility,
+          targetSessionAuthorityEpoch: h.targetSessionAuthorityEpoch,
+          ownerSubjectId: h.ownerSubjectId,
+          ownerOrganizationMembershipId: h.ownerOrganizationMembershipId,
+          ownerMembershipAuthorizationRevision: h.ownerMembershipAuthorizationRevision,
+          bindingId: h.bindingId,
+          bindingGeneration: h.bindingGeneration,
+          definition: h.definition,
+          delegationId: h.delegationId,
+          delegationGeneration: h.delegationGeneration,
+        }
+      : undefined,
+  };
+  return createHash("sha256").update(stableJson(metadata)).digest("hex");
+}

package/src/activities/mcp-operation-observer.ts

@@ -0,0 +1,86 @@
+import type { Settings } from "@opengeni/config";
+import type { AttemptToolEnvironment } from "@opengeni/codemode";
+import { digestCanonicalJson } from "@opengeni/tool-gateway";
+import {
+  runMcpOperationObservationWithAuthority,
+  type ResolveConnectionCredentialInput,
+  type ResolveConnectionCredentialResult,
+} from "@opengeni/runtime";
+import type { McpOperationReaderDependencies } from "./mcp-operation-reader";
+
+/** Current-attempt adapter: no credential renewal authority survives this
+ * closure. The stored digest constrains fresh authority, never establishes it. */
+export function createMcpOperationObserverResolver(input: {
+  settings: Pick<Settings, "mcpServers">;
+  workspaceId: string;
+  credentialSubjectId?: string;
+  assertAttempt: () => Promise<void>;
+  resolveCredential: (
+    request: ResolveConnectionCredentialInput,
+  ) => Promise<ResolveConnectionCredentialResult>;
+  getEnvironment: () => Promise<AttemptToolEnvironment | null>;
+}): McpOperationReaderDependencies["resolveObserver"] {
+  return async (operation) => {
+    await input.assertAttempt();
+    const configured = input.settings.mcpServers.find(
+      (candidate) => candidate.id === operation.serverId,
+    );
+    const recovery = configured?.operationRecovery?.[operation.originalTool];
+    if (!configured?.connectionRef || !recovery) return { status: "unsupported" };
+    const destinationUrl = new URL(configured.url).toString();
+    if (
+      recovery.observerTool !== operation.observerTool ||
+      digestCanonicalJson(destinationUrl) !== operation.destinationDigest
+    ) {
+      return { status: "binding_changed" };
+    }
+    const connectionRef = structuredClone(configured.connectionRef);
+    const environment = await input.getEnvironment();
+    const observerEntry = environment?.catalog.entries.find(
+      (entry) =>
+        entry.identity.serverId === operation.serverId &&
+        entry.identity.toolName === operation.observerTool,
+    );
+    if (!environment || !observerEntry) return { status: "unsupported" };
+
+    const authorize = async () => {
+      await input.assertAttempt();
+      const resolved = await input.resolveCredential({
+        workspaceId: input.workspaceId,
+        serverId: operation.serverId,
+        toolName: operation.observerTool,
+        connectionRef,
+        destinationUrl,
+        forceRefresh: false,
+        ...(input.credentialSubjectId ? { subjectId: input.credentialSubjectId } : {}),
+      });
+      // This is credential-resolution authorization. The actual broker keeps
+      // ownership of the physical provider-request authorization/audit fact.
+      return (
+        resolved.status === "ok" && resolved.operationAuthorityDigest === operation.authorityDigest
+      );
+    };
+    if (!(await authorize())) return { status: "auth_needed" };
+    return {
+      status: "ready",
+      authorize,
+      callObserver: async (tool, args) => {
+        if (tool !== operation.observerTool) throw new Error("MCP observer binding changed");
+        return await runMcpOperationObservationWithAuthority(
+          {
+            serverId: operation.serverId,
+            observerTool: operation.observerTool,
+            destinationDigest: operation.destinationDigest,
+            authorityDigest: operation.authorityDigest,
+          },
+          async () =>
+            await environment.callModel({
+              modelName: observerEntry.modelName,
+              arguments: args,
+              subjectId: "worker:first-party-mcp",
+            }),
+        );
+      },
+    };
+  };
+}

package/src/activities/mcp-operation-reader.ts

@@ -0,0 +1,108 @@
+import type { AttemptToolResult } from "@opengeni/contracts";
+import { observeMcpOperation, type McpObservationReceipt } from "@opengeni/runtime";
+import type { McpOperationReadSelector } from "./agent-turn/mcp-operation-read-tool";
+
+type TerminalReceipt = Extract<McpObservationReceipt, { status: "completed" }>;
+
+/** Internal, credential-free projection loaded through canonical current
+ * attempt/session authorization. Never return this object directly to tools. */
+export type McpOperationReadRecord = {
+  operationId: string;
+  sourceTurnId: string;
+  sourceCallId: string | null;
+  serverId: string;
+  originalTool: string;
+  observerTool: string;
+  argumentDigest: string;
+  destinationDigest: string;
+  authorityDigest: string;
+  originalOutcome: "captured" | "completed" | "outcome_unknown";
+  originalResult: AttemptToolResult | null;
+  receipt: TerminalReceipt | null;
+};
+
+type ObserverResolution =
+  | { status: "unsupported" | "auth_needed" | "binding_changed" }
+  | {
+      status: "ready";
+      authorize: (phase: "before_request" | "before_delivery") => Promise<boolean>;
+      callObserver: (tool: string, args: Record<string, unknown>) => Promise<unknown>;
+    };
+
+export type McpOperationReaderDependencies = {
+  /** Includes live attempt and original-principal/session disclosure checks. */
+  load: (selector: McpOperationReadSelector) => Promise<McpOperationReadRecord | null>;
+  claim: (operationId: string) => Promise<string | null>;
+  release: (operationId: string, claimId: string) => Promise<void>;
+  /** Claim-fenced transaction storing one immutable receipt. Must recheck
+   * canonical current authority and never rewrite the original outcome.
+   * Delivery uses the ordinary operation_read tool-result lifecycle. */
+  settle: (
+    operationId: string,
+    claimId: string,
+    receipt: TerminalReceipt,
+  ) => Promise<McpOperationReadRecord>;
+  /** Binds the current trusted config/connection to the persisted original
+   * digests. Model arguments may not supply or replace any of that authority. */
+  resolveObserver: (operation: McpOperationReadRecord) => Promise<ObserverResolution>;
+};
+
+/** One explicit read; no timer, inference wake, or mutation replay. */
+export async function readMcpOperation(
+  selector: McpOperationReadSelector,
+  dependencies: McpOperationReaderDependencies,
+): Promise<Record<string, unknown>> {
+  const operation = await dependencies.load(selector);
+  if (!operation) throw new Error("MCP operation is unavailable");
+  if (operation.receipt || operation.originalOutcome === "completed") return project(operation);
+
+  const observer = await dependencies.resolveObserver(operation);
+  if (observer.status !== "ready") return project(operation, { status: observer.status });
+  const claimId = await dependencies.claim(operation.operationId);
+  if (!claimId) {
+    // A competing reader may have committed after our initial load. Re-read
+    // under current authority instead of returning an old cached projection.
+    const fresh = await dependencies.load({ operationId: operation.operationId });
+    if (!fresh) throw new Error("MCP operation is unavailable");
+    return project(
+      fresh,
+      fresh.receipt || fresh.originalOutcome === "completed"
+        ? undefined
+        : { status: "observation_in_progress" },
+    );
+  }
+  let settled = false;
+  try {
+    const receipt = await observeMcpOperation({
+      binding: {
+        operationId: operation.operationId,
+        serverId: operation.serverId,
+        originalTool: operation.originalTool,
+        observerTool: operation.observerTool,
+        argumentDigest: operation.argumentDigest,
+      },
+      authorize: observer.authorize,
+      callObserver: observer.callObserver,
+    });
+    if (receipt.status !== "completed") return project(operation, receipt);
+    const recorded = await dependencies.settle(operation.operationId, claimId, receipt);
+    settled = true;
+    return project(recorded);
+  } finally {
+    if (!settled) await dependencies.release(operation.operationId, claimId);
+  }
+}
+
+function project(
+  operation: McpOperationReadRecord,
+  observation?: Record<string, unknown>,
+): Record<string, unknown> {
+  return {
+    operationId: operation.operationId,
+    original: { turnId: operation.sourceTurnId, sourceCallId: operation.sourceCallId },
+    invocationOutcome:
+      operation.originalOutcome === "captured" ? "outcome_unknown" : operation.originalOutcome,
+    ...(operation.originalOutcome === "completed" ? { result: operation.originalResult } : {}),
+    observation: observation ?? operation.receipt ?? { status: "unknown" },
+  };
+}

package/src/activities/mcp-operation-store.ts

@@ -0,0 +1,98 @@
+import { AttemptToolResult } from "@opengeni/contracts";
+import type { Database } from "@opengeni/db";
+import {
+  readMcpOperation as readStoredMcpOperation,
+  claimMcpOperationObservation,
+  releaseMcpOperationObservation,
+  settleMcpOperationObservation,
+  type McpOperationAttempt,
+  type McpOperationRecord,
+} from "@opengeni/db/mcp-operations";
+import type {
+  McpOperationReaderDependencies,
+  McpOperationReadRecord,
+} from "./mcp-operation-reader";
+
+/** All DB calls remain bound to the actual accepted worker attempt. Locators
+ * supplied to operation_read cannot replace this scope or its principal. */
+export function createMcpOperationReadStore(
+  db: Database,
+  attempt: McpOperationAttempt,
+): Pick<McpOperationReaderDependencies, "load" | "claim" | "release" | "settle"> {
+  const current = { ...attempt };
+  const load: McpOperationReaderDependencies["load"] = async (selector) => {
+    const found = await readStoredMcpOperation(db, current, selector);
+    if (found.status === "ambiguous") {
+      throw new Error("MCP source call matches multiple operations; select an exact operationId");
+    }
+    return found.status === "found" ? projectRecord(found.operation) : null;
+  };
+  return {
+    load,
+    claim: async (operationId) => {
+      const result = await claimMcpOperationObservation(db, current, operationId);
+      return result.status === "claimed" ? result.claimId : null;
+    },
+    release: async (operationId, claimId) => {
+      await releaseMcpOperationObservation(db, current, { operationId, claimId });
+    },
+    settle: async (operationId, claimId, receipt) => {
+      const outcome = await settleMcpOperationObservation(db, current, {
+        operationId,
+        claimId,
+        receiptRevision: receipt.receiptRevision,
+        result: receipt.result,
+      });
+      if (outcome.status === "conflict") {
+        throw new Error(
+          "MCP provider returned conflicting terminal receipts; the first receipt is preserved",
+        );
+      }
+      if (
+        outcome.status !== "settled" &&
+        outcome.status !== "existing" &&
+        outcome.status !== "original_completed"
+      ) {
+        throw new Error(
+          "MCP observation claim is no longer current; read the existing operation again",
+        );
+      }
+      const recorded = await load({ operationId });
+      if (!recorded) throw new Error("MCP operation is unavailable");
+      return recorded;
+    },
+  };
+}
+
+function projectRecord(record: McpOperationRecord): McpOperationReadRecord {
+  if (record.observationResult !== null && record.receiptRevision === null) {
+    throw new Error("Stored MCP operation receipt is incomplete");
+  }
+  return {
+    operationId: record.operationId,
+    sourceTurnId: record.sourceTurnId,
+    sourceCallId: record.sourceCallId,
+    serverId: record.serverId,
+    originalTool: record.originalTool,
+    observerTool: record.observerTool,
+    argumentDigest: record.argumentDigest,
+    destinationDigest: record.destinationDigest,
+    authorityDigest: record.authorityDigest,
+    // Capture precedes the physical request; after a crash it is not proof
+    // that the mutation was or was not sent. It never authorizes a replay.
+    originalOutcome: record.originalOutcome,
+    originalResult:
+      record.originalResult === null ? null : AttemptToolResult.parse(record.originalResult),
+    receipt:
+      record.observationResult === null
+        ? null
+        : {
+            version: 1,
+            operationRef: record.operationId,
+            fingerprint: { version: 1, algorithm: "sha256", value: record.argumentDigest },
+            status: "completed",
+            receiptRevision: record.receiptRevision!,
+            result: AttemptToolResult.parse(record.observationResult),
+          },
+  };
+}