deepline 0.1.149 → 0.1.151

package/dist/bundling-sources/apps/play-runner-workers/src/runtime/row-isolation.ts

@@ -1,53 +1,5 @@
-import {
-  isHardBillingToolHttpError,
-  isRateLimitToolHttpError,
-} from './tool-http-errors';
-
-/**
- * Thrown by `assertNotAborted` and surfaced through ctx.step / ctx.sleep / map
- * processing when the workflow has been terminated externally. Cooperatively
- * cancels in-flight user code: the play must check `ctx.signal.aborted` (or
- * await one of the abort-aware ctx methods) before doing more work.
- */
-export class WorkflowAbortError extends Error {
-  override readonly name = 'WorkflowAbort';
-  constructor(message = 'Play run cancelled.') {
-    super(message);
-  }
-}
-
-export function isAbortLikeError(error: unknown): boolean {
-  if (!error) return false;
-  if (error instanceof WorkflowAbortError) return true;
-  if (error instanceof Error) {
-    if (error.name === 'WorkflowAbort' || error.name === 'AbortError')
-      return true;
-    return /\b(cancell?ed|aborted|terminate[d]?)\b/i.test(error.message);
-  }
-  return false;
-}
-
-/**
- * Errors that must stay run-fatal even under the default map row failure
- * isolation:
- *
- * - Cancellation/abort must stop the run.
- * - Governor budget exhaustion is a run-level invariant — isolating it per
- *   row would silently convert "this run exceeded its execution budget" into
- *   thousands of identical row failures.
- * - Rate-limit pushback (a tool call that still got HTTP 429 after the
- *   in-process retry budget) is run-level throughput pressure that applies to
- *   every row equally, not a row defect. Isolating it silently drops healthy
- *   rows from the output dataset whenever a provider throttles — the durable
- *   chunk step's retries (and, if the storm persists, a loud run failure with
- *   recoverable persisted rows) are the correct response.
- * - Hard billing failures (billing cap / insufficient credits) promise "run
- *   halted before marking remaining rows processed"; isolating them would
- *   complete the run while silently failing every remaining row.
- */
-export function isRowIsolationExemptError(error: unknown): boolean {
-  if (isAbortLikeError(error)) return true;
-  if (error instanceof Error && error.name === 'GovernorBudgetError')
-    return true;
-  return isRateLimitToolHttpError(error) || isHardBillingToolHttpError(error);
-}
+export {
+  WorkflowAbortError,
+  isAbortLikeError,
+  isRowIsolationExemptError,
+} from '../../../../shared_libs/play-runtime/row-isolation';

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

@@ -84,6 +84,7 @@ import type { EnrichCompiledConfig } from './cli/enrich-play-compiler.js';
 const TERMINAL_PLAY_STATUSES = new Set(['completed', 'failed', 'cancelled']);
 const INCLUDE_TOOL_METADATA_HEADER = 'x-deepline-include-tool-metadata';
 const EXECUTE_RESPONSE_CONTRACT_HEADER = 'x-deepline-execute-response-contract';
+const EXECUTE_RESPONSE_INTENT_HEADER = 'x-deepline-execute-response-intent';
 const V2_EXECUTE_RESPONSE_CONTRACT = 'v2-tool-response';
 const COMPILE_MANIFEST_RETRY_DELAYS_MS = [250, 1_000];
 const REGISTER_PLAY_ARTIFACTS_COMPILE_CONCURRENCY = 3;
@@ -163,6 +164,7 @@ function chunkRegisterPlayArtifacts<T>(artifacts: T[]): T[][] {
 
 type ExecuteToolRawOptions = {
   includeToolMetadata?: boolean;
+  responseIntent?: 'raw' | 'row_artifact';
 };
 
 /**
@@ -1156,6 +1158,9 @@ export class DeeplineClient {
       ...(options?.includeToolMetadata
         ? { [INCLUDE_TOOL_METADATA_HEADER]: 'true' }
         : {}),
+      ...(options?.responseIntent
+        ? { [EXECUTE_RESPONSE_INTENT_HEADER]: options.responseIntent }
+        : {}),
     };
     return this.http.post<ToolExecution<TData, TMeta>>(
       `/api/v2/integrations/${encodeURIComponent(toolId)}/execute`,

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

@@ -321,8 +321,8 @@ function loadProjectDeeplineEnv(startDir = process.cwd()): EnvValues {
   return loadProjectEnvCandidates(startDir)[0]?.env ?? {};
 }
 
-function normalizeBaseUrl(baseUrl: string): string {
-  const trimmed = baseUrl.trim().replace(/\/+$/, '');
+function normalizeBaseUrl(baseUrl: string | null | undefined): string {
+  const trimmed = baseUrl?.trim().replace(/\/+$/, '') ?? '';
   if (!trimmed) return '';
   try {
     const parsed = new URL(trimmed);

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

@@ -102,10 +102,10 @@ export const SDK_RELEASE = {
   // the SDK enrich generator's one-second stale policy.
   // 0.1.110 ships authored V2 prebuilts and required top-level play descriptions.
   // 0.1.111 ships dataset-native tool list getters and result row datasets.
-  version: '0.1.149',
+  version: '0.1.151',
   apiContract: '2026-06-dataset-handle-results-hard-cutover',
   supportPolicy: {
-    latest: '0.1.149',
+    latest: '0.1.151',
     minimumSupported: '0.1.53',
     deprecatedBelow: '0.1.53',
     commandMinimumSupported: [

package/dist/bundling-sources/sdk/src/tool-output.ts

@@ -23,7 +23,13 @@
  *
  * @module
  */
-import { mkdirSync, writeFileSync } from 'node:fs';
+import {
+  closeSync,
+  mkdirSync,
+  openSync,
+  writeFileSync,
+  writeSync,
+} from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 
@@ -54,6 +60,22 @@ export type ListConversionResult = {
   sourcePath: string | null;
 };
 
+export type RowOutputProjection = {
+  rows: Array<Record<string, unknown>>;
+  rowCount: number;
+  columns: string[];
+  previewRows: Array<Record<string, unknown>>;
+  strategy: ListConversionResult['strategy'];
+  sourcePath: string | null;
+};
+
+export type CsvOutputArtifact = {
+  path: string;
+  rowCount: number;
+  columns: string[];
+  preview: string;
+};
+
 type Scalar = string | number | boolean | null;
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
@@ -109,6 +131,20 @@ function normalizeRows(value: unknown): Array<Record<string, unknown>> | null {
   });
 }
 
+function columnsForRows(rows: readonly Record<string, unknown>[]): string[] {
+  const seen = new Set<string>();
+  const columns: string[] = [];
+  for (const row of rows) {
+    for (const key of Object.keys(row)) {
+      if (!seen.has(key)) {
+        seen.add(key);
+        columns.push(key);
+      }
+    }
+  }
+  return columns;
+}
+
 /**
  * Generate candidate root objects to search for lists.
  * Tries: raw payload → V2 toolResponse.raw → legacy payload.output.body → legacy payload.result → legacy payload.result.data.
@@ -271,6 +307,19 @@ export function tryConvertToList(
   return null;
 }
 
+export function projectRowOutput(
+  conversion: ListConversionResult,
+): RowOutputProjection {
+  return {
+    rows: conversion.rows,
+    rowCount: conversion.rows.length,
+    columns: columnsForRows(conversion.rows),
+    previewRows: conversion.rows.slice(0, 5),
+    strategy: conversion.strategy,
+    sourcePath: conversion.sourcePath,
+  };
+}
+
 /** Ensure the shared output directory exists. Returns its path. */
 function ensureOutputDir(): string {
   const outputDir = join(homedir(), '.local', 'share', 'deepline', 'data');
@@ -330,21 +379,12 @@ export function writeCsvOutputFile(
   rows: Array<Record<string, unknown>>,
   stem: string,
   options?: { outPath?: string },
-): { path: string; rowCount: number; columns: string[]; preview: string } {
+): CsvOutputArtifact {
   const outputPath = options?.outPath
     ? options.outPath
     : join(ensureOutputDir(), `${stem}_${Date.now()}.csv`);
   mkdirSync(dirname(outputPath), { recursive: true });
-  const seen = new Set<string>();
-  const columns: string[] = [];
-  for (const row of rows) {
-    for (const key of Object.keys(row)) {
-      if (!seen.has(key)) {
-        seen.add(key);
-        columns.push(key);
-      }
-    }
-  }
+  const columns = columnsForRows(rows);
 
   const escapeCell = (value: unknown): string => {
     const normalized =
@@ -361,12 +401,18 @@ export function writeCsvOutputFile(
     return normalized;
   };
 
-  const lines: string[] = [];
-  lines.push(columns.map(escapeCell).join(','));
-  for (const row of rows) {
-    lines.push(columns.map((column) => escapeCell(row[column])).join(','));
+  const fd = openSync(outputPath, 'w');
+  try {
+    writeSync(fd, `${columns.map(escapeCell).join(',')}\n`);
+    for (const row of rows) {
+      writeSync(
+        fd,
+        `${columns.map((column) => escapeCell(row[column])).join(',')}\n`,
+      );
+    }
+  } finally {
+    closeSync(fd);
   }
-  writeFileSync(outputPath, `${lines.join('\n')}\n`, 'utf-8');
 
   const previewRows = rows.slice(0, 5);
   const previewColumns = columns.slice(0, 5);

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

@@ -28,6 +28,12 @@ import {
 } from './batch-runtime';
 import type { PlayQueueHint } from './governor/rate-state-backend';
 import type { MapRowOutcome } from './durability-store';
+import {
+  completedMapRowOutcome,
+  failedMapRowOutcome,
+  mapRowOutcomeRuntimeFields,
+  resolveMapRowOutcomeKey,
+} from './map-row-outcome';
 import {
   createDefaultGovernanceSnapshot,
   createPlayExecutionGovernor,
@@ -35,12 +41,9 @@ import {
   type PacingResolver,
   type PlayExecutionGovernor,
 } from './governor/governor';
-import {
-  CTX_FETCH_EGRESS_TOOL_ID,
-  resolveBuiltinPacing,
-} from './builtin-pacing';
+import { CTX_FETCH_EGRESS_TOOL_ID } from './builtin-pacing';
 import { InMemoryRateStateBackend } from './governor/in-memory-rate-state-backend';
-import type { PacingRule } from './governor/rate-state-backend';
+import { pacingPolicyForTool } from './pacing';
 import {
   cloneToolExecuteResultWithExecution,
   createToolExecuteResult,
@@ -54,13 +57,11 @@ import {
   type ToolResultMetadataInput,
 } from './tool-result';
 import {
-  TOOL_EXECUTE_TRANSIENT_HTTP_MAX_ATTEMPTS,
-  decideToolExecuteHttpRetry,
+  TOOL_EXECUTE_TRANSPORT_MAX_ATTEMPTS,
+  classifyToolExecuteHttpFailure,
+  createToolExecuteHttpFailureAttemptTracker,
 } from './tool-execute-retry-policy';
-import {
-  isHardBillingToolHttpError,
-  normalizeToolHttpErrorMessage,
-} from './tool-http-errors';
+import { isRowIsolationExemptError } from './row-isolation';
 import { sqlSafePlayColumnName } from '@shared_libs/plays/static-pipeline';
 import { createRuntimeDatasetId } from './dataset-id';
 import { dedupeExplicitMapKeyRows } from './map-row-identity';
@@ -577,24 +578,6 @@ function normalizeFetchHeaders(
   );
 }
 
-function parseRetryAfterMs(header: string | null): number {
-  if (!header) {
-    return TOOL_RETRY_AFTER_FALLBACK_MS;
-  }
-
-  const seconds = Number(header);
-  if (Number.isFinite(seconds) && seconds > 0) {
-    return Math.ceil(seconds * 1000);
-  }
-
-  const retryAt = Date.parse(header);
-  if (Number.isFinite(retryAt)) {
-    return Math.max(1, retryAt - Date.now());
-  }
-
-  return TOOL_RETRY_AFTER_FALLBACK_MS;
-}
-
 function parseJsonOrNull(bodyText: string): unknown | null {
   if (!bodyText.trim()) return null;
   try {
@@ -652,20 +635,10 @@ function createPacingResolver(
   getToolQueueHints: ContextOptions['getToolQueueHints'],
 ): PacingResolver {
   return async (toolId: string) => {
-    const builtin = resolveBuiltinPacing(toolId);
+    const builtin = pacingPolicyForTool(toolId, []);
     if (builtin) return builtin;
     const hints = getToolQueueHints ? await getToolQueueHints(toolId) : [];
-    if (hints.length === 0) {
-      return null;
-    }
-    const provider = hints[0]!.provider;
-    const rules: PacingRule[] = hints.map((hint) => ({
-      ruleId: hint.ruleId,
-      requestsPerWindow: hint.requestsPerWindow,
-      windowMs: hint.windowMs,
-      maxConcurrency: hint.maxConcurrency,
-    }));
-    return { provider, rules };
+    return pacingPolicyForTool(toolId, hints);
   };
 }
 
@@ -2030,9 +2003,8 @@ export class PlayContextImpl {
     }
 
     const rowIdentity = (row: Record<string, unknown>, index = 0) => {
-      if (typeof row.__deeplineRowKey === 'string') {
-        return row.__deeplineRowKey;
-      }
+      const runtimeKey = resolveMapRowOutcomeKey(row);
+      if (runtimeKey) return runtimeKey;
       return explicitKeyResolver
         ? derivePlayRowIdentityFromKey(
             explicitKeyResolver(row, index),
@@ -2081,7 +2053,9 @@ export class PlayContextImpl {
       const mapStartRows = shouldPassRowKey
         ? rawItems.map((row, index) => ({
             ...toSerializableCsvAliasedRow(row),
-            __deeplineRowKey: rowIdentity(row, index),
+            ...mapRowOutcomeRuntimeFields({
+              key: rowIdentity(row, index),
+            }),
           }))
         : rawItems.map((row) => toSerializableCsvAliasedRow(row));
       const mapStartResult = await this.#options.onMapStart(
@@ -2099,9 +2073,7 @@ export class PlayContextImpl {
         mapStartResult.tableNamespace,
       );
       const persistedRowIdentity = (row: Record<string, unknown>, index = 0) =>
-        typeof row.__deeplineRowKey === 'string'
-          ? row.__deeplineRowKey
-          : rowIdentity(row, index);
+        resolveMapRowOutcomeKey(row) ?? rowIdentity(row, index);
       const pendingKeys = new Set(
         mapStartResult.pendingRows.map((row, index) =>
           persistedRowIdentity(row, index),
@@ -2336,14 +2308,16 @@ export class PlayContextImpl {
         if (incrementalPersistence?.isPersisted(row)) continue;
         const rowKey = row.key;
         const meta = mapCellMeta?.get(rowKey);
-        persistRows.push({
-          key: rowKey,
-          data: row.data,
-          cellMetaPatch: {
-            ...(row.cellMetaPatch ?? {}),
-            ...(meta ?? {}),
-          },
-        });
+        persistRows.push(
+          completedMapRowOutcome({
+            key: rowKey,
+            data: row.data,
+            cellMetaPatch: {
+              ...(row.cellMetaPatch ?? {}),
+              ...(meta ?? {}),
+            },
+          }),
+        );
       }
       persistRows.push(
         ...mapResult.failedRows.filter(
@@ -2441,20 +2415,19 @@ export class PlayContextImpl {
       .filter((fieldName) => shouldPersistMapCellField(fieldName));
     const normalizedTableNamespace = mapScope.artifactTableNamespace;
     const rowIdentity = (row: Record<string, unknown>, index = 0) =>
-      typeof row.__deeplineRowKey === 'string'
-        ? row.__deeplineRowKey
-        : mapScope.rowIdentity(
-            stripCsvProjectedFields(
-              Object.fromEntries(
-                Object.entries(row).filter(
-                  ([fieldName]) =>
-                    !datasetColumnNames.includes(fieldName) &&
-                    !fieldName.startsWith('__deepline'),
-                ),
-              ),
+      resolveMapRowOutcomeKey(row) ??
+      mapScope.rowIdentity(
+        stripCsvProjectedFields(
+          Object.fromEntries(
+            Object.entries(row).filter(
+              ([fieldName]) =>
+                !datasetColumnNames.includes(fieldName) &&
+                !fieldName.startsWith('__deepline'),
             ),
-            index,
-          );
+          ),
+        ),
+        index,
+      );
     const executionRowKey = (row: Record<string, unknown>, index: number) =>
       runtimeOptions?.executionRowKeys?.[index] ?? rowIdentity(row, index);
     const executionRowIndex = (index: number) =>
@@ -2645,14 +2618,16 @@ export class PlayContextImpl {
         `Map completed: ${results.length + completedRows} results (${results.length} executed, ${completedRows} already satisfied)`,
       );
       return {
-        completedRows: results.map((row, index) => ({
-          key: executionRowKey(
-            this.toOutputRow(items[index] as Record<string, unknown>),
-            index,
-          ),
-          inputIndex: executionRowIndex(index),
-          data: this.toPersistedOutputRow(row),
-        })),
+        completedRows: results.map((row, index) =>
+          completedMapRowOutcome({
+            key: executionRowKey(
+              this.toOutputRow(items[index] as Record<string, unknown>),
+              index,
+            ),
+            inputIndex: executionRowIndex(index),
+            data: this.toPersistedOutputRow(row),
+          }),
+        ),
         failedRows: [],
       };
     }
@@ -2767,6 +2742,9 @@ export class PlayContextImpl {
             ) {
               throw error;
             }
+            if (isRowIsolationExemptError(error)) {
+              throw error;
+            }
 
             value = null;
             computedFields[fieldName] = value;
@@ -2787,7 +2765,7 @@ export class PlayContextImpl {
                 : {},
             });
             if (failFastOnRowError) {
-              const failedRow: PersistableMapRow = {
+              const failedRow: PersistableMapRow = failedMapRowOutcome({
                 key: rowKey,
                 inputIndex: rowIndex,
                 data: this.toPersistedOutputRow(
@@ -2796,9 +2774,8 @@ export class PlayContextImpl {
                 ...(this.activeMapCellMeta?.get(rowKey)
                   ? { cellMetaPatch: this.activeMapCellMeta.get(rowKey) }
                   : {}),
-                status: 'failed',
                 error: formattedError,
-              };
+              });
               failedRowsToPersist.push(failedRow);
               throw error;
             }
@@ -2806,14 +2783,13 @@ export class PlayContextImpl {
               cloneCsvAliasedRow(baseRow, computedFields),
             );
             const cellMetaPatch = this.activeMapCellMeta?.get(rowKey);
-            const failedRow: PersistableMapRow = {
+            const failedRow: PersistableMapRow = failedMapRowOutcome({
               key: rowKey,
               inputIndex: rowIndex,
               data: failedData,
               ...(cellMetaPatch ? { cellMetaPatch } : {}),
-              status: 'failed',
               error: formattedError,
-            };
+            });
             failedRowsToPersist.push(failedRow);
             updateMapFrameProgress({
               failedRowKey: rowKey,
@@ -2867,14 +2843,14 @@ export class PlayContextImpl {
           dataPatch: {},
         });
         const publicRow = this.toPublicOutputRow(merged);
-        const completedRow: PersistableMapRow = {
+        const completedRow: PersistableMapRow = completedMapRowOutcome({
           key: rowKey,
           inputIndex: rowIndex,
           data: this.toPersistedOutputRow(merged),
           ...(this.activeMapCellMeta?.get(rowKey)
             ? { cellMetaPatch: this.activeMapCellMeta.get(rowKey) }
             : {}),
-        };
+        });
         completedRowsToPersist.push(completedRow);
         enqueueIncrementalPersist(completedRow);
         return publicRow;
@@ -5538,7 +5514,13 @@ export class PlayContextImpl {
           },
         },
         async (span) => {
-          let rateLimitAttempt = 0;
+          const httpFailureAttempts =
+            createToolExecuteHttpFailureAttemptTracker();
+          const retryPolicy = await this.#options
+            .getToolRetryPolicy?.(toolId)
+            .catch(() => null);
+          const retrySafeTransientHttp =
+            retryPolicy?.retrySafeTransientHttp === true;
           let transportAttempt = 0;
 
           while (true) {
@@ -5568,7 +5550,7 @@ export class PlayContextImpl {
               transportAttempt += 1;
               const message =
                 error instanceof Error ? error.message : String(error);
-              if (transportAttempt < TOOL_EXECUTE_TRANSIENT_HTTP_MAX_ATTEMPTS) {
+              if (transportAttempt < TOOL_EXECUTE_TRANSPORT_MAX_ATTEMPTS) {
                 this.governor.chargeBudget('retry');
                 const retryAfterMs =
                   TOOL_RETRY_AFTER_FALLBACK_MS * transportAttempt;
@@ -5577,105 +5559,65 @@ export class PlayContextImpl {
                   transportAttempt,
                 );
                 this.log(
-                  `Tool ${toolId} transport failed calling ${url} on attempt ${transportAttempt}/${TOOL_EXECUTE_TRANSIENT_HTTP_MAX_ATTEMPTS}; retrying after ${retryAfterMs}ms: ${message}`,
+                  `Tool ${toolId} transport failed calling ${url} on attempt ${transportAttempt}/${TOOL_EXECUTE_TRANSPORT_MAX_ATTEMPTS}; retrying after ${retryAfterMs}ms: ${message}`,
                 );
                 await this.sleepWithCheckpointHeartbeat(retryAfterMs);
                 continue;
               }
               throw new Error(
-                `Tool ${toolId} transport failed calling ${url} after ${transportAttempt}/${TOOL_EXECUTE_TRANSIENT_HTTP_MAX_ATTEMPTS} attempts: ${message}`,
+                `Tool ${toolId} transport failed calling ${url} after ${transportAttempt}/${TOOL_EXECUTE_TRANSPORT_MAX_ATTEMPTS} attempts: ${message}`,
               );
             }
 
             span.setAttribute('plays.http_status_code', response.status);
 
-            if (response.status === 429) {
-              rateLimitAttempt += 1;
-              const text = await response.text();
-              const initialRetryDecision = decideToolExecuteHttpRetry({
-                toolId,
-                status: response.status,
-              });
-              const error = normalizeToolHttpErrorMessage({
-                toolId,
-                status: response.status,
-                attempt: rateLimitAttempt,
-                maxAttempts: initialRetryDecision.attemptCap,
-                bodyText: text,
-              });
-              const retryDecision = decideToolExecuteHttpRetry({
-                toolId,
-                status: response.status,
-                hardBillingFailure: isHardBillingToolHttpError(error),
-              });
-              if (
-                !retryDecision.retryable ||
-                rateLimitAttempt >= retryDecision.attemptCap
-              ) {
-                throw error;
-              }
-              this.governor.chargeBudget('retry');
-              const retryAfterMs = parseRetryAfterMs(
-                response.headers.get('retry-after'),
-              );
-              // Feed the server-observed Retry-After back into the shared pacer
-              // so subsequent acquires for this provider back off.
-              await this.reportToolBackpressure(toolId, retryAfterMs);
-              span.setAttribute(
-                'plays.rate_limit_retry_after_ms',
-                retryAfterMs,
-              );
-              span.setAttribute('plays.rate_limit_attempt', rateLimitAttempt);
-              this.log(
-                `Tool ${toolId} rate limited; retrying after ${retryAfterMs}ms`,
-              );
-              await this.sleepWithCheckpointHeartbeat(retryAfterMs);
-              continue;
-            }
-
             if (!response.ok) {
               const text = await response.text();
-              const initialRetryDecision = decideToolExecuteHttpRetry({
+              const httpFailureAttempt = httpFailureAttempts.next({
                 toolId,
                 status: response.status,
+                transientHttpRetrySafe: retrySafeTransientHttp,
               });
-              const error = normalizeToolHttpErrorMessage({
+              const failure = classifyToolExecuteHttpFailure({
                 toolId,
                 status: response.status,
-                attempt: rateLimitAttempt + 1,
-                maxAttempts: initialRetryDecision.attemptCap,
+                attempt: httpFailureAttempt,
                 bodyText: text,
+                retryAfterHeader: response.headers.get('retry-after'),
+                transientHttpRetrySafe: retrySafeTransientHttp,
               });
-              const retryDecision = decideToolExecuteHttpRetry({
-                toolId,
-                status: response.status,
-                hardBillingFailure: isHardBillingToolHttpError(error),
-              });
-              if (
-                retryDecision.retryable &&
-                rateLimitAttempt + 1 < retryDecision.attemptCap
-              ) {
-                rateLimitAttempt += 1;
-                this.governor.chargeBudget('retry');
-                const retryAfterMs = parseRetryAfterMs(
-                  response.headers.get('retry-after'),
+              if (failure.backpressureDelayMs !== null) {
+                // Feed the server-observed Retry-After back into the shared
+                // pacer even on the final attempt so later provider calls back
+                // off instead of retrying the whole map chunk.
+                await this.reportToolBackpressure(
+                  toolId,
+                  failure.backpressureDelayMs,
                 );
+              }
+              if (failure.shouldRetry) {
+                if (failure.chargeRetryBudget) {
+                  this.governor.chargeBudget('retry');
+                }
+                const retryAttributePrefix = failure.isRateLimit
+                  ? 'rate_limit'
+                  : 'transient_http';
                 span.setAttribute(
-                  'plays.transient_http_retry_after_ms',
-                  retryAfterMs,
+                  `plays.${retryAttributePrefix}_retry_after_ms`,
+                  failure.retryDelayMs,
                 );
                 span.setAttribute(
-                  'plays.transient_http_attempt',
-                  rateLimitAttempt,
+                  `plays.${retryAttributePrefix}_attempt`,
+                  httpFailureAttempt,
                 );
                 this.log(
-                  `Tool ${toolId} returned ${response.status}; retrying after ${retryAfterMs}ms`,
+                  `Tool ${toolId} returned ${response.status}; retrying after ${failure.retryDelayMs}ms`,
                 );
-                await this.sleepWithCheckpointHeartbeat(retryAfterMs);
+                await this.sleepWithCheckpointHeartbeat(failure.retryDelayMs);
                 continue;
               }
-              this.log(error.message);
-              throw error;
+              this.log(failure.error.message);
+              throw failure.error;
             }
 
             const data = (await response.json()) as Record<string, unknown>;

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

@@ -487,6 +487,9 @@ export interface ContextOptions {
   runId?: string;
   resolvePlay?: (playRef: string) => Promise<ResolvedPlayExecution | null>;
   getToolQueueHints?: (toolId: string) => Promise<readonly PlayQueueHint[]>;
+  getToolRetryPolicy?: (toolId: string) => Promise<{
+    retrySafeTransientHttp?: boolean;
+  } | null>;
   getToolTargetGetters?: (
     toolId: string,
     output: string,