@opengeni/runtime 2.5.2 → 2.5.3-canary.0

package/src/index.ts

@@ -1,5 +1,29 @@
 import type { ModelProviderApi, ResolvedModelProvider, Settings } from "@opengeni/config";
 import { executeCommandReadWithRefresh } from "./command-read-refresh";
+import {
+  captureMcpOperationDispatch,
+  hasActiveRecoverableMcpOperation,
+  runRecoverableMcpOperation,
+  type McpOperationPersistence,
+} from "./mcp-operation-dispatch";
+export {
+  captureMcpOperationDispatch,
+  hasActiveRecoverableMcpOperation,
+  McpOperationOutcomeUnknownError,
+  runRecoverableMcpOperation,
+  type CapturedMcpOperation,
+  type McpOperationPersistence,
+  type RecoverableMcpOperation,
+} from "./mcp-operation-dispatch";
+import { assertMcpOperationObservationAuthority } from "./mcp-operation-observation";
+export {
+  assertMcpOperationObservationAuthority,
+  observeMcpOperation,
+  runMcpOperationObservationWithAuthority,
+  type McpOperationObservationAuthority,
+  type McpObservationBinding,
+  type McpObservationReceipt,
+} from "./mcp-operation-observation";
 import { formatSkillCatalog, type SkillCatalogDescriptor } from "./skill-catalog";
 export { formatSkillCatalog, type SkillCatalogDescriptor } from "./skill-catalog";
 import {
@@ -11,6 +35,7 @@ import {
   AGENT_INSTRUCTIONS_CORE_PLACEHOLDER,
   collectSandboxEnvironment,
   configuredProviders,
+  McpOperationRecoverySchema,
   firstPartyMcpInternalBaseUrl,
   firstPartyMcpInternalWorkspaceUrl,
   resolveFirstPartyDelegationSecret,
@@ -683,6 +708,8 @@ export type ResolveConnectionCredentialResult =
       connectionId: string;
       authoritySource?: "host";
       authorizeProviderRequest?: () => Promise<boolean>;
+      /** Metadata-only immutable authority binding supplied by the trusted worker resolver. */
+      operationAuthorityDigest?: string;
       expiresAt?: Date | null;
     }
   | {
@@ -1723,6 +1750,11 @@ type ModelToolInvocation = {
 };
 
 const modelToolInvocation = new AsyncLocalStorage<ModelToolInvocation>();
+// Correlation must not activate the separate approval-only invocation guard.
+const modelMcpCallIdentity = new AsyncLocalStorage<{
+  modelName: string;
+  callId: string;
+} | null>();
 const agentInputWaitYields = new WeakMap<object, InputWaitYield>();
 
 export type BuildAgentOptions = {
@@ -2657,6 +2689,7 @@ export function buildOpenGeniAgent(
       agent as unknown as ApprovalCapableAgent,
       options.approvedToolCallId,
     );
+    installModelMcpCallIdentity(agent as unknown as ApprovalCapableAgent);
     return agent;
   }
 
@@ -2785,6 +2818,7 @@ export function buildOpenGeniAgent(
     agent as unknown as ApprovalCapableAgent,
     options.approvedToolCallId,
   );
+  installModelMcpCallIdentity(agent as unknown as ApprovalCapableAgent);
   return agent;
 }
 
@@ -2876,6 +2910,42 @@ type ApprovalCapableAgent = {
   clone?: (config: unknown) => ApprovalCapableAgent;
 };
 
+/** Preserve SDK correlation through MCP projection without granting approval.
+ * SandboxAgent clones rebuild instance methods, so reinstall on every clone. */
+function installModelMcpCallIdentity(agent: ApprovalCapableAgent): void {
+  const listMcpTools = agent.getMcpTools.bind(agent);
+  agent.getMcpTools = async (resolutionContext: unknown) =>
+    (await listMcpTools(resolutionContext)).map((tool) => {
+      if (tool.type !== "function") return tool;
+      const invoke = tool.invoke.bind(tool);
+      return {
+        ...tool,
+        invoke: async (runContext, input, details) => {
+          const callId = details?.toolCall?.callId;
+          return await modelMcpCallIdentity.run(
+            typeof callId === "string" && callId.length > 0
+              ? { modelName: tool.name, callId }
+              : null,
+            async () => await invoke(runContext, input, details),
+          );
+        },
+      };
+    });
+  const clone = agent.clone?.bind(agent);
+  if (clone) {
+    agent.clone = (config: unknown) => {
+      const cloned = clone(config);
+      installModelMcpCallIdentity(cloned);
+      return cloned;
+    };
+  }
+}
+
+function modelMcpSourceCallId(modelName: string): string | undefined {
+  const identity = modelMcpCallIdentity.getStore();
+  return identity?.modelName === modelName ? identity.callId : undefined;
+}
+
 /**
  * Install the approval wrap on a single agent instance: replace `getMcpTools`
  * with one that stamps `needsApproval: () => true` on every MCP tool whose
@@ -3612,6 +3682,8 @@ export type ToolPreparationPhaseMeasurement = {
 };
 
 export type PrepareToolsOptions = {
+  /** Opt-in exact-attempt persistence; absence preserves ordinary MCP execution. */
+  mcpOperationPersistence?: McpOperationPersistence;
   /** Live exact-owner control refresh; API remains read/observation authority. */
   refreshOwnedCommand?: (commandId: string) => Promise<boolean>;
   accountId?: string;
@@ -3986,24 +4058,30 @@ export async function prepareAgentTools(
           }
           const optional = tool.optional === true;
           return {
-            server: new PrefixedMcpServer(
-              local.server,
-              config.id,
-              config.allowedTools,
-              optional || Boolean(config.connectionRef),
-              aggregateToolBudget,
-              `${config.id}:${index}`,
-              false,
-              buildConnectorAttachmentAuthority(
-                config,
-                options,
-                resolvedMcpToolConnectionIds,
-                config.url,
-                local.resolvedConnectionId,
+            server: configureMcpOperationRecovery(
+              new PrefixedMcpServer(
+                local.server,
+                config.id,
+                config.allowedTools,
+                optional || Boolean(config.connectionRef),
+                aggregateToolBudget,
+                `${config.id}:${index}`,
+                false,
+                buildConnectorAttachmentAuthority(
+                  config,
+                  options,
+                  resolvedMcpToolConnectionIds,
+                  config.url,
+                  local.resolvedConnectionId,
+                ),
+                tool.eager !== true,
+                local.preflightCall,
+                local.approvalAuthority,
               ),
-              tool.eager !== true,
-              local.preflightCall,
-              local.approvalAuthority,
+              config,
+              options,
+              config.url,
+              false,
             ),
             bestEffort: optional || Boolean(config.connectionRef),
             optional,
@@ -4121,24 +4199,30 @@ export async function prepareAgentTools(
                 }
               : {}),
           });
-        const server = new PrefixedMcpServer(
-          innerServer,
-          config.id,
-          config.allowedTools,
-          bestEffort,
-          aggregateToolBudget,
-          `${config.id}:${index}`,
-          firstParty && !bestEffort,
-          buildConnectorAttachmentAuthority(config, options, resolvedMcpToolConnectionIds, url),
-          tool.eager !== true,
-          undefined,
-          undefined,
-          firstParty && config.id === "opengeni" && !config.connectionRef && !bridge
-            ? inputWaitYield
-            : undefined,
-          firstParty && config.id === "opengeni" && !config.connectionRef && !bridge
-            ? options.refreshOwnedCommand
-            : undefined,
+        const server = configureMcpOperationRecovery(
+          new PrefixedMcpServer(
+            innerServer,
+            config.id,
+            config.allowedTools,
+            bestEffort,
+            aggregateToolBudget,
+            `${config.id}:${index}`,
+            firstParty && !bestEffort,
+            buildConnectorAttachmentAuthority(config, options, resolvedMcpToolConnectionIds, url),
+            tool.eager !== true,
+            undefined,
+            undefined,
+            firstParty && config.id === "opengeni" && !config.connectionRef && !bridge
+              ? inputWaitYield
+              : undefined,
+            firstParty && config.id === "opengeni" && !config.connectionRef && !bridge
+              ? options.refreshOwnedCommand
+              : undefined,
+          ),
+          config,
+          options,
+          url,
+          Boolean(config.connectionRef) && !bridge && !isCodexAppsMcpServer(config),
         );
         return {
           server,
@@ -4788,18 +4872,42 @@ async function prepareToolGatewayDefinitionsFromServers(
                   }),
               }
             : {}),
-          execute: async (args, context) =>
-            await server.executeCatalogTool(
-              toolName,
-              args,
-              {
-                ...(context.transportMeta ?? {}),
-                opengeniOperationId: context.operationId,
-              },
+          execute: async (args, context) => {
+            const execute = async () =>
+              await server.executeCatalogTool(
+                toolName,
+                args,
+                {
+                  ...(context.transportMeta ?? {}),
+                  opengeniOperationId: context.operationId,
+                },
+                {
+                  ...(context.signal ? { signal: context.signal } : {}),
+                },
+              );
+            const recovery = configuredMcpOperationRecovery(server, toolName);
+            if (!recovery) return await execute();
+            if (!recovery.supported || !["model", "codemode"].includes(context.caller.kind)) {
+              throw new Error(
+                "MCP operation recovery requires an exact attempt and remote brokered execution",
+              );
+            }
+            return await runRecoverableMcpOperation(
               {
-                ...(context.signal ? { signal: context.signal } : {}),
+                operationId: context.operationId,
+                ...(context.sourceCallId === undefined
+                  ? {}
+                  : { sourceCallId: context.sourceCallId }),
+                serverId: server.registryId,
+                originalTool: toolName,
+                observerTool: recovery.policy[toolName]!.observerTool,
+                destinationDigest: recovery.destinationDigest,
+                argumentDigest: digestCanonicalJson(args),
               },
-            ),
+              recovery.persistence,
+              execute,
+            );
+          },
         };
       });
     },
@@ -4818,6 +4926,38 @@ function attemptToolCodemodePath(serverId: string, toolName: string): readonly s
   return [serverId, toolName];
 }
 
+type PreparedMcpOperationRecovery = {
+  policy: NonNullable<Settings["mcpServers"][number]["operationRecovery"]>;
+  persistence: McpOperationPersistence;
+  destinationDigest: string;
+  supported: boolean;
+};
+
+const mcpOperationRecoveryByServer = new WeakMap<PrefixedMcpServer, PreparedMcpOperationRecovery>();
+
+function configureMcpOperationRecovery(
+  server: PrefixedMcpServer,
+  config: Settings["mcpServers"][number],
+  options: PrepareToolsOptions,
+  destinationUrl: string,
+  brokered: boolean,
+): PrefixedMcpServer {
+  if (config.operationRecovery && options.mcpOperationPersistence) {
+    mcpOperationRecoveryByServer.set(server, {
+      policy: McpOperationRecoverySchema.parse(config.operationRecovery),
+      persistence: options.mcpOperationPersistence,
+      destinationDigest: digestCanonicalJson(new URL(destinationUrl).toString()),
+      supported: brokered && attemptToolScope(options) !== null,
+    });
+  }
+  return server;
+}
+
+function configuredMcpOperationRecovery(server: PrefixedMcpServer, toolName: string) {
+  const recovery = mcpOperationRecoveryByServer.get(server);
+  return recovery && Object.hasOwn(recovery.policy, toolName) ? recovery : undefined;
+}
+
 function attemptToolSource(serverId: string): ToolGatewayDefinition["source"] {
   if (serverId === "opengeni" || serverId === "files" || serverId === "docs") {
     return serverId;
@@ -4889,6 +5029,35 @@ function connectionBrokerFetch(
         suppressSetupAuthNeeded,
       );
     }
+    if (request.method === "tools/call") {
+      assertMcpOperationObservationAuthority({
+        serverId: config.id,
+        ...(request.toolName === undefined ? {} : { toolName: request.toolName }),
+        destinationDigest: digestCanonicalJson(destinationUrl),
+        ...(first.operationAuthorityDigest === undefined
+          ? {}
+          : { authorityDigest: first.operationAuthorityDigest }),
+      });
+      if (
+        hasActiveRecoverableMcpOperation() &&
+        (request.batch ||
+          request.id === undefined ||
+          request.id === null ||
+          !request.operationId ||
+          !request.toolName)
+      ) {
+        throw new Error("Recoverable MCP request is missing its exact dispatch identity");
+      }
+      // The helper is a no-op without its private context. Always enter it for
+      // tools/call so a late transport continuation cannot bypass a closed context.
+      await captureMcpOperationDispatch({
+        operationId: request.operationId ?? "",
+        serverId: config.id,
+        toolName: request.toolName ?? "",
+        destinationDigest: digestCanonicalJson(destinationUrl),
+        authorityDigest: first.operationAuthorityDigest ?? "",
+      });
+    }
     const response = await baseFetch(
       fetchInputForAttempt(input),
       withConnectionHeaders(input, init, first.headers),
@@ -6387,9 +6556,11 @@ class AttemptDefinitionMcpServer implements MCPServer {
   ): Promise<any> {
     if (this.closed) throw new Error("local model tool server is closed");
     const environment = await this.requiredAttemptToolEnvironment();
+    const sourceCallId = modelMcpSourceCallId(toolName);
     return await this.resultCustomDataBridge.captureResult(args, async (cleanArgs) =>
       environment.callModel({
         modelName: toolName,
+        ...(sourceCallId === undefined ? {} : { sourceCallId }),
         arguments: cleanArgs ?? {},
         subjectId: this.subjectId,
         ...(meta === undefined ? {} : { transportMeta: meta }),
@@ -6711,8 +6882,10 @@ export class PrefixedMcpServer implements MCPServer {
     }
     return await this.resultCustomDataBridge.captureResult(args, async (cleanArgs) => {
       if (this.attemptToolEnvironment) {
+        const sourceCallId = modelMcpSourceCallId(toolName);
         return await this.attemptToolEnvironment.callModel({
           modelName: toolName,
+          ...(sourceCallId === undefined ? {} : { sourceCallId }),
           arguments: cleanArgs ?? {},
           subjectId: this.attemptToolSubjectId,
           ...(meta === undefined ? {} : { transportMeta: meta }),
@@ -6741,6 +6914,9 @@ export class PrefixedMcpServer implements MCPServer {
     if (!this.isAllowed(unprefixed)) {
       throw new Error(`MCP tool ${unprefixed} is not allowed for server ${this.registryId}`);
     }
+    if (configuredMcpOperationRecovery(this, unprefixed) && !hasActiveRecoverableMcpOperation()) {
+      throw new Error("MCP operation recovery requires its trusted attempt execution context");
+    }
     // Nested prefix wrappers are a projection seam around one physical
     // tools/call. The innermost wrapper owns the single metric observation.
     const recordsPhysicalCall = !(this.inner instanceof PrefixedMcpServer);
@@ -6814,6 +6990,16 @@ export class PrefixedMcpServer implements MCPServer {
       // state. The broker refreshed credentials for future requests but did not
       // replay this call. Preserve that ambiguity as an explicit model-visible
       // error for required and best-effort servers alike.
+      if (hasActiveRecoverableMcpOperation()) {
+        recordOutcome(
+          isToolOutcomeUncertainMcpError(error)
+            ? "outcome_uncertain"
+            : isAuthNeededMcpError(error)
+              ? "auth_needed"
+              : mcpThrownToolCallOutcome(error, options?.signal),
+        );
+        throw error;
+      }
       if (isToolOutcomeUncertainMcpError(error)) {
         recordOutcome("outcome_uncertain");
         return boundedMcpToolResult({

package/src/mcp-operation-dispatch.ts

@@ -0,0 +1,144 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { AttemptToolResult } from "@opengeni/contracts";
+
+export type RecoverableMcpOperation = {
+  operationId: string;
+  sourceCallId?: string;
+  serverId: string;
+  originalTool: string;
+  observerTool: string;
+  destinationDigest: string;
+  argumentDigest: string;
+};
+
+export type CapturedMcpOperation = RecoverableMcpOperation & { authorityDigest: string };
+
+/** Worker-owned persistence. Its implementation must enforce canonical live
+ * attempt identity and store no arguments, URLs, headers, or credentials. */
+export type McpOperationPersistence = {
+  capture: (operation: CapturedMcpOperation) => Promise<"created" | "existing">;
+  settleOriginal: (
+    input:
+      | { operationId: string; outcome: "completed"; result: AttemptToolResult }
+      | { operationId: string; outcome: "outcome_unknown" },
+  ) => Promise<void>;
+};
+
+type DispatchContext = {
+  operation: RecoverableMcpOperation;
+  persistence: McpOperationPersistence;
+  captureStarted: boolean;
+  captured: boolean;
+  closed: boolean;
+};
+
+const dispatchContext = new AsyncLocalStorage<DispatchContext>();
+
+/** Presence is an execution-routing fact, not authorization. A closed context
+ * remains visible to late callbacks so they still hit the dispatch fence. */
+export function hasActiveRecoverableMcpOperation(): boolean {
+  return dispatchContext.getStore() !== undefined;
+}
+
+export class McpOperationOutcomeUnknownError extends Error {
+  readonly code = "mcp_operation_outcome_unknown";
+  constructor(
+    readonly operationId: string,
+    cause: unknown,
+  ) {
+    super(
+      `MCP operation ${operationId} has an unknown outcome. Read the existing operation result; do not repeat the mutation.`,
+      { cause },
+    );
+    this.name = "McpOperationOutcomeUnknownError";
+  }
+}
+
+/** Establish trusted in-process correlation around one gateway execution. */
+export async function runRecoverableMcpOperation(
+  operation: RecoverableMcpOperation,
+  persistence: McpOperationPersistence,
+  execute: () => Promise<AttemptToolResult>,
+): Promise<AttemptToolResult> {
+  const context: DispatchContext = {
+    operation: { ...operation },
+    persistence,
+    captureStarted: false,
+    captured: false,
+    closed: false,
+  };
+  return await dispatchContext.run(context, async () => {
+    let result: AttemptToolResult;
+    try {
+      try {
+        result = await execute();
+      } catch (error) {
+        if (!context.captured) throw error;
+        // An uncertain settlement acknowledgment cannot authorize replay or
+        // replace the original recovery handle with a database-only error.
+        try {
+          await persistence.settleOriginal({
+            operationId: operation.operationId,
+            outcome: "outcome_unknown",
+          });
+        } catch {
+          /* The pre-dispatch record remains the recovery authority. */
+        }
+        throw new McpOperationOutcomeUnknownError(operation.operationId, error);
+      }
+      if (!context.captured) {
+        throw new Error("Recoverable MCP execution did not cross its durable capture boundary");
+      }
+      try {
+        await persistence.settleOriginal({
+          operationId: operation.operationId,
+          outcome: "completed",
+          result,
+        });
+      } catch (error) {
+        // Never submit a second, contradictory settlement after an ambiguous
+        // acknowledgment of the successful one.
+        throw new McpOperationOutcomeUnknownError(operation.operationId, error);
+      }
+      return result;
+    } finally {
+      context.closed = true;
+    }
+  });
+}
+
+/** Called by the authorized broker immediately before the physical request.
+ * A second dispatch with the same identity is never an observation. */
+export async function captureMcpOperationDispatch(input: {
+  operationId: string;
+  serverId: string;
+  toolName: string;
+  destinationDigest: string;
+  authorityDigest: string;
+}): Promise<void> {
+  const context = dispatchContext.getStore();
+  if (!context) return;
+  const operation = context.operation;
+  if (
+    input.operationId !== operation.operationId ||
+    input.serverId !== operation.serverId ||
+    input.toolName !== operation.originalTool ||
+    input.destinationDigest !== operation.destinationDigest ||
+    !/^[a-f0-9]{64}$/u.test(input.authorityDigest)
+  )
+    throw new Error("Recoverable MCP dispatch identity does not match its trusted binding");
+  if (context.closed || context.captureStarted) {
+    throw new Error("MCP operation dispatch is already claimed or closed");
+  }
+  context.captureStarted = true;
+  const result = await context.persistence.capture({
+    ...operation,
+    authorityDigest: input.authorityDigest,
+  });
+  if (result !== "created")
+    throw new Error("MCP operation was already dispatched; read its existing result");
+  // The SDK may have timed out while capture was committing. Do not start a
+  // mutation after its enclosing execution has already returned.
+  if (context.closed) throw new Error("MCP operation dispatch closed during capture");
+  context.captured = true;
+}

package/src/mcp-operation-observation.ts

@@ -0,0 +1,148 @@
+import { AttemptToolResult } from "@opengeni/contracts";
+import { z } from "zod";
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export type McpOperationObservationAuthority = {
+  serverId: string;
+  observerTool: string;
+  destinationDigest: string;
+  authorityDigest: string;
+};
+const observationAuthority = new AsyncLocalStorage<{
+  binding: McpOperationObservationAuthority;
+  closed: boolean;
+}>();
+
+/** Pin the actual broker request, not merely the earlier credential lookup. */
+export async function runMcpOperationObservationWithAuthority<T>(
+  binding: McpOperationObservationAuthority,
+  execute: () => Promise<T>,
+): Promise<T> {
+  const scope = { binding: { ...binding }, closed: false };
+  return await observationAuthority.run(scope, async () => {
+    try {
+      return await execute();
+    } finally {
+      scope.closed = true;
+    }
+  });
+}
+
+/** The caller is the credential broker, after live authorization and before
+ * physical tools/call dispatch. Unrelated ordinary calls remain unchanged. */
+export function assertMcpOperationObservationAuthority(actual: {
+  serverId: string;
+  toolName?: string;
+  destinationDigest: string;
+  authorityDigest?: string;
+}): void {
+  const scope = observationAuthority.getStore();
+  if (!scope) return;
+  const expected = scope.binding;
+  if (
+    scope.closed ||
+    actual.serverId !== expected.serverId ||
+    actual.toolName !== expected.observerTool ||
+    actual.destinationDigest !== expected.destinationDigest ||
+    actual.authorityDigest !== expected.authorityDigest
+  ) {
+    throw new Error("MCP operation observation authority changed before provider use");
+  }
+}
+
+const fingerprint = z
+  .object({
+    version: z.literal(1),
+    algorithm: z.literal("sha256"),
+    value: z.string().regex(/^[a-f0-9]{64}$/u),
+  })
+  .strict();
+
+const identity = {
+  version: z.literal(1),
+  operationRef: z.string().uuid(),
+  fingerprint,
+};
+
+const receiptSchema = z.discriminatedUnion("status", [
+  z.object({ ...identity, status: z.literal("unknown") }).strict(),
+  z
+    .object({
+      ...identity,
+      status: z.literal("pending"),
+      evidenceRevision: z.string().min(1),
+    })
+    .strict(),
+  z
+    .object({
+      ...identity,
+      status: z.literal("completed"),
+      receiptRevision: z
+        .string()
+        .min(1)
+        .refine((value) => Buffer.byteLength(value, "utf8") <= 1024, {
+          message: "MCP receipt revision must fit the ledger's 1024-byte identity field",
+        }),
+      result: AttemptToolResult,
+    })
+    .strict(),
+  z.object({ ...identity, status: z.literal("conflict") }).strict(),
+]);
+
+const bindingSchema = z
+  .object({
+    operationId: z.string().uuid(),
+    serverId: z.string().min(1),
+    originalTool: z.string().min(1),
+    observerTool: z.string().min(1),
+    argumentDigest: fingerprint.shape.value,
+  })
+  .strict()
+  .refine((value) => value.originalTool !== value.observerTool, {
+    message: "The observer must not be the original mutation tool",
+  });
+
+export type McpObservationBinding = z.infer<typeof bindingSchema>;
+export type McpObservationReceipt = z.infer<typeof receiptSchema>;
+
+/**
+ * One observation, never a mutation retry. This helper is deliberately not an
+ * authority resolver or a scheduler: its caller must load an immutable trusted
+ * binding and bind callObserver to that exact authorized provider destination.
+ * Tool annotations and model-supplied arguments cannot establish that trust.
+ *
+ * Durable settlement must additionally recheck authority under its own locks.
+ * A successful return alone is not a durable delivery or commit receipt.
+ */
+export async function observeMcpOperation(input: {
+  binding: McpObservationBinding;
+  authorize: (phase: "before_request" | "before_delivery") => Promise<boolean>;
+  callObserver: (tool: string, args: Record<string, unknown>) => Promise<unknown>;
+}): Promise<McpObservationReceipt> {
+  // Parse into a fresh object before callbacks can mutate the caller's input.
+  const binding = bindingSchema.parse(input.binding);
+  if (!(await input.authorize("before_request"))) {
+    throw new Error("MCP operation observation is not authorized");
+  }
+  const response = await input.callObserver(binding.observerTool, {
+    version: 1,
+    operationRef: binding.operationId,
+    originalTool: binding.originalTool,
+    fingerprint: { version: 1, algorithm: "sha256", value: binding.argumentDigest },
+  });
+  if (!(await input.authorize("before_delivery"))) {
+    throw new Error("MCP operation observation is not authorized for delivery");
+  }
+  const envelope = AttemptToolResult.parse(response);
+  if (envelope.isError) {
+    throw new Error("MCP operation observer returned an error, not a receipt");
+  }
+  const receipt = receiptSchema.parse(envelope.structuredContent);
+  if (
+    receipt.operationRef !== binding.operationId ||
+    receipt.fingerprint.value !== binding.argumentDigest
+  ) {
+    throw new Error("MCP operation observation receipt identity does not match");
+  }
+  return receipt;
+}