deepline 0.3.144 → 0.3.146

package/dist/bundling-sources/sdk/src/client.ts

@@ -1960,6 +1960,21 @@ export type WorkspacesNamespace = {
   }) => Promise<WorkspaceCreateResult>;
 };
 
+/** One authenticated per-request usage event from `/api/v2/usage/events`. */
+export type BillingUsageEvent = {
+  id: string | null;
+  provider: string;
+  operation: string;
+  status: string;
+  request_id: string;
+  billing_outcome_reason: string | null;
+  credits: number | null;
+  billing_mode: string | null;
+  pricing_model: string | null;
+  policy_id: string | null;
+  created_at: string;
+};
+
 /**
  * Public `client.billing` namespace for CLI commands and programmatic callers.
  * Covers plans, subscription state, cancellation, and invoice/receipt history.
@@ -1989,6 +2004,8 @@ export type BillingNamespace = {
     /** Subscription invoices plus credit purchase receipts, newest first. */
     list: (options?: { limit?: number }) => Promise<BillingInvoicesResult>;
   };
+  /** Read one exact execution outcome using the request_id returned by executeTool. */
+  usageEvent: (requestId: string) => Promise<BillingUsageEvent>;
   /** Metronome-authored target catalog and current Contract projection. */
   targetPlans: () => Promise<TargetBillingPlansResult>;
   /** Normalized target billing state. */
@@ -2600,6 +2617,7 @@ export class DeeplineClient {
       invoices: {
         list: (options) => this.listBillingInvoices(options),
       },
+      usageEvent: (requestId) => this.getBillingUsageEvent(requestId),
       targetPlans: () => this.getTargetBillingPlans(),
       targetStatus: () => this.getTargetBillingStatus(),
       autoRecharge: {
@@ -3062,7 +3080,7 @@ export class DeeplineClient {
    * guaranteed support for every model. Runtime AI SDK/Gateway errors remain
    * authoritative for model-gated values.
    *
-   * @param model - Gateway model id such as `"openai/gpt-5.5"`
+   * @param model - Exact-case Gateway model id such as `"openai/gpt-5.6-luna"`
    * @returns Model metadata, provider option shapes, and runnable examples
    */
   async describeModel(model: string): Promise<DeeplineAgentModelDescription> {
@@ -5803,6 +5821,40 @@ export class DeeplineClient {
     return this.http.get<BillingPlansResult>('/api/v2/billing/catalog/current');
   }
 
+  /**
+   * Read the authenticated usage record for one execution request. The
+   * request id comes from the original `executeTool` result and is not a
+   * retry or idempotency token.
+   */
+  async getBillingUsageEvent(requestId: string): Promise<BillingUsageEvent> {
+    const normalizedRequestId = requestId.trim();
+    if (
+      normalizedRequestId.length === 0 ||
+      normalizedRequestId.length > 200 ||
+      normalizedRequestId !== requestId
+    ) {
+      throw new DeeplineError(
+        'Usage request_id must contain 1–200 characters with no leading or trailing whitespace.',
+        undefined,
+        'INVALID_USAGE_REQUEST_ID',
+      );
+    }
+    const response = await this.http.get<{
+      entries?: BillingUsageEvent[];
+    }>(
+      `/api/v2/usage/events?request_id=${encodeURIComponent(normalizedRequestId)}`,
+    );
+    const event = response.entries?.[0];
+    if (!event) {
+      throw new DeeplineError(
+        'No usage event was found for this request_id.',
+        undefined,
+        'USAGE_EVENT_NOT_FOUND',
+      );
+    }
+    return event;
+  }
+
   /**
    * Charge the saved payment method and add Deepline credits to the active
    * workspace. Prefer `client.billing.topUp(...)`.

package/dist/bundling-sources/sdk/src/index.ts

@@ -73,6 +73,7 @@ export type {
   BillingSubscriptionCancelResult,
   BillingSubscriptionStatus,
   BillingTopUpResult,
+  BillingUsageEvent,
   WorkspaceCreateResult,
   WorkspacesNamespace,
   MonitorsNamespace,

package/dist/bundling-sources/sdk/src/release.ts

@@ -200,7 +200,7 @@ export const SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: '0.3.144',
+  version: '0.3.146',
   updateSummary:
     'Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.',
   packageCapabilities: {

package/dist/bundling-sources/shared_libs/play-runtime/async-operation.ts

@@ -79,6 +79,12 @@ export type AsyncOperationResultMaterialization = {
 
 export type AsyncOperationContractWire = {
   version: 1;
+  /**
+   * Keep a default synchronous Play call in the runner process: launch the
+   * provider job, expose its handle in run progress, then poll companion tools
+   * until terminal. Direct tools.execute callers keep their own legacy policy.
+   */
+  runtimeManagedWait?: true;
   /** Preserve the provider's historical public async metadata exactly. */
   compatibility?: {
     /** null intentionally suppresses the legacy asyncGetAction projection. */
@@ -285,10 +291,7 @@ export function defineAsyncOperation(
   positiveInteger(contract.polling.intervalMs, 'polling.intervalMs');
   positiveInteger(contract.polling.timeoutMs, 'polling.timeoutMs');
   if (contract.polling.checkTimeoutMs !== undefined) {
-    positiveInteger(
-      contract.polling.checkTimeoutMs,
-      'polling.checkTimeoutMs',
-    );
+    positiveInteger(contract.polling.checkTimeoutMs, 'polling.checkTimeoutMs');
   }
   if (contract.polling.intervalInputField !== undefined) {
     required(contract.polling.intervalInputField, 'polling.intervalInputField');
@@ -906,6 +909,24 @@ export async function executeAsyncOperationLifecycle<Response>(input: {
   responseValue: (response: Response) => unknown;
   sleep?: (ms: number) => Promise<void>;
   now?: () => number;
+  /** Called after the provider handle is known and before the first poll. */
+  onJobStarted?: (input: { jobId: string }) => void;
+  /** Called after each successful status read, including running outcomes. */
+  onPoll?: (input: {
+    jobId: string;
+    pollAttempt: number;
+    elapsedMs: number;
+    result: unknown;
+    outcome: AsyncOperationTerminalOutcome;
+  }) => void;
+  /** Called when an upstream 429 delays a status check. */
+  onRateLimit?: (input: {
+    jobId: string;
+    pollAttempt: number;
+    rateLimitAttempt: number;
+    retryAfterMs: number | null;
+    delayMs: number;
+  }) => void;
   /** Legacy direct callers historically poll once immediately after launch. */
   pollImmediately?: boolean;
 }): Promise<
@@ -939,6 +960,7 @@ export async function executeAsyncOperationLifecycle<Response>(input: {
       `Async operation ${input.contract.lifecycle.startAction} returned running without a provider job id.`,
     );
   }
+  input.onJobStarted?.({ jobId });
   const sleep =
     input.sleep ??
     ((ms) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
@@ -1072,6 +1094,13 @@ export async function executeAsyncOperationLifecycle<Response>(input: {
         rateLimitAttempt: consecutiveRateLimitAttempts,
         retryAfterMs: rateLimit.retryAfterMs,
       });
+      input.onRateLimit?.({
+        jobId,
+        pollAttempt,
+        rateLimitAttempt: consecutiveRateLimitAttempts,
+        retryAfterMs: rateLimit.retryAfterMs,
+        delayMs: nextPollDelayMs,
+      });
       continue;
     }
     if (!pollResponse) {
@@ -1083,6 +1112,13 @@ export async function executeAsyncOperationLifecycle<Response>(input: {
       input.contract,
       previousPollResult,
     );
+    input.onPoll?.({
+      jobId,
+      pollAttempt,
+      elapsedMs: Math.max(0, now() - startedAt),
+      result: previousPollResult,
+      outcome: classification.outcome,
+    });
     if (classification.outcome === 'running') {
       pollAttempt += 1;
       continue;

package/dist/bundling-sources/shared_libs/play-runtime/context.ts

@@ -267,7 +267,14 @@ import {
   type DurableReceiptExecutionStore,
 } from './durable-receipt-execution';
 import {
+  asyncOperationLaunchInput,
+  buildAsyncOperationActionInput,
+  classifyAsyncOperationResult,
+  executeAsyncOperationLifecycle,
+  extractAsyncOperationJobId,
+  readAsyncOperationPath,
   asyncOperationShouldWait,
+  hasExplicitAsyncOperationTerminalMatch,
   type AsyncOperationContractWire,
 } from './async-operation';
 import {
@@ -1510,6 +1517,13 @@ function cancelRuntimeResponseBody(response: Response): void {
   }
 }
 
+function shellQuoteProviderJobCommandValue(value: string): string {
+  // Close the single-quoted token, emit a literal apostrophe, then reopen it.
+  // This keeps copied status commands safe even when provider job IDs contain
+  // shell metacharacters.
+  return `'${value.replaceAll("'", "'\"'\"'")}'`;
+}
+
 const NO_SECRET_RESOLUTION_RETRY: SecretResolutionRetryDecision = {
   retry: false,
   retryDelayMs: 0,
@@ -1859,6 +1873,7 @@ type NativeBatchBodyAttribution = {
 
 type ToolExecutionApiOptions = {
   timeoutMs?: number;
+  abortSignal?: AbortSignal;
   durableCallReceiptKey?: string | null;
   /**
    * Complete-result receipt the execution relay may publish before returning
@@ -8886,6 +8901,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           ),
           pendingRowsCount: Math.max(0, totalInputCount - processedCount),
           failedRowsCount: Math.max(0, failedCount - staleFailedKeys.size),
+          supersededRows: staleCompletedKeys.size + staleFailedKeys.size,
           startedAt:
             this.checkpoint.mapFrames?.[mapScope.mapInvocationId]?.startedAt ??
             Date.now(),
@@ -8915,6 +8931,8 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                 ),
               progressFailedOffset: () =>
                 Math.max(0, failedCount - staleFailedKeys.size),
+              progressSupersededOffset: () =>
+                staleCompletedKeys.size + staleFailedKeys.size,
               progressTotalRows: () => totalInputCount,
               rowFeed: execution.rowFeed,
               retainedRowsMemoryBudgetBytes:
@@ -9140,6 +9158,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           completedRowsCount: completedRows,
           pendingRowsCount: 0,
           failedRowsCount: failedCount,
+          supersededRows: staleCompletedKeys.size + staleFailedKeys.size,
           startedAt:
             this.checkpoint.mapFrames?.[mapScope.mapInvocationId]?.startedAt ??
             Date.now(),
@@ -9154,6 +9173,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           completedRows,
           failedRows: failedCount,
           totalRows: totalInputCount,
+          supersededRows: staleCompletedKeys.size + staleFailedKeys.size,
           at: Date.now(),
         });
         throw new AllAdmittedRowsFailedError({
@@ -9182,6 +9202,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         ),
         pendingRowsCount: 0,
         failedRowsCount: failedCount,
+        supersededRows: staleCompletedKeys.size + staleFailedKeys.size,
         startedAt:
           this.checkpoint.mapFrames?.[mapScope.mapInvocationId]?.startedAt ??
           Date.now(),
@@ -9202,6 +9223,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         ),
         failedRows: failedCount,
         totalRows: totalInputCount,
+        supersededRows: staleCompletedKeys.size + staleFailedKeys.size,
         at: Date.now(),
       });
 
@@ -9986,6 +10008,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       retainedRowsMemoryBudgetBytes?: number;
       progressCompletedOffset?: number | (() => number);
       progressFailedOffset?: number | (() => number);
+      progressSupersededOffset?: number | (() => number);
       progressTotalRows?: number | (() => number);
       /**
        * When set, `items`, `executionRowKeys` and `executionRowIndexes` grow
@@ -10329,6 +10352,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                   liveNumber(runtimeOptions?.progressFailedOffset, 0) +
                   liveFrameSets.failedRowsCount,
               }),
+          supersededRows: liveNumber(
+            runtimeOptions?.progressSupersededOffset,
+            existing.supersededRows ?? 0,
+          ),
           ...(input.activeBoundaryId !== undefined
             ? { activeBoundaryId: input.activeBoundaryId }
             : {}),
@@ -10358,6 +10385,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             completedRowKeys.size,
           failedRows,
           totalRows: currentTotalRows(),
+          supersededRows: liveNumber(
+            runtimeOptions?.progressSupersededOffset,
+            existing.supersededRows ?? 0,
+          ),
           // Inline child aggregates ride the single-writer progress event so
           // fan-out never contends on a per-child mutation. See ADR 0013.
           ...this.inlineChildAggregateEventFields(),
@@ -17781,6 +17812,189 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     this.providerBodyHandlesByRowColumn.delete(rowKey);
   }
 
+  private async resolveAsyncOperationInRuntime(input: {
+    toolId: string;
+    contract: AsyncOperationContractWire;
+    startInput: Record<string, unknown>;
+    startResponse: ParsedToolExecuteResponse;
+  }): Promise<ParsedToolExecuteResponse> {
+    const startResult = input.startResponse.toolResponse?.raw;
+    const jobId = extractAsyncOperationJobId(input.contract, startResult);
+    const hasTerminalMatch = hasExplicitAsyncOperationTerminalMatch(
+      input.contract,
+      startResult,
+    );
+    const startClassification = classifyAsyncOperationResult(
+      input.contract,
+      startResult,
+    );
+    const launchIsRunning =
+      input.contract.launch?.unclassifiedJobOutcome === 'running' &&
+      !hasTerminalMatch;
+
+    if (
+      hasTerminalMatch &&
+      (startClassification.outcome === 'failed' ||
+        startClassification.outcome === 'cancelled')
+    ) {
+      const statusAction = jobId
+        ? input.contract.lifecycle.pollActions[0]
+        : undefined;
+      const statusCommand =
+        jobId && statusAction
+          ? ` Check its status with: deepline tools execute ${shellQuoteProviderJobCommandValue(statusAction.action)}` +
+            ` --input ${shellQuoteProviderJobCommandValue(JSON.stringify(buildAsyncOperationActionInput({ mapping: statusAction.input, jobId, startInput: input.startInput, startResult })))} --json`
+          : '';
+      throw new Error(
+        `${startClassification.message ?? `Provider task ${jobId ?? input.toolId} ended ${startClassification.outcome}.`}${statusCommand}`,
+      );
+    }
+
+    if (!jobId) {
+      if (launchIsRunning) {
+        throw new Error(
+          `Async operation ${input.toolId} returned no provider job id; it could not be polled safely.`,
+        );
+      }
+      return input.startResponse;
+    }
+    if (hasTerminalMatch && startClassification.outcome !== 'running') {
+      return input.startResponse;
+    }
+    if (!launchIsRunning && startClassification.outcome !== 'running') {
+      return input.startResponse;
+    }
+
+    const statusAction = input.contract.lifecycle.pollActions[0];
+    if (!statusAction) {
+      throw new Error(
+        `Async operation ${input.toolId} has no status action for provider job ${jobId}.`,
+      );
+    }
+    const statusInput = buildAsyncOperationActionInput({
+      mapping: statusAction.input,
+      jobId,
+      startInput: input.startInput,
+      startResult,
+    });
+    const statusCommand =
+      `deepline tools execute ${shellQuoteProviderJobCommandValue(statusAction.action)}` +
+      ` --input ${shellQuoteProviderJobCommandValue(JSON.stringify(statusInput))} --json`;
+    let lastProgressLogAtMs = 0;
+    const lifecycle = await executeAsyncOperationLifecycle({
+      contract: input.contract,
+      startInput: input.startInput,
+      startResult,
+      jobId,
+      executeAction: ({ action, input: actionInput, timeoutMs, abortSignal }) =>
+        this.callToolExecutionAPI(action, actionInput, {
+          timeoutMs,
+          abortSignal,
+          skipAsyncOperationResolution: true,
+          uncachedAsyncLifecycleCall: true,
+        }),
+      responseValue: (response) => response.toolResponse?.raw,
+      onJobStarted: () => {
+        this.runtimeLog(
+          `Provider task ${jobId} is running. This Play remains synchronous while it checks for completion. ` +
+            `Canceling the Play stops this wait, not the accepted provider job; it may still incur Deepline credits. ` +
+            `Check it separately with: ${statusCommand}`,
+        );
+      },
+      onPoll: ({ pollAttempt, elapsedMs, outcome, result }) => {
+        if (
+          outcome !== 'running' ||
+          elapsedMs - lastProgressLogAtMs >= 15_000
+        ) {
+          const statusPaths = input.contract.terminal.rules.flatMap((rule) =>
+            rule.conditions.map((condition) => condition.path),
+          );
+          const providerStatus = statusPaths
+            .map((path) => readAsyncOperationPath(result, path))
+            .find((value): value is string => typeof value === 'string');
+          this.runtimeLog(
+            `Provider task ${jobId}: status check ${pollAttempt + 1} returned ${outcome}` +
+              `${providerStatus ? ` (provider status: ${providerStatus})` : ''} after ${Math.round(elapsedMs / 1_000)}s.`,
+          );
+          lastProgressLogAtMs = elapsedMs;
+        }
+      },
+      onRateLimit: ({
+        pollAttempt,
+        rateLimitAttempt,
+        retryAfterMs,
+        delayMs,
+      }) => {
+        this.runtimeLog(
+          `Provider task ${jobId}: status check received HTTP 429 on retry ${rateLimitAttempt} (after ${pollAttempt} successful checks). ` +
+            `${retryAfterMs === null ? 'No Retry-After was supplied' : `Retry-After was ${retryAfterMs}ms`}; retrying after ${delayMs}ms.`,
+        );
+      },
+    }).catch((error: unknown) => {
+      const surfacedError =
+        error instanceof Error ? error : new Error(String(error));
+      surfacedError.message =
+        `${surfacedError.message}\nProvider task ${jobId} may still be running. ` +
+        `Check its status with: ${statusCommand}`;
+      throw surfacedError;
+    });
+
+    if (lifecycle.kind === 'timed_out') {
+      const timeoutError = new Error(
+        `Provider task ${jobId} did not finish before the wait limit. ` +
+          `Check its status with: ${statusCommand}`,
+      );
+      this.runtimeLog(timeoutError.message, { level: 'error' });
+      throw timeoutError;
+    }
+    if (
+      lifecycle.classification.outcome === 'failed' ||
+      lifecycle.classification.outcome === 'cancelled'
+    ) {
+      const terminalError = new Error(
+        `${lifecycle.classification.message ?? `Provider task ${jobId} ended ${lifecycle.classification.outcome}.`} ` +
+          `Check its status with: ${statusCommand}`,
+      );
+      this.runtimeLog(terminalError.message, { level: 'error' });
+      throw terminalError;
+    }
+    if (!lifecycle.materialized) {
+      const error = new Error(
+        `Provider task ${jobId} completed without a materialized result. ` +
+          `Check its status with: ${statusCommand}`,
+      );
+      this.runtimeLog(error.message, { level: 'error' });
+      throw error;
+    }
+
+    const materialized = lifecycle.materialized;
+    const originalRawV2 = input.startResponse.toolResponse?.rawV2;
+    const rawV2 =
+      originalRawV2 &&
+      typeof originalRawV2 === 'object' &&
+      !Array.isArray(originalRawV2)
+        ? {
+            ...(originalRawV2 as Record<string, unknown>),
+            data: materialized.result,
+          }
+        : { data: materialized.result };
+    const responseMeta = input.startResponse.toolResponse?.meta;
+    return {
+      ...input.startResponse,
+      status: materialized.outcome === 'no_result' ? 'no_result' : 'completed',
+      toolResponse: {
+        ...input.startResponse.toolResponse,
+        raw: materialized.result,
+        rawV2,
+        view: 'data',
+      },
+      result: {
+        data: materialized.result,
+        ...(responseMeta ? { meta: responseMeta } : {}),
+      },
+    };
+  }
+
   private async callToolExecutionAPI(
     toolId: string,
     input: Record<string, unknown>,
@@ -17803,6 +18017,13 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     const shouldWaitForAsyncOperation = Boolean(
       asyncContract && asyncOperationShouldWait(asyncContract, input),
     );
+    const shouldResolveAsyncOperationInRuntime = Boolean(
+      asyncContract?.runtimeManagedWait === true &&
+      asyncContract.lifecycle.startAction === toolId &&
+      shouldWaitForAsyncOperation,
+    );
+    const shouldWaitAtExecutionBoundary =
+      shouldWaitForAsyncOperation && !shouldResolveAsyncOperationInRuntime;
     // An explicitly opted-in caller-managed launch gives the Play author the
     // provider handle and leaves polling to the authored graph. Do not let a
     // provider's legacy synchronous helper turn a wide start wave into
@@ -18035,7 +18256,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           let providerRateLimitRetryFromInvocationAttempt: number | null = null;
           const serializedRequestBody = (invocationAttempt: number) =>
             JSON.stringify({
-              payload: toolInputSnapshot,
+              payload: shouldResolveAsyncOperationInRuntime
+                ? asyncOperationLaunchInput(asyncContract!, toolInputSnapshot)
+                : toolInputSnapshot,
               metadata: {
                 parent_run_id: this.#options.runId,
                 invocation_attempt: invocationAttempt,
@@ -18050,7 +18273,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                 // admission proof distinct from the optional provider fence:
                 // ordinary calls are governor-managed too.
                 runtime_governor_managed: true,
-                ...(shouldWaitForAsyncOperation
+                ...(shouldWaitAtExecutionBoundary
                   ? { async_operation_wait: true }
                   : {}),
                 ...(shouldPreferAsyncProviderExecution
@@ -18278,11 +18501,26 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             // not share the coordinator's TTL environment.
             const hasReceiptHeartbeat = Boolean(options?.heartbeatReceipt);
             const abortController =
-              timeoutMs || hasReceiptHeartbeat ? new AbortController() : null;
+              timeoutMs || hasReceiptHeartbeat || options?.abortSignal
+                ? new AbortController()
+                : null;
+            const forwardAbortSignal = () => {
+              if (!options?.abortSignal?.aborted) return;
+              abortController?.abort(options.abortSignal.reason);
+            };
             const receiptHeartbeat = options?.heartbeatReceipt;
             let heartbeatFailure: unknown = null;
             let timeoutHandle: ReturnType<typeof setTimeout> | null = null;
             try {
+              if (options?.abortSignal?.aborted) {
+                forwardAbortSignal();
+              } else {
+                options?.abortSignal?.addEventListener(
+                  'abort',
+                  forwardAbortSignal,
+                  { once: true },
+                );
+              }
               const ownershipStartedAt = Date.now();
               await options?.beforeProviderCall?.();
               if (runtimeReceiptReadTraceEnabled) {
@@ -18971,6 +19209,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               if (timeoutHandle) {
                 clearTimeout(timeoutHandle);
               }
+              options?.abortSignal?.removeEventListener(
+                'abort',
+                forwardAbortSignal,
+              );
             }
 
             if (!response) {
@@ -19235,6 +19477,14 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               );
             }
             const parsed = parseToolExecuteResponse(toolId, responseData);
+            const resolved = shouldResolveAsyncOperationInRuntime
+              ? await this.resolveAsyncOperationInRuntime({
+                  toolId,
+                  contract: asyncContract!,
+                  startInput: toolInputSnapshot,
+                  startResponse: parsed,
+                })
+              : parsed;
             // Only the configured execution relay may mint this header. The
             // ordinary app route (and every direct provider path) keeps the
             // established full-payload completion behavior even if an
@@ -19249,14 +19499,16 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                 : null;
             setSpanAttributes(span, {
               'plays.tool_result_kind':
-                parsed.result == null
+                resolved.result == null
                   ? 'null'
-                  : Array.isArray(parsed.result)
+                  : Array.isArray(resolved.result)
                     ? 'array'
-                    : typeof parsed.result,
+                    : typeof resolved.result,
             });
             toolCallSucceeded = true;
-            return receiptOutputRef ? { ...parsed, receiptOutputRef } : parsed;
+            return receiptOutputRef
+              ? { ...resolved, receiptOutputRef }
+              : resolved;
           }
         },
       );

package/dist/bundling-sources/shared_libs/play-runtime/ctx-types.ts

@@ -489,6 +489,8 @@ export interface MapExecutionFrame {
   completedRowsCount?: number;
   pendingRowsCount?: number;
   failedRowsCount?: number;
+  /** Terminal rows omitted from this run's latest view because a newer write won. */
+  supersededRows?: number;
   activeBoundaryId?: string | null;
   startedAt: number;
   updatedAt: number;
@@ -590,6 +592,8 @@ export type PlayExecutionEvent =
       totalRows: number;
       completedRows: number;
       pendingRows: number;
+      /** Rows omitted because a newer Runtime Sheet write already won. */
+      supersededRows?: number;
       at: number;
     }
   | {
@@ -601,6 +605,8 @@ export type PlayExecutionEvent =
       totalRows: number;
       completedRows: number;
       pendingRows: number;
+      /** Rows omitted because a newer Runtime Sheet write already won. */
+      supersededRows?: number;
       at: number;
     }
   | {
@@ -612,6 +618,8 @@ export type PlayExecutionEvent =
       completedRows: number;
       failedRows: number;
       totalRows?: number;
+      /** Rows whose Runtime Sheet write lost to a newer write; not failures. */
+      supersededRows?: number;
       /**
        * Inline child-play composition aggregates for this run. Maintained by the
        * single-writer progress path (never per child), so fan-out cannot contend.
@@ -644,6 +652,8 @@ export type PlayExecutionEvent =
       completedRows: number;
       failedRows: number;
       totalRows?: number;
+      /** Rows whose Runtime Sheet write lost to a newer write; not failures. */
+      supersededRows?: number;
       /**
        * Inline child-play composition aggregates for this run. Maintained by the
        * single-writer progress path (never per child). See ADR 0013.

package/dist/bundling-sources/shared_libs/play-runtime/protocol.ts

@@ -371,6 +371,7 @@ export type PlayRunnerResult =
       /** Customer-safe runtime observations that must survive bounded log tails. */
       runtimeDiagnostics?: CtxFetchHttpFailureDiagnostic[];
       outputRowCount?: number;
+      rowOutcomes?: PlayRunnerRowOutcomeSummary;
       logs: string[];
       stats: Record<string, unknown>;
       steps: PlayStep[];
@@ -406,5 +407,14 @@ export type PlayRunnerResult =
       totalRows?: number;
       inserted?: number;
       skipped?: number;
+      rowOutcomes?: PlayRunnerRowOutcomeSummary;
       runtimeTiming?: PlayRunnerRuntimeTiming;
     };
+
+export type PlayRunnerRowOutcomeSummary = {
+  completedRows: number;
+  failedRows: number;
+  totalRows: number;
+  /** Rows omitted because a newer Runtime Sheet write took precedence. */
+  supersededRows?: number;
+};