deepline 0.1.300 → 0.1.302

package/dist/bundling-sources/shared_libs/play-runtime/runtime-receipt-store-adapter.ts

@@ -124,6 +124,7 @@ export class RuntimeReceiptStoreAdapter {
     maxBatchBytes?: number;
     maxFlushMs?: number;
     maxBufferedBytes?: number;
+    onRetryTelemetry?: (line: string) => void;
   }) {
     const context: WorkerRuntimeApiContext = {
       ...options.context,
@@ -137,6 +138,14 @@ export class RuntimeReceiptStoreAdapter {
       maxFlushMs: options.maxFlushMs,
       maxBufferedBytes: options.maxBufferedBytes,
       classifyRetryableError: classifyReceiptRetry,
+      onRetryEvent: (event) =>
+        emitReceiptWriterRetryTelemetry({
+          event,
+          playName: options.playName,
+          runId: options.runId,
+          gatewayHost: runtimeGatewayHost(context.baseUrl),
+          onTelemetry: options.onRetryTelemetry,
+        }),
       send: async (commands, { signal }) =>
         await sendReceiptCommands({
           context: { ...context, signal },
@@ -260,6 +269,100 @@ export class RuntimeReceiptStoreAdapter {
   }
 }
 
+const RECEIPT_WRITER_RETRY_TELEMETRY_TAG =
+  '[perf][worker.receipt_writer.retry]';
+
+function isPowerOfTwo(value: number): boolean {
+  return value > 0 && (value & (value - 1)) === 0;
+}
+
+function runtimeGatewayHost(baseUrl: string): string | null {
+  try {
+    return new URL(baseUrl).host || null;
+  } catch {
+    return null;
+  }
+}
+
+function receiptCommandTelemetryAction(command: ReceiptCommand): string {
+  return command.kind === 'settle'
+    ? `${command.kind}_${command.outcome}`
+    : command.kind;
+}
+
+function receiptRetryErrorTelemetry(error: unknown): Record<string, unknown> {
+  if (isAppRuntimeApiCapacityError(error)) {
+    return {
+      failureKind: 'capacity',
+      errorName: error.name,
+      status: error.status,
+      code: error.code,
+      requestId: error.requestId,
+    };
+  }
+  if (error instanceof AppRuntimeApiTransportError) {
+    return {
+      failureKind: 'transport',
+      errorName: error.name,
+      transportAttempts: error.attempts,
+      transportAction: error.action,
+    };
+  }
+  if (error instanceof AppRuntimeApiResponseError) {
+    return {
+      failureKind: 'http',
+      errorName: error.name,
+      status: error.status,
+      code: error.code,
+      requestId: error.requestId,
+    };
+  }
+  return {
+    failureKind: 'unknown',
+    errorName: error instanceof Error ? error.name : typeof error,
+  };
+}
+
+function emitReceiptWriterRetryTelemetry(input: {
+  event: import('./runtime-receipt-writer').RuntimeReceiptWriterRetryEvent<ReceiptCommand>;
+  playName: string;
+  runId: string;
+  gatewayHost: string | null;
+  onTelemetry?: (line: string) => void;
+}): void {
+  const { event } = input;
+  if (event.phase === 'retry' && !isPowerOfTwo(event.attempt)) return;
+  const payload = {
+    phase: event.phase,
+    playName: input.playName,
+    runId: input.runId,
+    gatewayHost: input.gatewayHost,
+    action: receiptCommandTelemetryAction(event.firstInput),
+    batchId: event.batchId,
+    batchSize: event.batchSize,
+    attempt: event.attempt,
+    elapsedMs: event.elapsedMs,
+    retryAfterMs: event.retryAfterMs,
+    queued: event.queued,
+    blocked: event.blocked,
+    bufferedBytes: event.bufferedBytes,
+    ...(event.error === undefined
+      ? { failureKind: null }
+      : receiptRetryErrorTelemetry(event.error)),
+  };
+  try {
+    const serialized = JSON.stringify(payload);
+    input.onTelemetry?.(`${RECEIPT_WRITER_RETRY_TELEMETRY_TAG} ${serialized}`);
+    if (event.phase === 'retry') {
+      console.warn(RECEIPT_WRITER_RETRY_TELEMETRY_TAG, serialized);
+    } else {
+      console.info(RECEIPT_WRITER_RETRY_TELEMETRY_TAG, serialized);
+    }
+  } catch {
+    // Receipt telemetry must never affect durable delivery.
+  }
+}
+
 function receiptCommandBatchKey(command: ReceiptCommand): string {
   switch (command.kind) {
     case 'get':

package/dist/bundling-sources/shared_libs/play-runtime/runtime-receipt-writer.ts

@@ -22,6 +22,20 @@ export type RuntimeReceiptWriterStats = {
   bufferedBytes: number;
 };
 
+export type RuntimeReceiptWriterRetryEvent<Input> = {
+  phase: 'retry' | 'recovered';
+  attempt: number;
+  batchId: number;
+  batchSize: number;
+  firstInput: Input;
+  elapsedMs: number;
+  retryAfterMs: number;
+  queued: number;
+  blocked: number;
+  bufferedBytes: number;
+  error?: unknown;
+};
+
 export class RuntimeReceiptWriterBufferLimitError extends Error {
   constructor(
     readonly inputBytes: number,
@@ -76,11 +90,15 @@ export class RuntimeReceiptWriter<Input, Output> {
   readonly #maxBatchBytes: number;
   readonly #maxBufferedBytes: number;
   readonly #maxFlushMs: number;
+  readonly #onRetryEvent:
+    | ((event: RuntimeReceiptWriterRetryEvent<Input>) => void)
+    | null;
   readonly #queued: Array<PendingWrite<Input, Output>> = [];
   readonly #blocked: Array<PendingWrite<Input, Output>> = [];
   readonly #closeController = new AbortController();
 
   #bufferedBytes = 0;
+  #nextBatchId = 0;
   #activeBatch: Array<PendingWrite<Input, Output>> | null = null;
   #pump: Promise<void> | null = null;
   #flushTimer: ReturnType<typeof setTimeout> | null = null;
@@ -103,6 +121,7 @@ export class RuntimeReceiptWriter<Input, Output> {
     maxBatchBytes?: number;
     maxBufferedBytes?: number;
     maxFlushMs?: number;
+    onRetryEvent?: (event: RuntimeReceiptWriterRetryEvent<Input>) => void;
   }) {
     this.#batchKey = options.batchKey;
     this.#send = options.send;
@@ -119,6 +138,7 @@ export class RuntimeReceiptWriter<Input, Output> {
       this.#maxBufferedBytes,
     );
     this.#maxFlushMs = Math.max(0, Math.floor(options.maxFlushMs ?? 5));
+    this.#onRetryEvent = options.onRetryEvent ?? null;
   }
 
   write(input: Input, options: { signal?: AbortSignal } = {}): Promise<Output> {
@@ -243,9 +263,10 @@ export class RuntimeReceiptWriter<Input, Output> {
     while (this.#queued.length > 0) {
       const batch = this.#takeBatch();
       if (batch.length === 0) continue;
+      const batchId = ++this.#nextBatchId;
       this.#activeBatch = batch;
       try {
-        const outputs = await this.#sendWithRetry(batch);
+        const outputs = await this.#sendWithRetry(batch, batchId);
         if (outputs.length !== batch.length) {
           throw new RuntimeReceiptWriterResultCountError(
             batch.length,
@@ -305,9 +326,13 @@ export class RuntimeReceiptWriter<Input, Output> {
 
   async #sendWithRetry(
     batch: readonly PendingWrite<Input, Output>[],
+    batchId: number,
   ): Promise<readonly Output[]> {
     const inputs = batch.map((pending) => pending.input);
+    const startedAt = Date.now();
+    let attempt = 0;
     while (true) {
+      attempt += 1;
       if (this.#closeController.signal.aborted) {
         throw this.#closeReason;
       }
@@ -315,20 +340,68 @@ export class RuntimeReceiptWriter<Input, Output> {
         throw batch[0]?.aborted;
       }
       try {
-        return await this.#send(inputs, {
+        const outputs = await this.#send(inputs, {
           signal: this.#closeController.signal,
         });
+        if (attempt > 1) {
+          this.#emitRetryEvent({
+            phase: 'recovered',
+            attempt,
+            batchId,
+            batch,
+            startedAt,
+            retryAfterMs: 0,
+          });
+        }
+        return outputs;
       } catch (error) {
         const retry = this.#classifyRetryableError(error);
         if (!retry) throw error;
-        await this.#waitForRetry(
-          jitteredRetryDelayMs(retry.retryAfterMs),
+        const retryAfterMs = jitteredRetryDelayMs(retry.retryAfterMs);
+        this.#emitRetryEvent({
+          phase: 'retry',
+          attempt,
+          batchId,
           batch,
-        );
+          startedAt,
+          retryAfterMs,
+          error,
+        });
+        await this.#waitForRetry(retryAfterMs, batch);
       }
     }
   }
 
+  #emitRetryEvent(input: {
+    phase: 'retry' | 'recovered';
+    attempt: number;
+    batchId: number;
+    batch: readonly PendingWrite<Input, Output>[];
+    startedAt: number;
+    retryAfterMs: number;
+    error?: unknown;
+  }): void {
+    const firstInput = input.batch[0]?.input;
+    if (!this.#onRetryEvent || firstInput === undefined) return;
+    try {
+      this.#onRetryEvent({
+        phase: input.phase,
+        attempt: input.attempt,
+        batchId: input.batchId,
+        batchSize: input.batch.length,
+        firstInput,
+        elapsedMs: Date.now() - input.startedAt,
+        retryAfterMs: input.retryAfterMs,
+        queued: this.#queued.length,
+        blocked: this.#blocked.length,
+        bufferedBytes: this.#bufferedBytes,
+        ...(input.error === undefined ? {} : { error: input.error }),
+      });
+    } catch {
+      // Receipt telemetry must never affect durable delivery.
+    }
+  }
+
   async #waitForRetry(
     delayMs: number,
     batch: readonly PendingWrite<Input, Output>[],

package/dist/bundling-sources/shared_libs/play-runtime/tool-execute-retry-policy.ts

@@ -3,6 +3,7 @@ import {
   normalizeToolHttpErrorMessage,
   type ToolHttpError,
 } from './tool-http-errors';
+import type { ToolExecutionErrorSchemaVersion } from '../tool-execution-error';
 
 export const TOOL_EXECUTE_TRANSIENT_HTTP_MAX_ATTEMPTS = 2;
 // A provider may need to finish the original request before it can replay the
@@ -296,6 +297,7 @@ export function classifyToolExecuteHttpFailure(input: {
   status: number;
   attempt: number;
   bodyText: string;
+  schemaVersion?: ToolExecutionErrorSchemaVersion;
   retryAfterHeader?: string | null;
   transientHttpRetrySafe?: boolean;
   providerLatencyMs?: number;
@@ -318,12 +320,20 @@ export function classifyToolExecuteHttpFailure(input: {
     hasRetryAfterHeader,
     transientHttpRetrySafe,
   });
+  const retryAfterMs = parseToolExecuteRetryAfterMs(
+    input.retryAfterHeader,
+    input.nowMs,
+  );
   const error = normalizeToolHttpErrorMessage({
     toolId: input.toolId,
     status: input.status,
     attempt: input.attempt,
     maxAttempts: initialRetryDecision.attemptCap,
     bodyText: input.bodyText,
+    schemaVersion: input.schemaVersion,
+    retryable: initialRetryDecision.retryable,
+    retryAfterMs:
+      input.status === 429 && hasRetryAfterHeader ? retryAfterMs : null,
   });
   if (
     typeof input.providerLatencyMs === 'number' &&
@@ -355,10 +365,6 @@ export function classifyToolExecuteHttpFailure(input: {
   ) {
     error.receiptFailureKind = 'repairable';
   }
-  const retryAfterMs = parseToolExecuteRetryAfterMs(
-    input.retryAfterHeader,
-    input.nowMs,
-  );
   const retryDelayMs =
     input.status === 429
       ? Math.min(
@@ -369,14 +375,14 @@ export function classifyToolExecuteHttpFailure(input: {
           ),
         )
       : retryDecision.reason === 'idempotency_in_progress' &&
-            !hasRetryAfterHeader
-        ? idempotencyInProgressRetryDelayMs(input.attempt)
-        : retryDecision.reason === 'gateway_invocation_in_progress' &&
           !hasRetryAfterHeader
         ? idempotencyInProgressRetryDelayMs(input.attempt)
-        : retryAfterMs > 0
-          ? Math.min(TOOL_EXECUTE_RETRY_DELAY_MAX_MS, retryAfterMs)
-          : TOOL_EXECUTE_RETRY_DELAY_FALLBACK_MS;
+        : retryDecision.reason === 'gateway_invocation_in_progress' &&
+            !hasRetryAfterHeader
+          ? idempotencyInProgressRetryDelayMs(input.attempt)
+          : retryAfterMs > 0
+            ? Math.min(TOOL_EXECUTE_RETRY_DELAY_MAX_MS, retryAfterMs)
+            : TOOL_EXECUTE_RETRY_DELAY_FALLBACK_MS;
   return {
     ...retryDecision,
     error,
@@ -395,7 +401,6 @@ export function classifyToolExecuteHttpFailure(input: {
           : TOOL_EXECUTE_BARE_RATE_LIMIT_BACKPRESSURE_MS
         : null,
     chargeRetryBudget:
-      shouldRetry &&
-      retryDecision.reason !== 'gateway_invocation_in_progress',
+      shouldRetry && retryDecision.reason !== 'gateway_invocation_in_progress',
   };
 }

package/dist/bundling-sources/shared_libs/play-runtime/tool-http-errors.ts

@@ -1,5 +1,50 @@
 import type { WorkReceiptFailureKind } from './work-receipts';
+import {
+  LEGACY_TOOL_EXECUTION_ERROR_SCHEMA_VERSION,
+  ToolExecutionError,
+  deserializeToolExecutionFailure,
+  isProviderTransientFailure,
+  normalizeToolExecutionCategory,
+  normalizeToolExecutionOrigin,
+  type ToolExecutionErrorSchemaVersion,
+  type ToolExecutionErrorOptions,
+} from '../tool-execution-error';
 
+const TOOL_HTTP_ERROR_BRAND = Symbol.for('deepline.tool-http-error.v1');
+
+type ToolHttpErrorConstructorInput = {
+  message: string;
+  billing: Record<string, unknown> | null;
+  status: number;
+  receiptFailureKind: WorkReceiptFailureKind;
+  options: Partial<ToolExecutionErrorOptions>;
+};
+
+function applyToolHttpErrorFields(
+  error: {
+    name: string;
+    billing: Record<string, unknown> | null;
+    status: number;
+    receiptFailureKind: WorkReceiptFailureKind;
+  },
+  input: ToolHttpErrorConstructorInput,
+): void {
+  error.name = 'ToolHttpError';
+  error.billing = input.billing;
+  error.status = input.status;
+  error.receiptFailureKind = input.receiptFailureKind;
+  Object.defineProperty(error, TOOL_HTTP_ERROR_BRAND, {
+    configurable: false,
+    enumerable: false,
+    writable: false,
+    value: true,
+  });
+}
+
+/**
+ * Historical play-runtime HTTP error. Existing artifacts must keep this exact
+ * Error prototype; typed errors are an explicit artifact-contract opt-in.
+ */
 export class ToolHttpError extends Error {
   readonly billing: Record<string, unknown> | null;
   /** HTTP status of the failed tool-execute response (e.g. 429, 502). */
@@ -11,15 +56,89 @@ export class ToolHttpError extends Error {
     billing: Record<string, unknown> | null,
     status: number,
     receiptFailureKind: WorkReceiptFailureKind = 'terminal',
+    _options: Partial<ToolExecutionErrorOptions> = {},
   ) {
     super(message);
-    this.name = 'ToolHttpError';
     this.billing = billing;
     this.status = status;
     this.receiptFailureKind = receiptFailureKind;
+    applyToolHttpErrorFields(this, {
+      message,
+      billing,
+      status,
+      receiptFailureKind,
+      options: _options,
+    });
+  }
+
+  static [Symbol.hasInstance](value: unknown): boolean {
+    return Boolean(
+      value &&
+      typeof value === 'object' &&
+      (value as Record<symbol, unknown>)[TOOL_HTTP_ERROR_BRAND] === true,
+    );
   }
 }
 
+class StructuredToolHttpError extends ToolExecutionError {
+  readonly billing: Record<string, unknown> | null;
+  readonly status: number;
+  receiptFailureKind: WorkReceiptFailureKind;
+
+  constructor(input: ToolHttpErrorConstructorInput) {
+    super(input.message, {
+      toolId: input.options.toolId ?? 'unknown_tool',
+      provider: input.options.provider ?? null,
+      operation: input.options.operation ?? null,
+      code: input.options.code ?? null,
+      origin: input.options.origin ?? 'unknown',
+      category: input.options.category ?? 'unknown',
+      retryable: input.options.retryable === true,
+      statusCode:
+        input.options.statusCode === undefined
+          ? input.status
+          : input.options.statusCode,
+      requestId: input.options.requestId ?? null,
+      retryAfterMs: input.options.retryAfterMs ?? null,
+      networkKind: input.options.networkKind ?? null,
+      networkScope: input.options.networkScope ?? null,
+    });
+    this.billing = input.billing;
+    this.status = input.status;
+    this.receiptFailureKind = input.receiptFailureKind;
+    applyToolHttpErrorFields(this, input);
+    this.name = isProviderTransientFailure(this)
+      ? 'ProviderTransientError'
+      : 'ToolExecutionError';
+  }
+}
+
+export function createToolHttpError(
+  schemaVersion: ToolExecutionErrorSchemaVersion,
+  message: string,
+  billing: Record<string, unknown> | null,
+  status: number,
+  receiptFailureKind: WorkReceiptFailureKind = 'terminal',
+  options: Partial<ToolExecutionErrorOptions> = {},
+): ToolHttpError {
+  if (schemaVersion === LEGACY_TOOL_EXECUTION_ERROR_SCHEMA_VERSION) {
+    return new ToolHttpError(
+      message,
+      billing,
+      status,
+      receiptFailureKind,
+      options,
+    );
+  }
+  return new StructuredToolHttpError({
+    message,
+    billing,
+    status,
+    receiptFailureKind,
+    options,
+  }) as ToolHttpError;
+}
+
 function formatCreditAmount(value: unknown): string {
   if (typeof value !== 'number' || !Number.isFinite(value)) {
     return String(value ?? '-');
@@ -222,7 +341,12 @@ export function normalizeToolHttpErrorMessage(input: {
   attempt: number;
   maxAttempts: number;
   bodyText: string;
+  retryable?: boolean;
+  retryAfterMs?: number | null;
+  schemaVersion?: ToolExecutionErrorSchemaVersion;
 }): ToolHttpError {
+  const schemaVersion =
+    input.schemaVersion ?? LEGACY_TOOL_EXECUTION_ERROR_SCHEMA_VERSION;
   let parsed: Record<string, unknown> | null = null;
   try {
     const candidate = JSON.parse(input.bodyText);
@@ -230,9 +354,64 @@ export function normalizeToolHttpErrorMessage(input: {
   } catch {
     parsed = null;
   }
+  const serializedFailure = parsed?.tool_error;
+  const hydratedFailure = deserializeToolExecutionFailure(
+    '',
+    serializedFailure,
+    schemaVersion,
+  );
+  const provider =
+    getStringField(parsed, 'provider') ??
+    hydratedFailure?.provider ??
+    input.toolId.split(/[._:./-]+/)[0]?.trim() ??
+    null;
+  const operation =
+    getStringField(parsed, 'operation') ??
+    hydratedFailure?.operation ??
+    input.toolId;
+  const code = getStringField(parsed, 'code') ?? hydratedFailure?.code ?? null;
+  const rawOrigin =
+    getStringField(parsed, 'failure_origin') ?? hydratedFailure?.origin;
+  const rawCategory =
+    getStringField(parsed, 'error_category') ?? hydratedFailure?.category;
+  const origin = normalizeToolExecutionOrigin(rawOrigin, {
+    provider,
+    operation,
+  });
+  const category = normalizeToolExecutionCategory(rawCategory);
+  const trustworthy = origin !== 'unknown' && category !== 'unknown';
+  const publicOptions: Partial<ToolExecutionErrorOptions> = {
+    toolId: input.toolId,
+    provider,
+    operation,
+    code,
+    origin,
+    category,
+    retryable: trustworthy
+      ? (hydratedFailure?.retryable ?? input.retryable === true)
+      : false,
+    statusCode: input.status,
+    requestId:
+      getStringField(parsed, 'request_id') ??
+      getStringField(parsed, 'requestId') ??
+      hydratedFailure?.requestId ??
+      null,
+    retryAfterMs: hydratedFailure?.retryAfterMs ?? input.retryAfterMs ?? null,
+    networkKind:
+      hydratedFailure?.networkKind ??
+      (category === 'network' && code?.toUpperCase().includes('TIMEOUT')
+        ? 'timeout'
+        : null),
+    networkScope:
+      hydratedFailure?.networkScope ??
+      (origin === 'provider' && category === 'network'
+        ? 'deepline_to_provider'
+        : null),
+  };
   const billing = getObjectField(parsed, 'billing');
   if (isInsufficientCreditsBilling(billing)) {
-    return new ToolHttpError(
+    return createToolHttpError(
+      schemaVersion,
       `tool ${input.toolId} ${input.status} attempt ${input.attempt}/${input.maxAttempts}: ${formatInsufficientCreditsMessage(
         {
           billing,
@@ -241,6 +420,14 @@ export function normalizeToolHttpErrorMessage(input: {
       )}`,
       billing,
       input.status,
+      'terminal',
+      {
+        ...publicOptions,
+        origin: 'deepline',
+        category: 'billing',
+        code: publicOptions.code ?? 'INSUFFICIENT_CREDITS',
+        retryable: false,
+      },
     );
   }
   const hardBillingPayload = isHardBillingFailurePayload(billing)
@@ -249,7 +436,8 @@ export function normalizeToolHttpErrorMessage(input: {
       ? normalizeHardBillingPayload(parsed)
       : null;
   if (hardBillingPayload) {
-    return new ToolHttpError(
+    return createToolHttpError(
+      schemaVersion,
       formatHardBillingFailureMessage({
         billing: hardBillingPayload,
         toolId: input.toolId,
@@ -259,9 +447,17 @@ export function normalizeToolHttpErrorMessage(input: {
       }),
       hardBillingPayload,
       input.status,
+      'terminal',
+      {
+        ...publicOptions,
+        origin: 'deepline',
+        category: 'billing',
+        retryable: false,
+      },
     );
   }
-  return new ToolHttpError(
+  return createToolHttpError(
+    schemaVersion,
     `tool ${input.toolId} ${input.status} attempt ${input.attempt}/${input.maxAttempts}: ${formatPublicToolErrorPayload(
       {
         parsed,
@@ -271,6 +467,7 @@ export function normalizeToolHttpErrorMessage(input: {
     billing,
     input.status,
     receiptFailureKindForToolErrorPayload(parsed),
+    publicOptions,
   );
 }
 
@@ -281,10 +478,18 @@ export function extractErrorBilling(
 }
 
 export function isHardBillingToolHttpError(error: unknown): boolean {
-  return (
+  if (
     error instanceof ToolHttpError &&
     (isInsufficientCreditsBilling(error.billing) ||
       isHardBillingFailurePayload(error.billing))
+  ) {
+    return true;
+  }
+  return (
+    error instanceof ToolExecutionError &&
+    error.origin === 'deepline' &&
+    error.category === 'billing' &&
+    error.code !== 'BILLING_UNAVAILABLE'
   );
 }
 

package/dist/bundling-sources/shared_libs/play-runtime/work-receipts.ts

@@ -1,4 +1,5 @@
 import { isReusableWorkReceiptState } from './work-receipt-state-machine';
+import type { ToolExecutionFailureV1 } from '../tool-execution-error';
 
 export type WorkReceiptFailureKind = 'terminal' | 'repairable';
 
@@ -37,6 +38,7 @@ export type WorkReceipt = {
   status: WorkReceiptStatus;
   output?: unknown;
   error?: string | null;
+  errorPayload?: ToolExecutionFailureV1 | null;
   failureKind?: WorkReceiptFailureKind | null;
   runId?: string | null;
   leaseId?: string | null;
@@ -89,6 +91,7 @@ export type WorkReceiptBatchFailCommand = {
     runId: string;
     key: string;
     error: string;
+    errorPayload?: ToolExecutionFailureV1 | null;
     failureKind?: WorkReceiptFailureKind | null;
     leaseId?: string | null;
     runAttempt?: number | null;
@@ -161,6 +164,7 @@ export type WorkReceiptStore = {
   failReceipt(
     input: WorkReceiptCommand & {
       error: string;
+      errorPayload?: ToolExecutionFailureV1 | null;
       failureKind?: WorkReceiptFailureKind | null;
     },
   ): Promise<WorkReceipt | null>;

package/dist/bundling-sources/shared_libs/plays/artifact-contract-version.ts

@@ -0,0 +1,6 @@
+/**
+ * Immutable Play artifact ABI version shared by bundling and SDK release
+ * policy. Keep this module dependency-free: shared Play code must not import
+ * the SDK release manifest or create a package cycle.
+ */
+export const CURRENT_PLAY_ARTIFACT_CONTRACT_VERSION = 2 as const;

package/dist/bundling-sources/shared_libs/plays/artifact-types.ts

@@ -1,3 +1,5 @@
+import type { ToolExecutionErrorSchemaVersion } from '../tool-execution-error';
+
 export type PlayPackageImport = {
   name: string;
   version: string | null;
@@ -21,6 +23,8 @@ export type PlayArtifactCompatibility = {
   minRunnerVersion: number;
   runtimeFeatures: PlayRuntimeFeature[];
   runtimeBackend?: string | null;
+  /** Missing preserves the legacy schema used before this field existed. */
+  toolErrorSchemaVersion?: ToolExecutionErrorSchemaVersion;
 };
 
 /** The only executable Play artifact contract. */