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

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

package/src/activities/sandbox-lease.ts

@@ -82,7 +82,10 @@ import {
   // box is typed as provider loss. Stale capture reconciliation separately uses
   // establishSandboxSessionFromEnvelope in strict resume-only mode so it can
   // reuse the runtime's provider-ready proof without ever cold-restoring.
-  captureVerifiedWorkspaceArchive,
+  captureWorkspaceArchiveForStorage,
+  disposeWorkspaceArchive,
+  type VerifiedWorkspaceArchivePayload,
+  type VerifiedHostWorkspaceArchive,
   cancelSelfhostedOp,
   assertConsistentSandboxProviderIdentity,
   createSandboxClientForBackend,
@@ -160,9 +163,7 @@ import {
 } from "../opensandbox-kubernetes-inventory";
 import type { ObjectStorage } from "@opengeni/storage";
 import {
-  collectWorkspaceArchiveObjectKeys,
-  deleteUnpublishedWorkspaceArchiveObject,
-  deleteWorkspaceArchiveObjectKeys,
+  persistWorkspaceArchiveCandidate,
   putVersion1TarArchiveOrInline,
 } from "../sandbox-archive-storage";
 
@@ -210,7 +211,7 @@ type DrainSandboxClient = {
  * aborts the terminate before client.delete()).
  */
 export type PersistArchiveFn = (
-  archiveBase64: string | null,
+  archiveBase64: string | VerifiedHostWorkspaceArchive | null,
   archiveMetadata?: WorkspaceArchiveDescriptor,
   providerSession?: unknown,
   providerBinding?: Awaited<
@@ -247,6 +248,7 @@ export type TerminateBoxFn = (
   providerCaptureRequestId?: string,
   captureDisposition?: DrainCaptureDisposition,
   capturePolicy?: ProviderWorkspaceCapturePolicy | null,
+  diskBackedArchives?: boolean,
 ) => Promise<boolean | ProviderTerminationOutcome>;
 
 export type SweepModalOrphansFn = (
@@ -479,6 +481,7 @@ export function createSandboxLeaseActivities(
       providerCaptureRequestId,
       captureDisposition,
       capturePolicy,
+      diskBackedArchives,
     ) =>
       await terminateProviderBox(
         settings,
@@ -490,6 +493,7 @@ export function createSandboxLeaseActivities(
         providerCaptureRequestId,
         captureDisposition,
         capturePolicy,
+        diskBackedArchives,
       ));
   const sweepModalOrphans: SweepModalOrphansFn =
     options.sweepModalOrphans ?? sweepModalOrphansForConfiguredBackend;
@@ -2675,7 +2679,7 @@ async function terminateDrainableBox(
       ? (lease.recovery.archive.current?.revision ?? null)
       : null;
   const persistArchive: PersistArchiveFn = async (
-    archiveBase64: string | null,
+    archiveBase64: string | VerifiedHostWorkspaceArchive | null,
     archiveMetadata?: WorkspaceArchiveDescriptor,
     _providerSession?: unknown,
     providerBinding?: Awaited<
@@ -2691,6 +2695,7 @@ async function terminateDrainableBox(
     const archiveMetrics = runtimeMetricsHooksForObservability(observability);
     let checkpointArtifactId: string | null = null;
     if (
+      typeof archiveBase64 === "string" &&
       archiveBase64 &&
       archiveMetadata?.version === 2 &&
       (archiveMetadata.provider === "modal_snapshot_filesystem" ||
@@ -2735,59 +2740,33 @@ async function terminateDrainableBox(
       if (!archiveMetadata) {
         throw new Error("Sandbox snapshot publication requires a verified archive descriptor");
       }
-      const priorKeys = collectWorkspaceArchiveObjectKeys(
-        (lease.resumeState as Record<string, unknown> | null | undefined) ?? null,
-      );
-      let workspaceArchiveRef:
-        | Awaited<ReturnType<typeof putVersion1TarArchiveOrInline>>["workspaceArchiveRef"]
-        | undefined;
-      try {
-        const published = await putVersion1TarArchiveOrInline({
-          backend: lease.backend,
-          objectStorage,
-          accountId,
-          workspaceId: row.workspaceId,
-          sandboxGroupId: row.sandboxGroupId,
-          archive: {
-            bytes: Buffer.from(archiveBase64, "base64"),
-            descriptor: archiveMetadata,
-            base64: archiveBase64,
-          },
-          metrics: archiveMetrics,
-        });
-        workspaceArchiveRef = published.workspaceArchiveRef;
-        result = await persistDrainSnapshot(db, {
-          ...baseInput,
-          workspaceArchiveMeta: archiveMetadata,
-          ...published,
-          ...(checkpointArtifactId ? { checkpointArtifactId } : {}),
-        });
-        if (published.workspaceArchiveRef && objectStorage) {
-          if (!result.wrote) {
-            await deleteUnpublishedWorkspaceArchiveObject(
-              objectStorage,
-              published.workspaceArchiveRef,
-              archiveMetrics,
-            );
-          } else {
-            const afterLease = await readLease(db, row.workspaceId, row.sandboxGroupId);
-            const afterKeys = collectWorkspaceArchiveObjectKeys(
-              (afterLease?.resumeState as Record<string, unknown> | null | undefined) ?? null,
-            );
-            await deleteWorkspaceArchiveObjectKeys(
-              objectStorage,
-              [...priorKeys].filter((key) => !afterKeys.has(key)),
-            ).catch(() => undefined);
-          }
-        }
-      } catch (error) {
-        await deleteUnpublishedWorkspaceArchiveObject(
-          objectStorage,
-          workspaceArchiveRef,
-          archiveMetrics,
-        );
-        throw error;
-      }
+      const published = await putVersion1TarArchiveOrInline({
+        backend: lease.backend,
+        objectStorage,
+        accountId,
+        workspaceId: row.workspaceId,
+        sandboxGroupId: row.sandboxGroupId,
+        archive:
+          typeof archiveBase64 === "object"
+            ? archiveBase64
+            : {
+                bytes: Buffer.from(archiveBase64, "base64"),
+                descriptor: archiveMetadata,
+                base64: archiveBase64,
+              },
+        metrics: archiveMetrics,
+      });
+      result = await persistWorkspaceArchiveCandidate({
+        objectStorage,
+        ...(published.workspaceArchiveRef ? { ref: published.workspaceArchiveRef } : {}),
+        persist: () =>
+          persistDrainSnapshot(db, {
+            ...baseInput,
+            workspaceArchiveMeta: archiveMetadata,
+            ...published,
+            ...(checkpointArtifactId ? { checkpointArtifactId } : {}),
+          }),
+      });
     }
     if (!result.wrote && checkpointArtifactId) {
       await markSandboxCheckpointArtifactDeletePending(db, {
@@ -2823,6 +2802,7 @@ async function terminateDrainableBox(
         captureClaim?.providerRequestId ?? attempt.operationId,
         captureDisposition,
         capturePolicy,
+        Boolean(objectStorage),
       );
   const terminated = typeof termination === "boolean" ? termination : termination.terminated;
   if (!terminated) {
@@ -2955,6 +2935,7 @@ export async function terminateProviderBox(
   providerCaptureRequestId?: string,
   captureDisposition: DrainCaptureDisposition = "capture_required",
   claimedCapturePolicy?: ProviderWorkspaceCapturePolicy | null,
+  diskBackedArchives = false,
 ): Promise<ProviderTerminationOutcome> {
   const durableBackendId = (lease.resumeBackendId ?? lease.backend) as string;
   const backend = sandboxBackendForSdkBackendId(durableBackendId) ?? durableBackendId;
@@ -3147,7 +3128,7 @@ export async function terminateProviderBox(
   // snapshot must re-throw BEFORE any terminate so files are never lost — the next
   // sweep retries, the provider idle-timeout is the backstop. A NotFound here (the
   // box raced gone between resume and persist) is success: nothing to persist.
-  let verifiedArchive: Awaited<ReturnType<typeof captureVerifiedWorkspaceArchive>> | undefined;
+  let verifiedArchive: VerifiedWorkspaceArchivePayload | undefined;
   const sessionWorkspacePersistence = (
     session as { state?: { workspacePersistence?: unknown } } | undefined
   )?.state?.workspacePersistence;
@@ -3162,10 +3143,15 @@ export async function terminateProviderBox(
       : null;
   try {
     if (captureDisposition !== "archive_published" && session?.persistWorkspace) {
-      const capture = captureVerifiedWorkspaceArchive(session, Date.now(), {
-        requestId: providerCaptureRequestId ?? randomUUID(),
-        strategy: liveCapturePolicy.strategy,
-      });
+      const capture = captureWorkspaceArchiveForStorage(
+        session,
+        Date.now(),
+        {
+          requestId: providerCaptureRequestId ?? randomUUID(),
+          strategy: liveCapturePolicy.strategy,
+        },
+        diskBackedArchives,
+      );
       verifiedArchive = await awaitProviderCaptureWithLatePublication({
         capture,
         timeoutMs: settings.sandboxSnapshotTimeoutMs,
@@ -3179,7 +3165,7 @@ export async function terminateProviderBox(
         publishLate: async (archive) => {
           try {
             const result = await persistArchive(
-              archive.base64,
+              archive.kind === "host_spool" ? archive : archive.base64,
               archive.descriptor,
               session,
               checkpointBinding,
@@ -3197,6 +3183,8 @@ export async function terminateProviderBox(
               ...logIdentity,
               error: error instanceof Error ? error.message : String(error),
             });
+          } finally {
+            await disposeWorkspaceArchive(archive);
           }
         },
         observeLateFailure: (error) => {
@@ -3237,12 +3225,17 @@ export async function terminateProviderBox(
       ...logIdentity,
     });
   } else if (verifiedArchive) {
-    const { wrote } = await persistArchive(
-      verifiedArchive.base64,
-      verifiedArchive.descriptor,
-      session,
-      checkpointBinding,
-    );
+    let wrote: boolean;
+    try {
+      ({ wrote } = await persistArchive(
+        verifiedArchive.kind === "host_spool" ? verifiedArchive : verifiedArchive.base64,
+        verifiedArchive.descriptor,
+        session,
+        checkpointBinding,
+      ));
+    } finally {
+      await disposeWorkspaceArchive(verifiedArchive);
+    }
     if (!wrote) {
       observability.info(
         "sandbox reaper: lease re-armed during persist — leaving box RUNNING (no terminate)",

package/src/observability-metrics.ts

@@ -413,7 +413,7 @@ export function recordWorkerDeathRecoveryMetrics(
 }
 
 export class TurnLifecycleMetrics {
-  private readonly turns = new Map<string, { startedAt: number; lastProgressAt: number }>();
+  private readonly attempts = new Map<string, { startedAt: number; lastProgressAt: number }>();
   private timer: ReturnType<typeof setInterval> | null = null;
 
   constructor(
@@ -424,42 +424,46 @@ export class TurnLifecycleMetrics {
     } = {},
   ) {}
 
-  start(turnId: string): void {
+  start(input: { attemptId: string }): void {
     const now = this.now();
-    this.turns.set(turnId, { startedAt: now, lastProgressAt: now });
+    this.attempts.set(input.attemptId, { startedAt: now, lastProgressAt: now });
     this.ensureTimer();
     this.refreshGauges();
   }
 
-  progress(turnId: string): void {
-    const turn = this.turns.get(turnId);
-    if (!turn) return;
-    turn.lastProgressAt = this.now();
+  progress(input: { attemptId: string }): void {
+    const attempt = this.attempts.get(input.attemptId);
+    if (!attempt) return;
+    attempt.lastProgressAt = this.now();
   }
 
-  finish(turnId: string, outcome: TurnOutcome | null, durationSeconds?: number): void {
-    const startedAt = this.turns.get(turnId)?.startedAt;
+  finish(input: {
+    attemptId: string;
+    outcome: TurnOutcome | null;
+    durationSeconds?: number;
+  }): void {
+    const startedAt = this.attempts.get(input.attemptId)?.startedAt;
     if (startedAt !== undefined) {
-      this.turns.delete(turnId);
+      this.attempts.delete(input.attemptId);
     }
-    if (outcome) {
+    if (input.outcome) {
       const observedDuration =
-        durationSeconds ??
+        input.durationSeconds ??
         (startedAt === undefined ? 0 : Math.max(0, (this.now() - startedAt) / 1000));
       this.observability.incrementCounter({
         name: "opengeni_turns_total",
         help: "Total agent turns by terminal outcome.",
-        labels: { outcome },
+        labels: { outcome: input.outcome },
       });
       this.observability.observeHistogram({
         name: "opengeni_turn_duration_seconds",
         help: "Agent turn duration in seconds by terminal outcome.",
-        labels: { outcome },
+        labels: { outcome: input.outcome },
         value: observedDuration,
       });
     }
     this.refreshGauges();
-    if (this.turns.size === 0) {
+    if (this.attempts.size === 0) {
       this.stopTimer();
     }
   }
@@ -467,42 +471,42 @@ export class TurnLifecycleMetrics {
   refreshGauges(): void {
     this.observability.setGauge({
       name: "opengeni_turns_inflight",
-      help: "Current number of in-flight agent turns in this worker process.",
-      value: this.turns.size,
+      help: "Current number of in-flight physical agent-turn attempts in this worker process.",
+      value: this.attempts.size,
     });
     this.observability.setGauge({
       name: "opengeni_turn_oldest_inflight_age_seconds",
-      help: "Age in seconds of the oldest in-flight agent turn in this worker process.",
+      help: "Age in seconds of the oldest in-flight physical agent-turn attempt in this worker process.",
       value: this.oldestInflightAgeSeconds(),
     });
     this.observability.setGauge({
       name: "opengeni_turn_oldest_no_progress_age_seconds",
-      help: "Seconds since durable progress for the least recently progressing in-flight turn.",
+      help: "Seconds since durable progress for the least recently progressing in-flight physical agent-turn attempt.",
       value: this.oldestNoProgressAgeSeconds(),
     });
   }
 
   stop(): void {
-    this.turns.clear();
+    this.attempts.clear();
     this.refreshGauges();
     this.stopTimer();
   }
 
   private oldestInflightAgeSeconds(): number {
-    if (this.turns.size === 0) {
+    if (this.attempts.size === 0) {
       return 0;
     }
     let oldest = Number.POSITIVE_INFINITY;
-    for (const { startedAt } of this.turns.values()) {
+    for (const { startedAt } of this.attempts.values()) {
       oldest = Math.min(oldest, startedAt);
     }
     return Math.max(0, (this.now() - oldest) / 1000);
   }
 
   private oldestNoProgressAgeSeconds(): number {
-    if (this.turns.size === 0) return 0;
+    if (this.attempts.size === 0) return 0;
     let leastRecentProgress = Number.POSITIVE_INFINITY;
-    for (const { lastProgressAt } of this.turns.values()) {
+    for (const { lastProgressAt } of this.attempts.values()) {
       leastRecentProgress = Math.min(leastRecentProgress, lastProgressAt);
     }
     return Math.max(0, (this.now() - leastRecentProgress) / 1000);