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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/worker-bundle",
-  "version": "0.28.3-canary.0",
+  "version": "0.28.4-canary.0",
   "description": "OpenGeni worker entry and reusable embedded lifecycle, shipped with a release-coherent pre-bundled Temporal workflow artifact.",
   "license": "Apache-2.0",
   "repository": {
@@ -54,22 +54,23 @@
   },
   "dependencies": {
     "@llamaindex/liteparse": "2.14.2",
-    "@opengeni/agent-proto": "^0.5.1-canary.25",
-    "@opengeni/capabilities": "^0.3.3-canary.7",
-    "@opengeni/codemode": "^0.5.5-canary.0",
-    "@opengeni/codex": "^0.2.22-canary.7",
-    "@opengeni/config": "^1.1.1-canary.0",
-    "@opengeni/contracts": "^3.0.1-canary.0",
-    "@opengeni/core": "^2.9.3-canary.0",
-    "@opengeni/db": "^4.3.2-canary.0",
-    "@opengeni/documents": "^0.8.26-canary.0",
-    "@opengeni/events": "^0.4.24-canary.0",
-    "@opengeni/github": "^0.7.9-canary.0",
-    "@opengeni/network": "^0.3.1-canary.7",
-    "@opengeni/observability": "^0.8.25-canary.0",
-    "@opengeni/runtime": "^2.5.2-canary.0",
-    "@opengeni/storage": "^0.2.126-canary.0",
-    "@opengeni/xai-subscription": "^0.1.4-canary.7",
+    "@opengeni/agent-proto": "^0.5.1-canary.26",
+    "@opengeni/capabilities": "^0.3.3-canary.8",
+    "@opengeni/codemode": "^0.5.6-canary.0",
+    "@opengeni/codex": "^0.2.22-canary.8",
+    "@opengeni/config": "^1.1.2-canary.0",
+    "@opengeni/contracts": "^3.0.2-canary.0",
+    "@opengeni/core": "^2.9.4-canary.0",
+    "@opengeni/db": "^4.3.3-canary.0",
+    "@opengeni/documents": "^0.8.27-canary.0",
+    "@opengeni/events": "^0.4.25-canary.0",
+    "@opengeni/github": "^0.7.10-canary.0",
+    "@opengeni/network": "^0.3.1-canary.8",
+    "@opengeni/observability": "^0.8.26-canary.0",
+    "@opengeni/runtime": "^2.5.3-canary.0",
+    "@opengeni/storage": "^0.2.127-canary.0",
+    "@opengeni/tool-gateway": "^0.1.7-canary.0",
+    "@opengeni/xai-subscription": "^0.1.4-canary.8",
     "@temporalio/activity": "^1.17.0",
     "@temporalio/client": "^1.17.0",
     "@temporalio/worker": "^1.17.0",

package/src/activities/agent-turn/mcp-operation-read-tool.ts

@@ -0,0 +1,61 @@
+import type { AttemptToolDefinition } from "@opengeni/codemode";
+import { AttemptToolResult } from "@opengeni/contracts";
+import { z } from "zod";
+
+const selectorSchema = z.union([
+  z.object({ operationId: z.string().uuid() }).strict(),
+  z.object({ sourceTurnId: z.string().uuid(), sourceCallId: z.string().min(1) }).strict(),
+]);
+
+export type McpOperationReadSelector = z.infer<typeof selectorSchema>;
+
+/** Attempt-local adapter. The supplied read closure owns canonical session
+ * access, current provider authority, immutable binding checks and settlement.
+ * No caller-controlled provider parameters cross this tool boundary. */
+export function createOperationReadAttemptToolDefinition(input: {
+  read: (selector: McpOperationReadSelector) => Promise<Record<string, unknown>>;
+}): AttemptToolDefinition {
+  return {
+    identity: { serverId: "opengeni", toolName: "operation_read" },
+    modelName: "operation_read",
+    codemodePath: ["opengeni", "operation_read"],
+    title: "Read an existing MCP operation outcome",
+    description:
+      "Read a retained MCP operation and, when supported and currently authorized, observe its provider receipt. " +
+      "Use the operationId from the original call, or its exact sourceTurnId and sourceCallId if that response was lost. " +
+      "This never repeats the original mutation. Unknown means the outcome is not proven, not that the operation failed. " +
+      "Provider support and renewed authorization may be required after reconnecting.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        operationId: { type: "string", format: "uuid" },
+        sourceTurnId: { type: "string", format: "uuid" },
+        sourceCallId: { type: "string", minLength: 1 },
+      },
+      additionalProperties: false,
+      oneOf: [
+        {
+          required: ["operationId"],
+          not: { anyOf: [{ required: ["sourceTurnId"] }, { required: ["sourceCallId"] }] },
+        },
+        { required: ["sourceTurnId", "sourceCallId"], not: { required: ["operationId"] } },
+      ],
+    },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
+    source: "opengeni",
+    approval: "none",
+    execute: async (args) => {
+      const selector = selectorSchema.parse(args);
+      const receipt = await input.read(selector);
+      return AttemptToolResult.parse({
+        content: [{ type: "text", text: JSON.stringify(receipt) }],
+        structuredContent: receipt,
+      });
+    },
+  };
+}

package/src/activities/agent-turn/tool-environment.ts

@@ -37,6 +37,11 @@ import {
   resolveGoogleDrivePublicationTarget,
 } from "../google-drive-publication";
 import { connectionTokenResolverForTurn } from "../mcp-credentials";
+import { createMcpOperationPersistence } from "@opengeni/db/mcp-operations";
+import { createMcpOperationReadStore } from "../mcp-operation-store";
+import { createMcpOperationObserverResolver } from "../mcp-operation-observer";
+import { readMcpOperation } from "../mcp-operation-reader";
+import { createOperationReadAttemptToolDefinition } from "./mcp-operation-read-tool";
 import { buildGitHubRestMcpForTurn } from "../../github-rest-mcp";
 import { materializeConnectorAttachmentsInChannel } from "../connector-attachments";
 import { allowedFirstPartyMcpToolsForSession, type Settings } from "@opengeni/config";
@@ -668,7 +673,66 @@ export async function prepareTurnToolRuntime(deps: PrepareTurnToolRuntimeDeps) {
       });
     },
   });
+  const operationRecoveryEnabled = githubRestMcp.settings.mcpServers.some(
+    (server) =>
+      server.operationRecovery &&
+      Object.keys(server.operationRecovery).length > 0 &&
+      githubRestMcp.tools.some((tool) => tool.kind === "mcp" && tool.id === server.id),
+  );
+  const operationAttempt = {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    sessionId: input.sessionId,
+    turnId: turn.id,
+    attemptId: input.attemptId,
+    executionGeneration: attempt.executionGeneration,
+  };
+  const operationPersistence = operationRecoveryEnabled
+    ? createMcpOperationPersistence(db, operationAttempt)
+    : undefined;
+  const operationReadStore = operationRecoveryEnabled
+    ? createMcpOperationReadStore(db, operationAttempt)
+    : undefined;
+  const operationObserver = createMcpOperationObserverResolver({
+    settings: githubRestMcp.settings,
+    workspaceId: input.workspaceId,
+    ...(credentialSubjectId ? { credentialSubjectId } : {}),
+    resolveCredential,
+    assertAttempt: async () => {
+      throwIfWorkerShuttingDown();
+      throwIfTurnCancelled();
+      const current = await getSessionTurnForAttempt(
+        db,
+        input.workspaceId,
+        input.sessionId,
+        input.attemptId,
+      );
+      if (
+        !current ||
+        current.id !== turn.id ||
+        current.executionGeneration !== attempt.executionGeneration
+      ) {
+        throw new Error("MCP operation reader no longer owns the executing attempt");
+      }
+    },
+    getEnvironment: async () => {
+      const prepared = eventing.preparedTools;
+      if (!prepared) return null;
+      return ((await prepared.ready) ?? prepared).attemptToolEnvironment;
+    },
+  });
   const attemptToolDefinitions = [
+    ...(operationReadStore
+      ? [
+          createOperationReadAttemptToolDefinition({
+            read: async (selector) =>
+              await readMcpOperation(selector, {
+                ...operationReadStore,
+                resolveObserver: operationObserver,
+              }),
+          }),
+        ]
+      : []),
     ...skillTools,
     createListModelsAttemptToolDefinition({
       currentModelId: turnExecutionPolicy.productModelId,
@@ -876,6 +940,7 @@ export async function prepareTurnToolRuntime(deps: PrepareTurnToolRuntimeDeps) {
         ...(credentialSubjectId ? { credentialSubjectId } : {}),
         ...(codexAppsAuth ? { codexAppsAuth } : {}),
         resolveCredential,
+        ...(operationPersistence ? { mcpOperationPersistence: operationPersistence } : {}),
         ...(linkedAuthority
           ? {
               authorizeAttemptExecution: async () => {

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" },
+  };
+}