deepline 0.3.289 → 0.3.291

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

@@ -216,7 +216,11 @@ import {
   ToolExecuteAuthScopeChangedError,
   type ToolExecuteHttpFailureOutcome,
 } from './tool-execute-retry-policy';
-import { createToolHttpError } from './tool-http-errors';
+import {
+  createToolHttpError,
+  attachToolCallFailureEvidenceFromResponse,
+  readToolCallFailureEvidence,
+} from './tool-http-errors';
 import {
   describeTransportError,
   transportGatewayOriginForDiagnostic,
@@ -255,6 +259,7 @@ import {
 } from './play-artifact-runtime-contract';
 import {
   LOG_LEVELS,
+  classifyLogLine,
   formatCtxFetchHttpFailureDiagnostic,
   tagLogEntry,
   tagLogLevel,
@@ -446,7 +451,11 @@ import {
   RunLogBuffer,
   RUNNER_LOG_CONTEXT_MAX_BYTES,
 } from './run-log-buffer';
-import { normalizePlayLogContext, type PlayLogContext } from './log-context';
+import {
+  normalizePlayLogContext,
+  type PlayLogContext,
+  type PlayLogMetadata,
+} from './log-context';
 import type { AsyncPlayRunRef } from '../plays/authoring-contract';
 import { admitAsyncPlayLineage } from './async-play-invocation';
 import {
@@ -536,6 +545,11 @@ type InlineCompositionStore = {
 };
 const inlineCompositionContext =
   new AsyncLocalStorage<InlineCompositionStore>();
+// Authored scope is async-local: concurrent steps and rows cannot steal attribution.
+const authoredStepContext = new AsyncLocalStorage<{
+  context: PlayContextImpl;
+  stepId: string;
+}>();
 const toolExecutionOverrides = new AsyncLocalStorage<{ force: boolean }>();
 const PROGRESS_HEARTBEAT_INTERVAL_MS = 1_000;
 const PURE_JS_HEARTBEAT_ROW_INTERVAL = 250;
@@ -1806,7 +1820,27 @@ type NativeBatchBodyAttribution = {
   release(): void;
 };
 
+type ToolBatchAdmissionObserver = {
+  pending(requests: readonly ToolCallRequest[]): void;
+  dispatched(requests: readonly ToolCallRequest[]): void;
+};
+
+function settleToolBatchGroups(
+  groups: ToolCallRequest[][],
+  execute: (requests: ToolCallRequest[]) => Promise<void>,
+  observer?: ToolBatchAdmissionObserver,
+): Promise<PromiseSettledResult<void>[]> {
+  return Promise.allSettled(
+    groups.map((requests) =>
+      execute(requests).finally(() => observer?.dispatched(requests)),
+    ),
+  );
+}
+
 type ToolExecutionApiOptions = {
+  /** Runner-local scheduling signals; never part of a provider/wire payload. */
+  onProviderAdmissionPending?: () => void;
+  onProviderDispatched?: () => void;
   timeoutMs?: number;
   abortSignal?: AbortSignal;
   durableCallReceiptKey?: string | null;
@@ -6367,11 +6401,14 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               ? {
                   relayReceiptOutput: {
                     receiptKey: input.resultReceiptKey,
-                    execution: toolExecutionMetadataForOutcome({
-                      kind: 'live',
-                      cacheKey: input.request.cacheKey,
-                      receiptKey: input.request.receiptKey,
-                    }),
+                    execution: {
+                      ...toolExecutionMetadataForOutcome({
+                        kind: 'live',
+                        cacheKey: input.request.cacheKey,
+                        receiptKey: input.request.receiptKey,
+                      }),
+                      resultReceiptKey: input.resultReceiptKey,
+                    },
                     metadata: await this.resolveToolResultMetadata(
                       input.dispatchToolId,
                     ),
@@ -6411,11 +6448,16 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           meta: execution.meta,
           billing: execution.billing,
           requestInput: input.dispatchPayload,
-          execution: toolExecutionMetadataForOutcome({
-            kind: 'live',
-            cacheKey: input.request.cacheKey,
-            receiptKey: input.request.receiptKey,
-          }),
+          execution: {
+            ...toolExecutionMetadataForOutcome({
+              kind: 'live',
+              cacheKey: input.request.cacheKey,
+              receiptKey: input.request.receiptKey,
+            }),
+            ...(!alwaysFresh && input.resultReceiptKey
+              ? { resultReceiptKey: input.resultReceiptKey }
+              : {}),
+          },
         });
         // First sub-phase of `resultDelivery`: the body was parsed above, and
         // this is the instant the row's result actually exists. Everything
@@ -7032,7 +7074,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
 
   private async serializeCellValue(value: unknown): Promise<unknown> {
     const serialized = isToolExecuteResult(value)
-      ? serializeToolExecuteResult(value)
+      ? serializeToolExecuteResult(value, { includeCallEvidence: false })
       : await this.serializeDatasetCells(value);
     try {
       stringifyPostgresJson(serialized);
@@ -7053,7 +7095,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     const visiting = new WeakSet<object>();
     const visit = async (current: unknown): Promise<unknown> => {
       if (isToolExecuteResult(current)) {
-        return serializeToolExecuteResult(current);
+        return serializeToolExecuteResult(current, {
+          includeCallEvidence: false,
+        });
       }
       if (isPlayDataset(current)) {
         return await serializePlayDatasetCell(current, visit);
@@ -7359,7 +7403,20 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           input.metadata ??
           (await this.resolveToolResultMetadata(input.toolId)),
         execution: input.execution,
-        meta: input.meta,
+        meta: {
+          ...input.meta,
+          ...(input.execution.source === 'live' &&
+          input.requestInput &&
+          !input.meta?.callEvidence
+            ? {
+                callEvidence: {
+                  input: this.secretRedactor.redact(input.requestInput),
+                  providerRequestsUnavailable:
+                    'This response did not retain provider HTTP evidence.',
+                },
+              }
+            : {}),
+        },
         billing: input.billing,
       }),
     );
@@ -11829,8 +11886,14 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           request.executionAuthScopeDigest ?? '',
           String(strategy.toBucketKey(request.input)),
         ].join('\u0000'),
-        readyCount: strategy.maxBatchSize,
-        maxGroupSize: this.governor.policy.concurrency.toolCalls,
+        readyCount: Math.min(
+          strategy.maxBatchSize,
+          this.governor.policy.concurrency.toolCalls,
+        ),
+        maxGroupSize: Math.min(
+          strategy.maxBatchSize,
+          this.governor.policy.concurrency.toolCalls,
+        ),
         coalesceWindowMs: this.toolCoalesceWindowMs(
           this.#options.toolBatchCoalesceWindowMs,
           TOOL_BATCH_COALESCE_WINDOW_MS,
@@ -12030,6 +12093,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
 
     const requests: ToolCallRequest[] = [];
     const remaining: ToolCallRequest[] = [];
+    const remainingLaneKeys = new Set<string>();
     const selectedByLane = new Map<string, number>();
     for (const request of this.toolCallQueue) {
       const lane = this.toolDispatchLane(request);
@@ -12043,12 +12107,15 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         selectedByLane.set(lane.key, selectedCount + 1);
       } else {
         remaining.push(request);
+        remainingLaneKeys.add(lane.key);
       }
     }
     this.toolCallQueue = remaining;
     const selectedLaneKeys = new Set(selectedByLane.keys());
     for (const laneKey of selectedLaneKeys) {
-      this.toolDispatchQueuedAtByLane.delete(laneKey);
+      if (!remainingLaneKeys.has(laneKey)) {
+        this.toolDispatchQueuedAtByLane.delete(laneKey);
+      }
     }
     return { requests, laneKeys: selectedLaneKeys, nextDeadlineMs };
   }
@@ -12258,6 +12325,33 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     // it never waits for unrelated sibling calls from the previous column.
     const inFlightToolExecutions = new Map<Promise<void>, ToolCallRequest[]>();
     const activeGroupsByLane = new Map<string, number>();
+    // Keep a native batch lane together while its physical request is
+    // preparing or waiting for provider admission. Release it at dispatch, so
+    // provider residence does not serialize the next batch.
+    const pendingAdmissionByLane = new Map<string, Set<string>>();
+    const admissionObserver: ToolBatchAdmissionObserver = {
+      pending: (requests) => {
+        for (const request of requests) {
+          if (!this.#options.getBatchOperationStrategy?.(request.toolId))
+            continue;
+          const key = this.toolDispatchLane(request).key;
+          const pending = pendingAdmissionByLane.get(key) ?? new Set<string>();
+          pending.add(request.callId);
+          pendingAdmissionByLane.set(key, pending);
+        }
+      },
+      dispatched: (requests) => {
+        let changed = false;
+        for (const request of requests) {
+          const key = this.toolDispatchLane(request).key;
+          const pending = pendingAdmissionByLane.get(key);
+          if (!pending?.delete(request.callId)) continue;
+          changed = true;
+          if (pending.size === 0) pendingAdmissionByLane.delete(key);
+        }
+        if (changed) this.wakeToolDispatcher();
+      },
+    };
     const maxInFlightGroups = Math.max(
       1,
       Math.floor(
@@ -12319,6 +12413,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             .filter(([, count]) => count >= maxInFlightGroupsPerLane)
             .map(([laneKey]) => laneKey),
         );
+        for (const key of pendingAdmissionByLane.keys()) {
+          blockedLaneKeys.add(key);
+        }
         const dispatchable =
           inFlightToolExecutions.size >= maxInFlightGroups
             ? {
@@ -12361,7 +12458,11 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               (activeGroupsByLane.get(laneKey) ?? 0) + 1,
             );
           }
-          const tracked = this.executeBatchedToolCalls(dispatchable.requests)
+          admissionObserver.pending(dispatchable.requests);
+          const tracked = this.executeBatchedToolCalls(
+            dispatchable.requests,
+            admissionObserver,
+          )
             .catch(async (error) => {
               this.toolDispatcherFailure ??= error;
               this.rejectQueuedToolCalls(error);
@@ -12371,6 +12472,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               );
             })
             .finally(() => {
+              admissionObserver.dispatched(dispatchable.requests);
               this.observeToolDispatchGroupRoundTrip(
                 this.toolBatchDispatcherNowMs() - launchedAtMs,
               );
@@ -12517,6 +12619,54 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     };
   }
 
+  private async saveToolFailureEvidence(input: {
+    toolId: string;
+    callKey: string;
+    input: Record<string, unknown>;
+    error: unknown;
+    context: PlayLogContext;
+  }): Promise<string | undefined> {
+    if (!this.#options.completeRuntimeStepReceipt) return;
+    try {
+      // An immutable diagnostic record in the SAME receipt store, discovered
+      // through runtime_observability.events. It is never an executable result
+      // cache and cannot change provider admission or replay semantics.
+      const receipt = await this.completeRuntimeStepReceipt(
+        `${buildDurableToolReceiptPrefix({
+          orgId: this.#options.orgId ?? 'unknown-org',
+          toolId: 'call-evidence',
+        })}${stableDigest(`${this.currentRunId}:${crypto.randomUUID()}`)}`,
+        this.currentRunId,
+        this.secretRedactor.redact({
+          kind: 'tool_call_evidence',
+          toolId: input.toolId,
+          callKey: input.callKey,
+          status: 'failed',
+          context: input.context,
+          callEvidence: readToolCallFailureEvidence(input.error) ?? {
+            input: input.input,
+            providerRequestsUnavailable:
+              'This failure did not retain provider HTTP evidence.',
+          },
+          error:
+            serializeToolExecutionFailure(input.error) ??
+            this.formatRuntimeError(input.error),
+        }),
+        COMPLETED_RECEIPT_CACHE_INSERT_LEASE_ID,
+      );
+      if (!receipt)
+        throw new Error('Saved failure evidence was not acknowledged.');
+      return receipt.key;
+    } catch (error) {
+      // Keep the original failure and never repeat a paid operation just to
+      // repair observability. A missing record is explicit in retained logs.
+      this.runtimeLog(
+        `Saved call details unavailable: ${this.formatRuntimeError(error)}`,
+        { level: 'warn' },
+      );
+    }
+  }
+
   private async executeTool(
     key: string,
     toolId: string,
@@ -12545,13 +12695,31 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         !isPlayRowExecutionSuspendedError(error) &&
         !(error instanceof PlayRowProviderBackpressureError)
       ) {
+        const scope = authoredStepContext.getStore();
+        const savedKey = await this.saveToolFailureEvidence({
+          toolId,
+          callKey: context.call_key,
+          context: {
+            callKey: context.call_key,
+            toolId,
+            callStatus: 'failed',
+            ...(scope?.context === this ? { stepId: scope.stepId } : {}),
+            ...(context.dataset ? { dataset: context.dataset } : {}),
+            ...(context.column ? { column: context.column } : {}),
+            ...(context.row_key ? { rowKey: context.row_key } : {}),
+          },
+          input,
+          error,
+        });
         this.runtimeLog(
           JSON.stringify({
             event: 'tool_call_failed',
             ...context,
+            ...(savedKey ? { receipt_key: savedKey } : {}),
             status: 'failed',
             duration_ms: Math.max(0, Date.now() - startedAt),
           }),
+          { level: 'error' },
         );
       }
       throw error;
@@ -12562,7 +12730,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       JSON.stringify({
         event: 'tool_call_completed',
         ...context,
-        ...(execution?.receiptKey ? { receipt_key: execution.receiptKey } : {}),
+        ...(execution?.resultReceiptKey || execution?.receiptKey
+          ? { receipt_key: execution.resultReceiptKey ?? execution.receiptKey }
+          : {}),
         ...(execution?.source ? { execution_source: execution.source } : {}),
         status: toolResult?.status ?? 'completed',
         // Caller wall time includes queueing/reuse and result delivery. It is
@@ -14222,7 +14392,21 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
   ): void {
     const boundedLine = boundRunLogLine(line);
     const omittedBefore = this.logBuffer.snapshot().omittedLines;
-    for (const retained of this.logBuffer.append(line, terminal, context)) {
+    const scope = authoredStepContext.getStore();
+    const classified = classifyLogLine(line);
+    const timestamp = classified.line.match(/^\[([^\]]+)\]/)?.[1];
+    const parsedAt = timestamp ? Date.parse(timestamp) : NaN;
+    const metadata: PlayLogMetadata = {
+      level: classified.level,
+      occurredAt: Number.isFinite(parsedAt) ? parsedAt : Date.now(),
+      ...(scope?.context === this ? { stepId: scope.stepId } : {}),
+    };
+    for (const retained of this.logBuffer.append(
+      line,
+      terminal,
+      context,
+      metadata,
+    )) {
       const originalLineWasRetained =
         retained === boundedLine &&
         this.logBuffer.snapshot().omittedLines === omittedBefore;
@@ -14231,6 +14415,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         originalLineWasRetained
           ? (this.logBuffer.contexts.at(-1) ?? undefined)
           : undefined,
+        this.logBuffer.ids.at(-1),
+        originalLineWasRetained
+          ? (this.logBuffer.metadata.at(-1) ?? undefined)
+          : undefined,
       );
       if (this.#options.verbose) console.log(retained);
     }
@@ -14894,42 +15082,80 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       return output;
     };
 
-    return this.executeWithRuntimeReceipt<T>(
-      'step',
-      normalizedKey,
-      this.currentRunId,
-      {
-        semanticKey: rowStore
-          ? stableDigest(
-              stableStringify({
-                scope: 'row',
-                tableNamespace: rowStore.tableNamespace ?? null,
-                rowKey: rowStore.rowKey ?? null,
-                rowId: rowStore.rowKey ? null : rowStore.rowId,
-                fieldName: rowStore.fieldName ?? null,
-                callIndex,
-                // Row scope prevents unrelated map cells from sharing a
-                // checkpoint. A supplied semantic key identifies the actual
-                // work (for example, ctx.runSteps hashes its current input),
-                // so it must refine row scope rather than being discarded.
-                semanticKey: options?.semanticKey ?? null,
-              }),
-            )
-          : options?.semanticKey,
-        staleAfterSeconds: options?.staleAfterSeconds,
-        force: this.#options.cachePolicy?.forceStepRefresh === true,
-        markSkipped: (output) => {
-          assertJsonSerializableStepOutput(normalizedKey, output);
-        },
-        execute: executeStep,
-      },
-    );
+    const observe = !rowStore;
+    const startedAt = Date.now();
+    if (observe)
+      this.emitExecutionEvent({
+        type: 'step.started',
+        stepId: normalizedKey,
+        at: startedAt,
+      });
+    try {
+      const output = await authoredStepContext.run(
+        { context: this, stepId: normalizedKey },
+        () =>
+          this.executeWithRuntimeReceipt<T>(
+            'step',
+            normalizedKey,
+            this.currentRunId,
+            {
+              semanticKey: rowStore
+                ? stableDigest(
+                    stableStringify({
+                      scope: 'row',
+                      tableNamespace: rowStore.tableNamespace ?? null,
+                      rowKey: rowStore.rowKey ?? null,
+                      rowId: rowStore.rowKey ? null : rowStore.rowId,
+                      fieldName: rowStore.fieldName ?? null,
+                      callIndex,
+                      // Row scope prevents unrelated map cells from sharing a
+                      // checkpoint. A supplied semantic key identifies the actual
+                      // work (for example, ctx.runSteps hashes its current input),
+                      // so it must refine row scope rather than being discarded.
+                      semanticKey: options?.semanticKey ?? null,
+                    }),
+                  )
+                : options?.semanticKey,
+              staleAfterSeconds: options?.staleAfterSeconds,
+              force: this.#options.cachePolicy?.forceStepRefresh === true,
+              markSkipped: (output) => {
+                assertJsonSerializableStepOutput(normalizedKey, output);
+              },
+              execute: executeStep,
+            },
+          ),
+      );
+      if (observe)
+        this.emitExecutionEvent({
+          type: 'step.completed',
+          stepId: normalizedKey,
+          at: Date.now(),
+        });
+      return output;
+    } catch (error) {
+      if (observe && !isControlledPlaySuspension(error))
+        this.emitExecutionEvent({
+          type: 'step.failed',
+          stepId: normalizedKey,
+          at: Date.now(),
+          error: buildPlayDocflowNodeErrorPreview(error, this.secretRedactor),
+        });
+      throw error;
+    }
   }
 
   getLogs(): string[] {
     return this.logBuffer.lines;
   }
 
+  getLogMetadata(): Array<PlayLogMetadata | null> {
+    return this.logBuffer.metadata.slice();
+  }
+
+  getLogIds(): string[] {
+    return this.logBuffer.ids.slice();
+  }
+
   getLogContexts(): Array<PlayLogContext | null> {
     return this.logBuffer.contexts.slice();
   }
@@ -15512,15 +15738,16 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       source: 'cache' | 'owner',
     ): Promise<void> => {
       const receiptKey = request.receiptKey!;
-      const finalResult = cloneToolExecuteResultWithExecution(
-        result,
-        toolExecutionMetadataForOutcome({
+      const finalResult = cloneToolExecuteResultWithExecution(result, {
+        ...toolExecutionMetadataForOutcome({
           kind: source === 'owner' ? 'live' : source,
           cacheKey: request.cacheKey,
           receiptKey,
           ...(source === 'owner' ? {} : { attachedToReceiptKey: receiptKey }),
         }),
-      );
+        resultReceiptKey:
+          this.mappedToolResultReceiptPolicy(request).resultReceiptKey,
+      });
       this.cacheToolResult(toolId, request.cacheKey, finalResult);
       const resolver = this.toolCallResolvers.get(request.callId);
       if (resolver) {
@@ -15676,6 +15903,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     toolId: string;
     requests: ToolCallRequest[];
     strategy: AnyBatchOperationStrategy;
+    admissionObserver?: ToolBatchAdmissionObserver;
   }): Promise<ToolCallRequest[]> {
     const { toolId, requests, strategy } = input;
     if (requests.length === 0) return [];
@@ -15952,6 +16180,12 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                       ),
                       executionAuthScopeDigest:
                         detail.members[0]?.executionAuthScopeDigest ?? null,
+                      onProviderAdmissionPending: () =>
+                        input.admissionObserver?.pending(batch.memberRequests),
+                      onProviderDispatched: () =>
+                        input.admissionObserver?.dispatched(
+                          batch.memberRequests,
+                        ),
                       providerIdempotencyKey: detail.providerOperationKey,
                       providerIdempotencyReceiptKey:
                         compatibility.resultReceiptKey,
@@ -16199,6 +16433,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           });
           return { batch, result };
         } finally {
+          input.admissionObserver?.dispatched(batch.memberRequests);
           // A dispatch that never reached its split — a provider failure, a
           // cohort throw — must not leave the body registered against
           // nobody for the rest of the run.
@@ -16290,16 +16525,23 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
 
   private async executeBatchedToolCalls(
     queuedToolCalls: ToolCallRequest[],
+    admissionObserver?: ToolBatchAdmissionObserver,
   ): Promise<void> {
-    // Group by toolId
+    // Preserve authentication partitions through physical batch compilation.
     const byTool = new Map<string, ToolCallRequest[]>();
     for (const req of queuedToolCalls) {
-      if (!byTool.has(req.toolId)) byTool.set(req.toolId, []);
-      byTool.get(req.toolId)!.push(req);
-    }
-
-    const toolSettlements = await Promise.allSettled(
-      [...byTool.entries()].map(async ([toolId, requests]) => {
+      const key = JSON.stringify([
+        req.toolId,
+        req.executionAuthScopeDigest ?? '',
+      ]);
+      if (!byTool.has(key)) byTool.set(key, []);
+      byTool.get(key)!.push(req);
+    }
+    const toolGroups = [...byTool.values()];
+    const toolSettlements = await settleToolBatchGroups(
+      toolGroups,
+      async (requests) => {
+        const toolId = requests[0]!.toolId;
         this.runtimeLog(
           `Executing tool batch ${toolId}: ${requests.length} calls`,
         );
@@ -16430,6 +16672,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                   toolId,
                   requests: cohortRequests,
                   strategy: operationStrategy,
+                  admissionObserver,
                 })
               : await this.executeCacheableNonNativeMapToolCallCohort({
                   toolId,
@@ -16524,6 +16767,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                       providerOperationKey: aggregateProviderOperationKey,
                       apiOptions: {
                         durableCallReceiptKey: aggregateReceiptKey,
+                        onProviderAdmissionPending: () =>
+                          admissionObserver?.pending(batch.memberRequests),
+                        onProviderDispatched: () =>
+                          admissionObserver?.dispatched(batch.memberRequests),
                         legacyProviderRetryIdentities: [
                           {
                             transportReceiptKey:
@@ -16785,7 +17032,8 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             this.#options.onBatchComplete?.(this.checkpoint);
           }
         }
-      }),
+      },
+      admissionObserver,
     );
     const rejected = toolSettlements.find(
       (settlement): settlement is PromiseRejectedResult =>
@@ -17944,6 +18192,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           let providerTelemetryKey: string | null = null;
           let providerRunInFlightAtDispatch: number | null = null;
           const acquireProviderPermit = async (signal?: AbortSignal) => {
+            options?.onProviderAdmissionPending?.();
             logProvider429RetryPhase('provider_permit_wait_started');
             const permit = await this.resourceGovernor.acquireProviderPermit({
               toolId,
@@ -18094,6 +18343,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                   acquireProviderPermit: async ({ signal }) =>
                     await acquireProviderPermit(signal),
                   tryAcquireProviderPermit: () => {
+                    options?.onProviderAdmissionPending?.();
                     logProvider429RetryPhase(
                       'provider_permit_acquire_attempted',
                     );
@@ -18146,6 +18396,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                       > | null;
                     } = { current: null };
                     const beginProviderExecution = () => {
+                      if (providerExecution.current === null) {
+                        options?.onProviderDispatched?.();
+                      }
                       const execution =
                         providerExecution.current ??
                         this.resourceGovernor.beginProviderExecution({
@@ -19209,6 +19462,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                   `gateway=${transportGatewayOriginForDiagnostic(url)} attempt=${httpFailureAttempt})`,
                 { level: 'error' },
               );
+              attachToolCallFailureEvidenceFromResponse(surfacedError, text);
               throw surfacedError;
             }
 

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

@@ -11,7 +11,7 @@ import type { PlayRunContractSnapshot } from '../plays/contracts';
 import type { PlayDatasetColumnTypes } from '../play-data-plane/contracts';
 import type { PlayStructuredDefinition } from '../plays/definition';
 import type { PlayStaticPipeline } from '../plays/static-pipeline';
-import type { PlayLogContext } from './log-context';
+import type { PlayLogContext, PlayLogMetadata } from './log-context';
 import type {
   AsyncPlayRunRef,
   DurableCallStaleAfterSeconds,
@@ -514,6 +514,9 @@ export interface MapExecutionScope {
 }
 
 export type PlayExecutionEvent =
+  | { type: 'step.started'; stepId: string; at: number }
+  | { type: 'step.completed'; stepId: string; at: number }
+  | { type: 'step.failed'; stepId: string; error: string; at: number }
   | PlayActivityEvent
   | {
       type: 'docflow.node.hit';
@@ -851,7 +854,12 @@ export interface ContextOptions {
   /** Called after each durable batch completes for scheduler checkpointing. */
   onBatchComplete?: (checkpoint: PlayCheckpoint) => void;
   /** Called when the runtime emits a new execution log line. */
-  onLog?: (line: string, context?: PlayLogContext) => void;
+  onLog?: (
+    line: string,
+    context?: PlayLogContext,
+    entryId?: string,
+    metadata?: PlayLogMetadata,
+  ) => void;
   /**
    * Runtime-provided HTTP transport for ctx.fetch. Node runtimes should provide
    * a transport that validates resolved IP addresses at connect time.

package/dist/bundling-sources/shared_libs/play-runtime/fixture-behavior.ts

@@ -84,6 +84,7 @@ const FIXTURE_MODE_BYPASS_PROVIDERS = new Set([
   'test',
   'test_high',
   'test_low',
+  'test_batching',
   // Dedicated stateful failure fixtures must reach their local custom handlers
   // even when the surrounding Play runs in fixture mode.
   'test_receipt',