deepline 0.3.64 → 0.3.66

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

@@ -95,6 +95,7 @@ import { resolveExecutionPolicy } from './governor/policy';
 import {
   createRuntimeResourceGovernor,
   type RuntimeResourceGovernor,
+  type RuntimeResourceLease,
 } from './resource-governor';
 import { CTX_FETCH_EGRESS_TOOL_ID } from './builtin-pacing';
 import {
@@ -193,6 +194,10 @@ import {
   type PlayAuthoringRunScope,
   type PlayAuthoringRuntimeContext,
 } from '../plays/authoring-contract';
+import {
+  formatCtxFetchHttpFailureDiagnostic,
+  tagLogProvenance,
+} from './log-provenance';
 import {
   DURABLE_RECEIPT_WAIT_DELAY_MS,
   DURABLE_RECEIPT_WAIT_MAX_ATTEMPTS,
@@ -207,6 +212,14 @@ import {
   waitForCompletedRuntimeReceipts,
   type DurableReceiptExecutionStore,
 } from './durable-receipt-execution';
+import {
+  asyncOperationDurableStartInput,
+  asyncOperationShouldWait,
+  classifyAsyncOperationResult,
+  executeAsyncOperationLifecycle,
+  resolveAsyncOperationPolling,
+  type AsyncOperationContractWire,
+} from './async-operation';
 import {
   QUERY_RESULT_DATASET_PAGE_SIZE,
   isCustomerDbDatasetTool,
@@ -442,6 +455,10 @@ const DEFAULT_TOOL_RUNTIME_TIMEOUT_MS = 15 * 60 * 1000 + 30_000;
 const FETCH_TRANSPORT_MAX_ATTEMPTS =
   RUNTIME_RELIABILITY_POLICY.egress.fetchMaxAttempts;
 const FETCH_TRANSPORT_RETRY_DELAY_MS = 100;
+// Diagnostic logs are retained in the context until terminalization. Keep a
+// representative, deduplicated set so row-heavy continued failures cannot turn
+// customer-safe observability into unbounded runner memory or log traffic.
+const MAX_CTX_FETCH_HTTP_FAILURE_DIAGNOSTICS = 16;
 const CTX_FETCH_HEADERS_TIMEOUT_MS =
   RUNTIME_RELIABILITY_POLICY.egress.fetchHeadersTimeoutMs;
 const CTX_FETCH_BODY_TIMEOUT_MS =
@@ -1228,6 +1245,27 @@ function publicToolResponseEnvelope(value: unknown): {
   };
 }
 
+function materializedAsyncToolResponse(
+  response: ParsedToolExecuteResponse['toolResponse'] | undefined,
+  result: unknown,
+): ParsedToolExecuteResponse['toolResponse'] {
+  const hasRawV2 =
+    response !== undefined &&
+    Object.prototype.hasOwnProperty.call(response, 'rawV2');
+  const materializedRawV2 =
+    response?.view === 'data'
+      ? {
+          ...(recordOrNull(response.rawV2) ?? {}),
+          data: result,
+        }
+      : result;
+  return {
+    ...(response ?? {}),
+    raw: result,
+    ...(hasRawV2 ? { rawV2: materializedRawV2 } : {}),
+  };
+}
+
 /**
  * A batched provider request returns one envelope for several logical source
  * tool calls. Each source call persists only its own item-shaped canonical
@@ -1384,6 +1422,8 @@ type ToolExecutionApiOptions = {
     pageSize: number;
     totalRows: number;
   };
+  /** Internal recursion guard for lifecycle poll/finish calls. */
+  skipAsyncOperationResolution?: boolean;
 };
 const IN_MEMORY_STEP_RESULT_PREVIEW_LIMIT = 25;
 /**
@@ -2048,9 +2088,14 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     string,
     { resolve: (value: unknown) => void; reject: (reason: unknown) => void }
   >();
+  private readonly asyncOperationCapacity = new Map<
+    string,
+    { active: number; waiters: Array<() => void> }
+  >();
   #options: ContextOptions;
   private readonly executionScope: RunExecutionScope;
   private logBuffer: string[] = [];
+  private readonly ctxFetchHttpFailureDiagnosticIdentities = new Set<string>();
   private checkpoint: PlayCheckpoint;
   private readonly durableCallCacheEpochMs: number;
   /**
@@ -10124,6 +10169,58 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     if (this.#options.verbose) console.log(line);
   }
 
+  /**
+   * Emit a runtime-authored diagnostic through the same durable log path as
+   * ctx.log without changing the customer-authored log wire format.
+   */
+  private runtimeDiagnosticLog(message: string): void {
+    assertNoSecretTaint(message, 'runtime diagnostic log');
+    const line = tagLogProvenance(
+      'diagnostic',
+      `[${new Date().toISOString()}] ${this.secretRedactor.redactRegisteredSecrets(message)}`,
+    );
+    this.logBuffer.push(line);
+    this.#options.onLog?.(line);
+    if (this.#options.verbose) console.log(line);
+  }
+
+  /** A URL safe to persist in a customer-visible run log (origin only). */
+  private ctxFetchDiagnosticUrl(url: string): string {
+    try {
+      const parsed = new URL(url);
+      return parsed.origin;
+    } catch {
+      // ctx.fetch already parses its URL before this helper is reachable.
+      return '[invalid-url]';
+    }
+  }
+
+  private logCtxFetchHttpFailure(input: {
+    key: string;
+    method: string;
+    url: string;
+    httpStatus: number;
+  }): void {
+    const url = this.ctxFetchDiagnosticUrl(input.url);
+    const identity = `${input.key}\u0000${input.method}\u0000${url}\u0000${input.httpStatus}`;
+    if (
+      this.ctxFetchHttpFailureDiagnosticIdentities.has(identity) ||
+      this.ctxFetchHttpFailureDiagnosticIdentities.size >=
+        MAX_CTX_FETCH_HTTP_FAILURE_DIAGNOSTICS
+    ) {
+      return;
+    }
+    this.ctxFetchHttpFailureDiagnosticIdentities.add(identity);
+    this.runtimeDiagnosticLog(
+      formatCtxFetchHttpFailureDiagnostic({
+        key: input.key,
+        method: input.method,
+        url,
+        http_status: input.httpStatus,
+      }),
+    );
+  }
+
   async sleep(ms: number): Promise<void> {
     this.assertInlineChildContract('suspending_child');
     const delayMs =
@@ -10176,6 +10273,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
 
     const url = input.toString();
     const parsedUrl = new URL(url);
+    const method = (init.method ?? 'GET').toUpperCase();
     const urlContainsResolvedSecret =
       this.secretRedactor.containsRegisteredSecret(url, {
         includeEncoded: true,
@@ -10267,6 +10365,14 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         staleAfterSeconds: options?.staleAfterSeconds,
         transient: options?.transient === true,
         onRecovered: (output) => {
+          if (!output.ok) {
+            this.logCtxFetchHttpFailure({
+              key: normalizedKey,
+              method,
+              url: output.url || url,
+              httpStatus: output.status,
+            });
+          }
           if (!output.ok && this.currentAuthoringContractEdition >= 5) {
             throw new CtxFetchHttpError(output);
           }
@@ -10278,7 +10384,6 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             this.currentAuthoringContractEdition >= 5
           ),
         execute: async ({ retainExternalCallSlot }) => {
-          const method = (init.method ?? 'GET').toUpperCase();
           const secretHeaders = await this.resolveSecretAuth(secretAuth);
           const headers: Record<string, string> = {
             ...normalizeFetchHeaders(init.headers),
@@ -10313,6 +10418,15 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             'output' in existing
           ) {
             this.log(`ctx.fetch(${url}): recovered response from checkpoint`);
+            const checkpointOutput = existing.output as PlayFetchResponse;
+            if (!checkpointOutput.ok) {
+              this.logCtxFetchHttpFailure({
+                key: normalizedKey,
+                method,
+                url: checkpointOutput.url || url,
+                httpStatus: checkpointOutput.status,
+              });
+            }
             if (this.durableDirectToolResultsBackedByReceipts) {
               // The outer durable receipt is the replay authority in hosted
               // runtimes. A legacy checkpoint fetch may seed that receipt
@@ -10320,7 +10434,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               // cache for the lifetime of a large map.
               delete this.checkpoint.resolvedBoundaries?.[boundaryId];
             }
-            return existing.output as PlayFetchResponse;
+            return checkpointOutput;
           }
 
           if (!['GET', 'HEAD', 'OPTIONS'].includes(method)) {
@@ -10460,6 +10574,15 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               json: this.secretRedactor.redactKnownSecrets(rawJson),
             };
 
+            if (!output.ok) {
+              this.logCtxFetchHttpFailure({
+                key: normalizedKey,
+                method,
+                url: output.url || url,
+                httpStatus: output.status,
+              });
+            }
+
             // Edition 5 adopts normal fetch semantics: a non-2xx response is
             // a failed durable operation. Throw before checkpoint/receipt
             // completion so the failure is never cached. Editions 1–4 retain
@@ -13123,6 +13246,154 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     });
   }
 
+  private async acquireAsyncOperationCapacity(input: {
+    toolId: string;
+    provider: string;
+    contract: AsyncOperationContractWire;
+    authScopeDigest: string | null;
+  }): Promise<() => void> {
+    const scopeSuffix =
+      input.contract.capacity.scope === 'organization_action'
+        ? input.toolId
+        : input.contract.capacity.scope === 'organization_connection'
+          ? (input.authScopeDigest ?? 'default-connection')
+          : input.provider;
+    const key = `${this.#options.orgId ?? 'unknown-org'}:${input.provider}:${input.contract.capacity.scope}:${scopeSuffix}`;
+    let limit = 1;
+    if (input.contract.capacity.limit.kind === 'fixed') {
+      limit = input.contract.capacity.limit.maxConcurrentJobs;
+    } else {
+      const hints =
+        (await this.#options.getToolQueueHints?.(input.toolId)) ?? [];
+      const declaredLimits = hints
+        .map((hint) => hint.maxConcurrency)
+        .filter(
+          (value): value is number =>
+            typeof value === 'number' && Number.isFinite(value) && value > 0,
+        );
+      limit = declaredLimits.length > 0 ? Math.min(...declaredLimits) : 1;
+    }
+    const state = this.asyncOperationCapacity.get(key) ?? {
+      active: 0,
+      waiters: [],
+    };
+    this.asyncOperationCapacity.set(key, state);
+    if (state.active >= limit) {
+      if (input.contract.capacity.onConflict === 'fail') {
+        throw new Error(
+          `Async provider capacity is full for ${input.provider}; the contract allows ${limit} active job(s).`,
+        );
+      }
+      await new Promise<void>((resolve) => state.waiters.push(resolve));
+    }
+    state.active += 1;
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      state.active = Math.max(0, state.active - 1);
+      state.waiters.shift()?.();
+      if (state.active === 0 && state.waiters.length === 0) {
+        this.asyncOperationCapacity.delete(key);
+      }
+    };
+  }
+
+  private asyncOperationActionReceiptKey(input: {
+    action: string;
+    parentReceiptKey: string | null;
+    jobId: string;
+    phase: string;
+  }): string | null {
+    if (!input.parentReceiptKey) return null;
+    return `${buildDurableToolReceiptPrefix({
+      orgId: this.#options.orgId,
+      toolId: input.action,
+    })}${stableDigest(
+      stableStringify({
+        parentReceiptKey: input.parentReceiptKey,
+        jobId: input.jobId,
+        phase: input.phase,
+      }),
+    )}`;
+  }
+
+  private async resolveAsyncOperation(input: {
+    toolId: string;
+    startInput: Record<string, unknown>;
+    startResponse: ParsedToolExecuteResponse;
+    contract: AsyncOperationContractWire;
+    receiptKey: string | null;
+  }): Promise<ParsedToolExecuteResponse> {
+    const responseValue = (response: ParsedToolExecuteResponse): unknown => {
+      if (response.toolResponse && 'raw' in response.toolResponse) {
+        return response.toolResponse.raw;
+      }
+      const result = recordOrNull(response.result);
+      return result && Object.prototype.hasOwnProperty.call(result, 'data')
+        ? result.data
+        : response.result;
+    };
+    const startResult = responseValue(input.startResponse);
+    const lifecycle = await executeAsyncOperationLifecycle({
+      contract: input.contract,
+      startInput: input.startInput,
+      startResult,
+      jobId: input.startResponse.jobId,
+      sleep: async (delayMs) =>
+        await this.sleepWithCheckpointHeartbeat(delayMs),
+      responseValue,
+      executeAction: async (request) => {
+        const receiptKey = this.asyncOperationActionReceiptKey({
+          action: request.action,
+          parentReceiptKey: input.receiptKey,
+          jobId: request.jobId,
+          phase: `${request.phase}:${request.pollAttempt}:${request.page ?? ''}`,
+        });
+        return await this.callToolExecutionAPI(request.action, request.input, {
+          skipAsyncOperationResolution: true,
+          durableCallReceiptKey: receiptKey,
+          providerIdempotencyReceiptKey: receiptKey,
+          providerIdempotencyKey: receiptKey,
+        });
+      },
+    });
+    if (lifecycle.kind === 'timed_out') {
+      const polling = resolveAsyncOperationPolling({
+        contract: input.contract,
+        startInput: input.startInput,
+      });
+      throw new Error(
+        `Async operation ${input.toolId} (${lifecycle.jobId}) did not reach a terminal state within ${polling.timeoutMs}ms.`,
+      );
+    }
+    if (
+      lifecycle.classification.outcome === 'failed' ||
+      lifecycle.classification.outcome === 'cancelled'
+    ) {
+      throw new Error(
+        lifecycle.classification.message ??
+          `Async operation ${input.toolId} (${lifecycle.jobId}) ended ${lifecycle.classification.outcome}.`,
+      );
+    }
+    const materialized = lifecycle.materialized!;
+    const selectedResponse =
+      lifecycle.finishResponse ?? lifecycle.pollResponse;
+    return {
+      ...selectedResponse,
+      status:
+        lifecycle.classification.outcome === 'no_result' ||
+        materialized.outcome === 'no_result'
+          ? 'no_result'
+          : 'completed',
+      result: { data: materialized.result },
+      toolResponse: materializedAsyncToolResponse(
+        selectedResponse.toolResponse,
+        materialized.result,
+      ),
+    };
+  }
+
   private async callToolExecutionAPI(
     toolId: string,
     input: Record<string, unknown>,
@@ -13152,6 +13423,16 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       this.currentAuthoringContractEdition,
     );
     const provider = toolId.split(/[._]/)[0]?.trim() || 'provider';
+    const asyncContract = options?.skipAsyncOperationResolution
+      ? null
+      : ((await this.#options.getToolAsyncOperation?.(toolId)) ?? null);
+    const shouldWaitForAsyncOperation = Boolean(
+      asyncContract && asyncOperationShouldWait(asyncContract, input),
+    );
+    const effectiveInput =
+      asyncContract && shouldWaitForAsyncOperation
+        ? asyncOperationDurableStartInput(asyncContract, input)
+        : input;
     const activityId = `provider:${toolId}`;
     let retryActivityEmitted = false;
     let toolCallSucceeded = false;
@@ -13160,39 +13441,51 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     // execution. Per-provider rate admission is intentionally deferred until
     // each physical fetch is ready to leave this process.
     const admissionStartedAt = Date.now();
-    const toolSlot = await this.resourceGovernor
-      .acquireTool({
+    const asyncCapacityRelease =
+      asyncContract && shouldWaitForAsyncOperation
+        ? await this.acquireAsyncOperationCapacity({
+            toolId,
+            provider,
+            contract: asyncContract,
+            authScopeDigest:
+              (await this.resolveToolAuthScopeDigest(toolId))?.trim() ?? null,
+          })
+        : null;
+    let toolSlot: RuntimeResourceLease;
+    try {
+      toolSlot = await this.resourceGovernor.acquireTool({
         orgId: this.#options.orgId ?? null,
         providerResourceKey: `tool:${toolId}`,
         toolId,
-      })
-      .catch((error: unknown) => {
-        if (!(error instanceof ProviderExhaustedError)) throw error;
-        const retryAtMs = Date.parse(error.retryAt);
-        throw createToolHttpError(
-          toolErrorSchemaVersion,
-          error.message,
-          null,
-          429,
-          'repairable',
-          {
-            toolId,
-            provider: error.provider,
-            operation: toolId,
-            code: error.code,
-            origin: 'provider',
-            category: 'rate_limit',
-            retryable: true,
-            statusCode: 429,
-            requestId: null,
-            retryAfterMs: Number.isFinite(retryAtMs)
-              ? Math.max(0, retryAtMs - Date.now())
-              : null,
-            networkKind: null,
-            networkScope: null,
-          },
-        );
       });
+    } catch (error) {
+      asyncCapacityRelease?.();
+      if (!(error instanceof ProviderExhaustedError)) throw error;
+      const retryAtMs = Date.parse(error.retryAt);
+      throw createToolHttpError(
+        toolErrorSchemaVersion,
+        error.message,
+        null,
+        429,
+        'repairable',
+        {
+          toolId,
+          provider: error.provider,
+          operation: toolId,
+          code: error.code,
+          origin: 'provider',
+          category: 'rate_limit',
+          retryable: true,
+          statusCode: 429,
+          requestId: null,
+          retryAfterMs: Number.isFinite(retryAtMs)
+            ? Math.max(0, retryAtMs - Date.now())
+            : null,
+          networkKind: null,
+          networkScope: null,
+        },
+      );
+    }
     if (runtimeReceiptReadTraceEnabled) {
       this.log(
         `[perf] tool call id=${toolId} phase=governor_admission elapsed_ms=${Date.now() - admissionStartedAt}`,
@@ -13222,10 +13515,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           // Snapshot the caller-controlled payload exactly once. The replay
           // decision and every physical attempt must refer to the same bytes,
           // even if the original object has getters or is later mutated.
-          const toolInputSnapshot = JSON.parse(JSON.stringify(input)) as Record<
-            string,
-            unknown
-          >;
+          const toolInputSnapshot = JSON.parse(
+            JSON.stringify(effectiveInput),
+          ) as Record<string, unknown>;
           const retryPolicy = await this.#options
             .getToolRetryPolicy?.(toolId, toolInputSnapshot)
             .catch(() => null);
@@ -13865,7 +14157,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                 );
               }
               if (failure.shouldRetry) {
-                if (failure.reason !== 'gateway_invocation_in_progress') {
+                if (
+                  failure.reason !== 'gateway_invocation_in_progress' &&
+                  failure.reason !== 'concurrency_backpressure'
+                ) {
                   invocationAttempt += 1;
                 }
                 if (failure.chargeRetryBudget) {
@@ -13949,8 +14244,29 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                     ? 'array'
                     : typeof parsed.result,
             });
+            const parsedValue =
+              parsed.toolResponse && 'raw' in parsed.toolResponse
+                ? parsed.toolResponse.raw
+                : (recordOrNull(parsed.result)?.data ?? parsed.result);
+            const asyncStartPending =
+              asyncContract && shouldWaitForAsyncOperation
+                ? classifyAsyncOperationResult(asyncContract, parsedValue)
+                    .outcome === 'running'
+                : false;
+            const resolved =
+              asyncContract &&
+              shouldWaitForAsyncOperation &&
+              (parsed.status === 'running' || asyncStartPending)
+                ? await this.resolveAsyncOperation({
+                    toolId,
+                    startInput: input,
+                    startResponse: parsed,
+                    contract: asyncContract,
+                    receiptKey: durableCallReceiptKey,
+                  })
+                : parsed;
             toolCallSucceeded = true;
-            return parsed;
+            return resolved;
           }
         },
       );
@@ -13977,6 +14293,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       if (!toolSlotTransferred) {
         toolSlot.release();
       }
+      asyncCapacityRelease?.();
     }
   }
 

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

@@ -815,6 +815,13 @@ export interface ContextOptions {
   getToolResultMetadata?: (
     toolId: string,
   ) => Promise<ToolResultMetadataInput | null> | ToolResultMetadataInput | null;
+  /** Canonical provider-job lifecycle executed below scalar and native batch calls. */
+  getToolAsyncOperation?: (
+    toolId: string,
+  ) =>
+    | Promise<import('./async-operation').AsyncOperationContractWire | null>
+    | import('./async-operation').AsyncOperationContractWire
+    | null;
   getIntegrationEventWaitHandler?: (
     toolId: string,
   ) =>

package/dist/bundling-sources/shared_libs/play-runtime/log-provenance.ts

@@ -125,6 +125,85 @@ export function tagLogProvenance(
   return `${PROVENANCE_PREFIX}${provenance}${PROVENANCE_SENTINEL}${line}`;
 }
 
+/**
+ * A customer-safe record of a `ctx.fetch` response that reached the server but
+ * was not successful. Its URL is destination-origin-only; it deliberately
+ * omits paths, query strings, request/response bodies, headers, receipt ids,
+ * and row identity: all of those can contain customer data or credentials.
+ * This one stable shape is shared by the
+ * runtime (emission), finalization (terminal warning), and CLI/tests
+ * (inspection), rather than each layer trying to infer an HTTP failure from
+ * arbitrary user logs.
+ */
+export type CtxFetchHttpFailureDiagnostic = {
+  key: string;
+  method: string;
+  url: string;
+  http_status: number;
+};
+
+/** Guard terminal-transport diagnostics before they reach customer surfaces. */
+export function isCtxFetchHttpFailureDiagnostic(
+  value: unknown,
+): value is CtxFetchHttpFailureDiagnostic {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+  const record = value as Record<string, unknown>;
+  return (
+    typeof record.key === 'string' &&
+    typeof record.method === 'string' &&
+    typeof record.url === 'string' &&
+    typeof record.http_status === 'number' &&
+    Number.isInteger(record.http_status)
+  );
+}
+
+export const CTX_FETCH_HTTP_FAILURE_LOG_PREFIX =
+  '[runtime.ctx_fetch_http_failure]';
+
+/** Format the canonical durable log line for an observed non-2xx ctx.fetch. */
+export function formatCtxFetchHttpFailureDiagnostic(
+  diagnostic: CtxFetchHttpFailureDiagnostic,
+): string {
+  return `${CTX_FETCH_HTTP_FAILURE_LOG_PREFIX} ${JSON.stringify(diagnostic)}`;
+}
+
+/**
+ * Parse only runtime-authored, canonical ctx.fetch diagnostics. Untagged
+ * legacy/user lines are never interpreted as evidence, even if they happen to
+ * contain the same words.
+ */
+export function parseCtxFetchHttpFailureDiagnostic(
+  rawLine: string,
+): CtxFetchHttpFailureDiagnostic | null {
+  const tagged = readProvenanceTag(rawLine);
+  if (tagged.provenance !== 'diagnostic') return null;
+  const index = tagged.line.indexOf(CTX_FETCH_HTTP_FAILURE_LOG_PREFIX);
+  if (index === -1) return null;
+  const json = tagged.line
+    .slice(index + CTX_FETCH_HTTP_FAILURE_LOG_PREFIX.length)
+    .trim();
+  try {
+    const parsed: unknown = JSON.parse(json);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return null;
+    }
+    const record = parsed as Record<string, unknown>;
+    if (!isCtxFetchHttpFailureDiagnostic(record)) {
+      return null;
+    }
+    return {
+      key: record.key,
+      method: record.method,
+      url: record.url,
+      http_status: record.http_status,
+    };
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Read a structural provenance tag off a line, if present, and return the tag
  * plus the original untagged line. Returns `null` provenance when untagged.
@@ -141,9 +220,7 @@ export function readProvenanceTag(line: string): {
     return { provenance: null, line };
   }
   const candidate = line.slice(PROVENANCE_PREFIX.length, end);
-  const provenance = LOG_PROVENANCE_CLASSES.includes(
-    candidate as LogProvenance,
-  )
+  const provenance = LOG_PROVENANCE_CLASSES.includes(candidate as LogProvenance)
     ? (candidate as LogProvenance)
     : null;
   return { provenance, line: line.slice(end + 1) };

package/dist/bundling-sources/shared_libs/play-runtime/play-runtime-batching-registry.ts

@@ -3,6 +3,7 @@ import { bettercontactBatchStrategies } from './bettercontact-batching';
 import { DEFAULT_PLAY_RUNTIME_BATCH_STRATEGIES } from './default-batch-strategies';
 import { fullenrichBatchStrategies } from './fullenrich-batching';
 import { opensosdataBatchStrategies } from './opensosdata-batching';
+import { testAsyncBatchStrategies } from './test-async-batching';
 
 export const PLAY_RUNTIME_BATCH_OPERATION_REGISTRY: Record<
   string,
@@ -12,6 +13,7 @@ export const PLAY_RUNTIME_BATCH_OPERATION_REGISTRY: Record<
   ...bettercontactBatchStrategies,
   ...fullenrichBatchStrategies,
   ...opensosdataBatchStrategies,
+  ...testAsyncBatchStrategies,
 };
 
 export function getPlayRuntimeBatchStrategy(

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

@@ -17,6 +17,7 @@ import type { PlayRunFailureDetails } from './run-failure';
 import type { ToolExecutionErrorSchemaVersion } from '../plays/tool-execution-error';
 import type { ToolResponseContract } from '../plays/tool-response-contract';
 import type { FixtureBehavior } from './fixture-behavior';
+import type { CtxFetchHttpFailureDiagnostic } from './log-provenance';
 
 export type PlayRunnerRateStateBackendConfig =
   | {
@@ -307,6 +308,8 @@ export type PlayRunnerResult =
       status: 'completed';
       output: unknown;
       outputWarnings?: PlayRunOutputWarning[];
+      /** Customer-safe runtime observations that must survive bounded log tails. */
+      runtimeDiagnostics?: CtxFetchHttpFailureDiagnostic[];
       outputRowCount?: number;
       logs: string[];
       stats: Record<string, unknown>;