@mono-agent/agent-runtime 0.20.14 → 0.21.0

package/src/ai/providers/pi-native/turn-runner.js

@@ -78,6 +78,8 @@ export async function buildTurnTools(runState, {
     ? null
     : createWebToolController({
       searchConfig: options.webSearchConfig,
+      searchState: options.webSearchState,
+      coordinator: options.webRequestCoordinator,
       fetchConfig: options.webFetchConfig,
       sandboxPolicy: options.sandboxPolicy,
       sandboxEngine,
@@ -121,6 +123,7 @@ export async function buildTurnTools(runState, {
       nodeReplController,
       webController,
       processJobsController: options.processJobs,
+      processJobsAvailability: options.processJobsAvailability,
       monitorsController: options.monitors,
       toolExecutionMode,
       subagents: options.subagents,
@@ -143,6 +146,9 @@ export async function buildTurnTools(runState, {
         skills: options.skills,
         skillsRoot: options.skillsRoot,
         toolEnvironment: options.toolEnvironment,
+        webSearchConfig: options.webSearchConfig,
+        webRequestCoordinator: options.webRequestCoordinator,
+        webFetchConfig: options.webFetchConfig,
       },
       ctx: runCtx,
     }));
@@ -163,6 +169,7 @@ export async function buildTurnTools(runState, {
       qaOutputDir,
       onTruncate,
       limits: toolLimits,
+      mcpCallNoTotalTimeoutTools: options.mcpCallNoTotalTimeoutTools,
       toolPayloadMaxBytes: toolLimits.toolPayloadMaxBytes,
       sandboxPolicy: options.sandboxPolicy,
       sandboxEngine,
@@ -275,6 +282,8 @@ export async function buildTurnHarness(runState, {
     streamOptions: { transport, maxRetries, maxRetryDelayMs },
     steeringMode,
     followUpMode: steeringMode,
+    promptCacheDiagnostics: options.promptCacheDiagnostics,
+    onEvent: options.onEvent,
   });
   // MCP `CallToolResult.isError` is a successful protocol response, so pi's
   // execute() promise resolves. The bridge records that bit in result details;
@@ -343,10 +352,10 @@ export function activateTurnHarness(runState, {
  * the harness mid-run; the consumer is tied to run completion (an internal
  * runComplete flag) so it stops steering once the run finishes and does not
  * swallow a follow-up meant for a later turn. Returns a `stop()` teardown.
- * @param {{harness: any, options: any, onEvent: (event: any) => void}} deps
+ * @param {{harness: any, options: any, onEvent: (event: any) => void, promptEpoch?: any}} deps
  * @returns {{stop: () => Promise<void>}}
  */
-export function startLiveInput({ harness, options, onEvent }) {
+export function startLiveInput({ harness, options, onEvent, promptEpoch }) {
   if (!options.liveInput) return { stop: async () => {} };
   const iterator = typeof options.liveInput[Symbol.asyncIterator] === "function"
     ? options.liveInput[Symbol.asyncIterator]()
@@ -355,6 +364,8 @@ export function startLiveInput({ harness, options, onEvent }) {
   /** @type {() => void} */
   let signalStop = () => {};
   const stopped = new Promise((resolve) => { signalStop = () => resolve(); });
+  /** @type {Array<{entryId: string, message: any}>} */
+  const acceptedEntries = [];
   const task = (async () => {
     try {
       while (!runComplete && !options.abortSignal?.aborted) {
@@ -364,8 +375,19 @@ export function startLiveInput({ harness, options, onEvent }) {
         ]);
         if (next.done || runComplete || options.abortSignal?.aborted) break;
         try {
-          await harness.steer(formatLiveInputGuidance(next.value.body, options.prompts));
-          next.value.acknowledge?.();
+          const entryId = await harness.steer(formatLiveInputGuidance(next.value.body, options.prompts));
+          if (typeof entryId !== "string" || entryId.length === 0) {
+            next.value.accepted?.();
+            next.value.uncertain?.({ reason: "delivery_uncertain" });
+            continue;
+          }
+          const evidence = {
+            providerEntryId: entryId,
+            ...(promptEpoch?.ownedRunId() === undefined ? {} : { providerRunId: promptEpoch.ownedRunId() }),
+          };
+          acceptedEntries.push({ entryId, message: next.value });
+          next.value.accepted?.(evidence);
+          promptEpoch?.register(entryId, next.value);
         } catch (err) {
           next.value.reject?.(err);
           throw err;
@@ -379,6 +401,8 @@ export function startLiveInput({ harness, options, onEvent }) {
       });
     }
   })();
+  /** @type {Promise<void>|undefined} */
+  let stopPromise;
   return {
     // The run is done: stop the live-steering consumer so it cannot steer a
     // finished harness or swallow a follow-up meant for the next turn. We signal
@@ -386,15 +410,214 @@ export function startLiveInput({ harness, options, onEvent }) {
     // race releases the task even when a third-party iterator's return() does
     // not unblock its pending next(); awaiting the task still closes any steer
     // acknowledgement already in progress.
-    stop: async () => {
+    stop: () => {
+      stopPromise ??= performStop();
+      return stopPromise;
+    },
+  };
+
+  async function performStop() {
       runComplete = true;
       signalStop();
       if (iterator && typeof iterator.return === "function") {
         try { void Promise.resolve(iterator.return()).catch(() => {}); } catch { /* best-effort */ }
       }
       await task;
+      for (const accepted of acceptedEntries) {
+        if (promptEpoch?.isConsumed(accepted.entryId)) continue;
+        try {
+          if (typeof harness.cancelQueued !== "function") {
+            accepted.message.uncertain?.({
+              reason: "delivery_uncertain",
+              providerEntryId: accepted.entryId,
+              ...(promptEpoch?.ownedRunId() === undefined ? {} : { providerRunId: promptEpoch.ownedRunId() }),
+            });
+            continue;
+          }
+          const cancellation = await harness.cancelQueued(accepted.entryId);
+          if (cancellation?.kind === "cancelled") {
+            accepted.message.reject?.({ code: "native_queue_removed" });
+          } else if (!promptEpoch?.isConsumed(accepted.entryId)) {
+            accepted.message.uncertain?.({
+              reason: "delivery_uncertain",
+              providerEntryId: accepted.entryId,
+              ...(promptEpoch?.ownedRunId() === undefined ? {} : { providerRunId: promptEpoch.ownedRunId() }),
+            });
+          }
+        } catch {
+          accepted.message.uncertain?.({
+            reason: "delivery_uncertain",
+            providerEntryId: accepted.entryId,
+            ...(promptEpoch?.ownedRunId() === undefined ? {} : { providerRunId: promptEpoch.ownedRunId() }),
+          });
+          onEvent({
+            type: "runtime_warning",
+            warning_kind: "live_input_cancellation_failed",
+            message: "Unable to prove whether queued live input was removed.",
+          });
+        }
+      }
+  }
+}
+
+/**
+ * Own exact Pi run/entry correlation for the one main prompt in this Mono run.
+ * @param {{harness: any, onEvent: (event: any) => void}} deps
+ */
+export function createLiveInputPromptEpoch({ harness, onEvent }) {
+  const BUFFER_LIMIT = 101;
+  /** @type {string|undefined} */
+  let runId;
+  let eventWindowClosed = false;
+  let invalid = false;
+  /** @type {Array<{entryId: string, runId: string}>} */
+  const buffered = [];
+  /** @type {Map<string, {message: any, observed: boolean, consumed: boolean}>} */
+  const entries = new Map();
+  // The operation id Pi admitted for the main prompt (via confirm) or that the
+  // settled prompt reported (via finish). Consumption is only acknowledged once
+  // the observed main-lane run_start carries this exact id.
+  /** @type {string|undefined} */
+  let admittedOperationId;
+  let operationConfirmed = false;
+
+  const remove = harness.subscribe((event) => {
+    if (!event || event.lane !== "main") return;
+    if (event.type === "run_start" && typeof event.runId === "string" && event.runId.length > 0) {
+      if (runId === undefined) {
+        runId = event.runId;
+        if (admittedOperationId !== undefined && admittedOperationId !== runId) {
+          invalidate("operation_mismatch");
+          return;
+        }
+        if (admittedOperationId !== undefined) operationConfirmed = true;
+        consumeBuffered();
+      } else if (runId !== event.runId) {
+        invalidate("multiple_run_start");
+      }
+      return;
+    }
+    if (event.type === "run_end" && event.runId === runId) {
+      eventWindowClosed = true;
+      return;
+    }
+    if (
+      event.type !== "message_end"
+      || eventWindowClosed
+      || event.message?.role !== "user"
+      || typeof event.entryId !== "string"
+      || event.entryId.length === 0
+      || typeof event.runId !== "string"
+      || event.runId.length === 0
+    ) return;
+    if (buffered.some((item) => item.entryId === event.entryId && item.runId === event.runId)) {
+      consumeBuffered();
+      return;
+    }
+    if (buffered.length >= BUFFER_LIMIT) {
+      invalidate("event_buffer_overflow");
+      return;
+    }
+    buffered.push({ entryId: event.entryId, runId: event.runId });
+    consumeBuffered();
+  });
+
+  return {
+    ownedRunId: () => runId,
+    consumedInputIds: () => invalid ? null : [...entries.values()].filter((entry) => entry.consumed).map((entry) => entry.message.id),
+    register(entryId, message) {
+      if (!entries.has(entryId)) entries.set(entryId, { message, observed: false, consumed: false });
+      if (invalid) {
+        settleUncertain(entries.get(entryId), entryId);
+        return;
+      }
+      consumeBuffered();
+    },
+    isConsumed: (entryId) => entries.get(entryId)?.consumed === true,
+    /**
+     * Own the admitted operation as soon as Pi reports its id, before the run
+     * settles, so entries consumed mid-run are acknowledged when their
+     * message_end arrives rather than in one batch at the end of the run.
+     * Safe in either order with run_start; a conflicting id invalidates.
+     */
+    confirm(operationId) {
+      if (invalid) return;
+      if (
+        typeof operationId !== "string"
+        || operationId.length === 0
+        || (admittedOperationId !== undefined && admittedOperationId !== operationId)
+        || (runId !== undefined && runId !== operationId)
+      ) {
+        invalidate("operation_mismatch");
+        return;
+      }
+      admittedOperationId = operationId;
+      if (runId === undefined) return;
+      operationConfirmed = true;
+      confirmObserved();
+    },
+    finish(operationId) {
+      if (
+        typeof operationId !== "string"
+        || operationId.length === 0
+        || runId === undefined
+        || operationId !== runId
+        || (admittedOperationId !== undefined && admittedOperationId !== operationId)
+      ) {
+        invalidate("operation_mismatch");
+        return;
+      }
+      admittedOperationId = operationId;
+      operationConfirmed = true;
+      confirmObserved();
+    },
+    close() {
+      remove?.();
     },
   };
+
+  function consumeBuffered() {
+    if (invalid || runId === undefined) return;
+    for (const evidence of buffered) {
+      if (evidence.runId !== runId) continue;
+      const entry = entries.get(evidence.entryId);
+      if (entry === undefined || entry.consumed) continue;
+      entry.observed = true;
+    }
+    if (operationConfirmed) confirmObserved();
+  }
+
+  function confirmObserved() {
+    if (!operationConfirmed || runId === undefined || invalid) return;
+    for (const [entryId, entry] of entries) {
+      if (!entry.observed || entry.consumed) continue;
+      entry.consumed = true;
+      entry.message.acknowledge?.({ providerEntryId: entryId, providerRunId: runId });
+    }
+  }
+
+  function invalidate(reason) {
+    if (invalid) return;
+    invalid = true;
+    try {
+      onEvent({
+        type: "runtime_warning",
+        warning_kind: "live_input_correlation_invalid",
+        message: "Live-input consumption could not be correlated to exactly one provider operation.",
+        reason,
+      });
+    } catch { /* diagnostics do not alter settlement */ }
+    for (const [entryId, entry] of entries) settleUncertain(entry, entryId);
+  }
+
+  function settleUncertain(entry, entryId) {
+    if (entry === undefined || entry.consumed) return;
+    entry.message.uncertain?.({
+      reason: "delivery_uncertain",
+      providerEntryId: entryId,
+      ...(runId === undefined ? {} : { providerRunId: runId }),
+    });
+  }
 }
 
 /**
@@ -404,23 +627,32 @@ export function startLiveInput({ harness, options, onEvent }) {
  * @param {any} harness
  * @param {string} promptText
  * @param {Array<any>} promptImages
- * @returns {Promise<{runError: any}>}
+ * @param {{onOperationAdmitted?: (operationId: string) => void}} [hooks]
+ *   `onOperationAdmitted` fires as soon as Pi admits the run, before any
+ *   provider request, so the live-input epoch can own the operation up front.
+ * @returns {Promise<{runError: any, operationId?: string}>}
  */
-export async function runHarnessPrompt(harness, promptText, promptImages) {
+export async function runHarnessPrompt(harness, promptText, promptImages, hooks) {
   let runError = null;
+  let operationId;
   try {
     // Pass structured images (when present) so multimodal input reaches the
     // model as image blocks rather than stringified text. AgentHarness.prompt
     // takes them under an options object (`{ images }`); a bare array would be
     // read as `options` and silently dropped (options?.images === undefined).
-    if (Array.isArray(promptImages) && promptImages.length > 0) {
-      await harness.prompt(promptText, { images: promptImages });
-    } else {
-      await harness.prompt(promptText);
-    }
+    const promptOptions = {
+      ...(Array.isArray(promptImages) && promptImages.length > 0 ? { images: promptImages } : {}),
+      ...(typeof hooks?.onOperationAdmitted === "function"
+        ? { onOperationAdmitted: hooks.onOperationAdmitted }
+        : {}),
+    };
+    const result = Object.keys(promptOptions).length > 0
+      ? await harness.prompt(promptText, promptOptions)
+      : await harness.prompt(promptText);
+    operationId = result?.operationId;
   } catch (err) {
     runError = err;
   }
   await harness.waitForIdle();
-  return { runError };
+  return { runError, ...(operationId === undefined ? {} : { operationId }) };
 }

package/src/ai/providers/pi-native.js

@@ -55,12 +55,15 @@ import {
   buildErrorDetails,
   buildErrorResult,
   buildSuccessResult,
+  failureKindForPiError,
   emitCapabilitiesResolved,
   emitUsageCostEvents,
   usageFromMessages,
+  hasMeasuredUsage,
   withSubagentUsage,
 } from "./pi-native/result-builder.js";
 import {
+  captureSessionRecovery,
   cleanupSessionOnThrow,
   commitSession,
   discardUncommittedSession,
@@ -77,11 +80,13 @@ import {
   activateTurnHarness,
   buildTurnHarness,
   buildTurnTools,
+  createLiveInputPromptEpoch,
   runHarnessPrompt,
   startLiveInput,
   thinkingLevelForEffort,
 } from "./pi-native/turn-runner.js";
 import { resolvePiTransport } from "./pi-native/transport.js";
+import { withOpenCodeSessionHeaders } from "./pi-native/provider-attribution.js";
 
 /**
  * Resolve mono-agent's programmatic mode once per run. Tool builders mark
@@ -190,23 +195,82 @@ export function createDynamicCredentialStore(apiKeys, resolvePiApiKey, runtimeWa
 // resolved model. `piResolvedModels` is an advanced/test seam mirroring
 // `piResolvedModel`: when supplied it is used verbatim (the model dispatched via
 // `piResolvedModel` may live outside pi's builtin catalog, e.g. a faux model).
-function buildRunModels(runtime, options, runtimeWarnings) {
-  if (options.piResolvedModels) return options.piResolvedModels;
-  const credentials = createDynamicCredentialStore(runtime.apiKeys, options.resolvePiApiKey, runtimeWarnings);
-  if (options.customProvider) {
-    const model = runtime.model;
-    const models = createModels({ credentials });
-    models.setProvider(createProvider({
-      id: model.provider,
-      name: model.name || model.provider,
-      baseUrl: model.baseUrl,
-      auth: { apiKey: envApiKeyAuth(model.name || model.provider, []) },
-      models: [model],
-      api: openAICompletionsApi(),
-    }));
-    return models;
+function buildRunModels(runtime, options, runtimeWarnings, providerAttributionSessionId) {
+  let models;
+  if (options.piResolvedModels) {
+    models = options.piResolvedModels;
+  } else {
+    const credentials = createDynamicCredentialStore(runtime.apiKeys, options.resolvePiApiKey, runtimeWarnings);
+    if (options.customProvider) {
+      const model = runtime.model;
+      models = createModels({ credentials });
+      models.setProvider(createProvider({
+        id: model.provider,
+        name: model.name || model.provider,
+        baseUrl: model.baseUrl,
+        auth: { apiKey: envApiKeyAuth(model.name || model.provider, []) },
+        models: [model],
+        api: openAICompletionsApi(),
+      }));
+    } else {
+      models = builtinModels({
+        credentials,
+        ...(options.providerCheckAuthContext === undefined
+          ? {}
+          : { authContext: options.providerCheckAuthContext }),
+      });
+    }
   }
-  return builtinModels({ credentials });
+  return withProviderCheckOutputCap(
+    withOpenCodeSessionHeaders(models, providerAttributionSessionId),
+    options.providerCheckMaxTokens,
+  );
+}
+
+const PROVIDER_CHECK_REQUEST_METHODS = new Set([
+  "stream",
+  "complete",
+  "streamSimple",
+  "completeSimple",
+  "streamDeferred",
+  "fetchDeferred",
+  "cancelDeferred",
+]);
+
+/**
+ * Pi's Agent resolves the transport model through `Models` again, so capping
+ * only the model handed to the harness does not constrain the actual provider
+ * request. Bind the same cap at the dispatcher boundary used by every request
+ * path. This wrapper is activated only for explicit provider checks.
+ *
+ * @param {import("@earendil-works/pi-ai").Models} models
+ * @param {unknown} requestedCap
+ * @returns {import("@earendil-works/pi-ai").Models}
+ */
+function withProviderCheckOutputCap(models, requestedCap) {
+  const cap = Number(requestedCap);
+  if (!Number.isSafeInteger(cap) || cap <= 0) return models;
+  const wrappers = new Map();
+  return /** @type {import("@earendil-works/pi-ai").Models} */ (new Proxy(models, {
+    get(target, property) {
+      const value = Reflect.get(target, property, target);
+      if (typeof property !== "string" || typeof value !== "function") return value;
+      if (!PROVIDER_CHECK_REQUEST_METHODS.has(property)) return value.bind(target);
+      let wrapper = wrappers.get(property);
+      if (wrapper === undefined) {
+        wrapper = (model, ...args) => {
+          const current = Number(model?.maxTokens);
+          const cappedModel = {
+            ...model,
+            maxTokens: Number.isFinite(current) && current > 0 ? Math.min(current, cap) : cap,
+          };
+          return value.call(target, cappedModel, ...args);
+        };
+        wrappers.set(property, wrapper);
+      }
+      return wrapper;
+    },
+  }));
 }
 
 // Normalize the incoming runtime messages into AgentMessages the harness can
@@ -313,6 +377,9 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
       diagnostics: {},
     },
     session: null,
+    // Fresh stateless calls own a private repo, even when attribution matches a
+    // live primary session. Cleanup must never delete that primary's record.
+    ephemeralSessionRepo: null,
     sessionEntry: null,
     // Fresh keep-alive sessions are registered busy until the harness closes;
     // this prevents another turn from reopening the same repo record while its
@@ -336,12 +403,17 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
     // (host/runtime-side throws after the session mutated) can roll back too, not
     // just the success path.
     baselineLeafId: null,
+    recoveryOperationId: undefined,
+    recoveryInputIds: null,
+    retainRecoveryTail: false,
   };
 
   const providerSessionId = options.sessionId
     || options.providerSessionId
+    || options.providerAttributionSessionId
     || options.runId
     || randomUUID();
+  const providerAttributionSessionId = options.providerAttributionSessionId || providerSessionId;
   // Prefer the explicit sessionId, but fall back to providerSessionId so a caller
   // that only supplies providerSessionId still resumes the prior session instead
   // of being treated as a fresh run (which would drop prior context).
@@ -423,7 +495,7 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
     // ready pi-ai Model (e.g. a registered faux provider model) plus optional
     // capabilities, bypassing the static model-registry lookup. Production
     // callers leave it undefined and resolve through pi-ai's registry.
-    const runtime = options.piResolvedModel
+    let runtime = options.piResolvedModel
       ? {
         model: options.piResolvedModel,
         capabilities: options.piResolvedCapabilities || {
@@ -438,6 +510,15 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
         apiKeys: new Map(),
       }
       : resolvePiRuntimeModel(resolved, options);
+    if (Number.isSafeInteger(options.providerCheckMaxTokens) && options.providerCheckMaxTokens > 0) {
+      runtime = {
+        ...runtime,
+        model: {
+          ...runtime.model,
+          maxTokens: Math.min(runtime.model.maxTokens, options.providerCheckMaxTokens),
+        },
+      };
+    }
     const capabilities = runtime.capabilities || {};
     const effectiveThinkingLevel = thinkingLevelForEffort(options.effort || "medium", capabilities);
     const reference = resolved.reference || `${resolved.provider}:${resolved.model}`;
@@ -507,7 +588,7 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
     // global scheduling mode from the tools' executionMode markers.
     const toolSteeringMode = "one-at-a-time";
 
-    const piModels = buildRunModels(runtime, options, runtimeWarnings);
+    const piModels = buildRunModels(runtime, options, runtimeWarnings, providerAttributionSessionId);
 
     // Construct the harness and recover any interrupted durable operation.
     // Stream subscription and the external abort handler are activated only
@@ -560,11 +641,6 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
       reference,
     });
 
-    // Live steering: consume follow-up messages and steer the harness mid-run.
-    // The consumer is tied to run completion so it stops steering once the run
-    // finishes and does not swallow messages meant for a later turn.
-    const liveInput = startLiveInput({ harness, options, onEvent });
-
     // Re-check abort right before issuing the provider request. The abort
     // handler is only installed at ~:639, AFTER a long stretch of awaited setup
     // (reopen, create, MCP init, buildContext, appendMessage, getLeafId). If
@@ -606,6 +682,25 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
       runtimeWarnings,
     });
 
+    // Arm the main-prompt epoch after proactive compaction so compaction and
+    // transcript seeding cannot be mistaken for live-input consumption.
+    runState.recoveryBaselineTipId = await runState.session.getLeafId();
+    const liveInputEpoch = createLiveInputPromptEpoch({ harness, onEvent });
+    const liveInput = startLiveInput({ harness, options, onEvent, promptEpoch: liveInputEpoch });
+
+    // Report the live harness value, not a downstream recreation of Pi's
+    // thinking-level normalization. This also captures any future adapter-side
+    // adjustment between construction and the provider request.
+    const providerEffectiveEffort = harness.getThinkingLevel();
+    onEvent({
+      type: "provider_execution_config",
+      sdk: "pi",
+      model: reference,
+      ...(options.effort ? { effort: options.effort } : {}),
+      effectiveEffort: providerEffectiveEffort,
+      timestamp: Date.now(),
+    });
+
     onEvent({
       type: "provider_request_started",
       sdk: "pi",
@@ -614,11 +709,26 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
       timestamp: Date.now(),
     });
 
-    let { runError } = await runHarnessPrompt(harness, promptText, promptImages);
-
-    // The run is done: stop the live-steering consumer so it cannot steer a
-    // finished harness or swallow a follow-up meant for the next turn.
-    await liveInput.stop();
+    let runError;
+    try {
+      // Own the operation at admission so steers consumed mid-run settle as
+      // applied immediately; finish() re-checks the settled id at the end.
+      const promptResult = await runHarnessPrompt(harness, promptText, promptImages, {
+        onOperationAdmitted: (operationId) => {
+          runState.recoveryOperationId = operationId;
+          liveInputEpoch.confirm(operationId);
+        },
+      });
+      runError = promptResult.runError;
+      liveInputEpoch.finish(promptResult.operationId);
+    } finally {
+      // Stop joins unresolved native enqueue and reconciles every returned
+      // entry before the exact-operation subscription is removed.
+      try { await liveInput.stop(); } finally {
+        runState.recoveryInputIds = liveInputEpoch.consumedInputIds();
+        liveInputEpoch.close();
+      }
+    }
 
     runState.externalAbort ||= !!options.abortSignal?.aborted;
 
@@ -804,6 +914,12 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
     // tracks LIVENESS so disposeProviderSession / idle-TTL eviction can reach
     // native sessions, keep-alive registers the session, and a failed/aborted
     // resumed turn rolls back to its pre-turn leaf.
+    runState.retainRecoveryTail = !!durableRepo && options.sessionKeepAlive === true
+      && !runState.maxTurnsHit
+      && (!errorMessage || failureKindForPiError(errorMessage, diagnostics) === "provider_unavailable")
+      && typeof options.sessionRecovery?.runId === "string" && options.sessionRecovery.runId.length > 0
+      && Number.isSafeInteger(options.sessionRecovery?.revision) && options.sessionRecovery.revision >= 0
+      && typeof runState.recoveryOperationId === "string";
     await commitSession(runState, {
       options,
       requestedSessionId,
@@ -815,21 +931,21 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
       onEvent,
     });
 
-    // Final abort guard (durable cancel TOCTOU): if a cancel raced the lifecycle
-    // commit above — landing AFTER the keep-alive/!externalAbort decision but
-    // before this return — the cancelled turn is still in the durable transcript
-    // and (for keep-alive) the live registry. Roll it back so the next resume sees
-    // the pre-turn state (rollbackAbortedTurn: a resumed session moves to its
-    // baseline leaf and drops its live entry; a fresh durable session deletes its
-    // jsonl). The abort re-check + return stay inline with NO await between the
-    // false-branch check and the return, so an external cancel cannot newly fire
-    // past it (I10).
+    // Uncoordinated calls keep their final rollback guard. Coordinated calls
+    // retain the tail and close it before granting a recovery receipt; recheck
+    // cancellation after that await as well.
     if (!runState.externalAbort && options.abortSignal?.aborted) {
       runState.externalAbort = true;
-      await rollbackAbortedTurn(runState, { requestedSessionId, providerSessionId, durableRepo });
+      if (!runState.retainRecoveryTail) await rollbackAbortedTurn(runState, { requestedSessionId, providerSessionId, durableRepo });
     }
 
-    return buildSuccessResult({
+    // A receipt is proof of a successfully closed native operation, never a
+    // promise that the finally block will eventually close it.
+    const providerSessionRecovery = runState.retainRecoveryTail
+      ? await captureSessionRecovery(runState, { options, providerSessionId, modelKey: `${resolved.provider}:${resolved.model}`, model: runtime.model, pending: !!errorMessage || runState.externalAbort })
+      : undefined;
+    if (runState.retainRecoveryTail) runState.externalAbort ||= !!options.abortSignal?.aborted;
+    return { ...buildSuccessResult({
       finalText,
       finalThinking,
       events,
@@ -848,8 +964,10 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
       providerSessionId,
       runtimeWarnings,
       capabilitiesUsed,
+      usageMeasured: hasMeasuredUsage(runTranscript),
       structuredResult: runState.structuredResult,
-    });
+      effectiveEffort: providerEffectiveEffort,
+    }), ...(providerSessionRecovery ? { providerSessionRecovery } : {}) };
   } catch (err) {
     runState.externalAbort ||= !!options.abortSignal?.aborted;
     // Drop a just-created fresh durable session, release a create-on-miss
@@ -883,6 +1001,7 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
       runtimeWarnings,
       isRetryable,
       piTransport,
+      effectiveEffort: harness?.getThinkingLevel?.(),
     });
   } finally {
     try { await harness?.close?.(); } catch { /* best-effort */ }