deepline 0.3.50 → 0.3.52

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

@@ -56,6 +56,7 @@
 
 // ——— Client ———
 export { DeeplineClient } from './client.js';
+export { CtxFetchHttpError } from './play.js';
 export { RunObserveTransportUnavailableError } from './runs/observe-transport.js';
 export type {
   BillingCreditPool,

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

@@ -80,6 +80,7 @@ import {
 } from '../../shared_libs/play-runtime/tool-result.js';
 export { readValue, readList } from '../../shared_libs/play-runtime/tool-result.js';
 import { createDeferredPlayDataset } from '../../shared_libs/plays/dataset.js';
+export { CtxFetchHttpError } from '../../shared_libs/plays/authoring-contract.js';
 import {
   QUERY_RESULT_DATASET_PAGE_SIZE,
   isCustomerDbDatasetTool,

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

@@ -199,7 +199,7 @@ export const SDK_RELEASE = {
   // available at toolResponse.rawV2 while toolResponse.raw and all declared
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
-  version: '0.3.50',
+  version: '0.3.52',
   updateSummary:
     'Automatic CLI updates are now enabled by default. To opt out, run `deepline settings autoupdate off`; use `deepline settings autoupdate on` to re-enable updates or `deepline settings autoupdate pin <version>` to hold an exact release. This release also adds raw-v2 tool responses at toolResponse.rawV2 while preserving existing toolResponse.raw and declared getters.',
   packageCapabilities: {

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

@@ -178,6 +178,7 @@ import {
   resolveDurableCallCachePolicy,
 } from './durable-call-cache';
 import {
+  CtxFetchHttpError,
   PLAY_AUTHORING_CONTRACT_EDITION,
   normalizePlayAuthoringCustomerDbStatement,
   validateOptionalPlayAuthoringField,
@@ -287,6 +288,7 @@ import {
   isSecretAuthInput,
   isPlaintextSecretPromise,
   isSecretHandle,
+  isSecretValue,
   secretAuthEntries,
   secretAuthHeaderMarkers,
   valueContainsSecret,
@@ -2864,7 +2866,12 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       this.secretRedactor.register(value);
       return value;
     }
-    return this.resolveSecretValue(secret as SecretValue);
+    if (isSecretHandle(secret) || isSecretValue(secret)) {
+      return this.resolveSecretValue(secret);
+    }
+    throw new Error(
+      'ctx.secrets auth requires a resolved string or an approved secret value.',
+    );
   }
 
   private async resolveSecretValue(secret: SecretValue): Promise<string> {
@@ -4251,6 +4258,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       ) => T;
       onClaimedResult?: (output: T, receiptKey: string) => T;
       shouldPersistFailure?: (error: unknown) => boolean;
+      transient?: boolean;
       markRunningBeforeExecute?: boolean;
       requiresExecutionLock?: boolean;
       executionLockTtlMs?: number;
@@ -4260,6 +4268,28 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       }) => Promise<T>;
     },
   ): Promise<T> {
+    let releaseExternalCallSlot: (() => void) | null = null;
+    const execute = async (leaseId: string | null): Promise<T> =>
+      await opts.execute({
+        leaseId,
+        retainExternalCallSlot: (release) => {
+          if (releaseExternalCallSlot) {
+            release();
+            throw new Error(
+              `ctx.${operation}(${id}) attempted to retain more than one external-call slot.`,
+            );
+          }
+          releaseExternalCallSlot = release;
+        },
+      });
+    if (opts.transient === true) {
+      try {
+        return await execute(null);
+      } finally {
+        const release = releaseExternalCallSlot as (() => void) | null;
+        release?.();
+      }
+    }
     const stalePolicy = resolveDurableCallCachePolicy(
       opts.staleAfterSeconds,
       operation === 'step'
@@ -4279,7 +4309,6 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         staleAfterSeconds: stalePolicy.staleAfterSeconds,
         cacheEpochMs: this.durableCallCacheEpochMs,
       });
-    let releaseExternalCallSlot: (() => void) | null = null;
     try {
       return await executeWithDurableRuntimeReceipt<T>({
         operation,
@@ -4307,19 +4336,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         toolErrorSchemaVersion: this.currentToolErrorSchemaVersion,
         formatError: (error) => this.formatRuntimeError(error),
         log: (message) => this.log(message),
-        execute: ({ leaseId }) =>
-          opts.execute({
-            leaseId,
-            retainExternalCallSlot: (release) => {
-              if (releaseExternalCallSlot) {
-                release();
-                throw new Error(
-                  `ctx.${operation}(${id}) attempted to retain more than one external-call slot.`,
-                );
-              }
-              releaseExternalCallSlot = release;
-            },
-          }),
+        execute: ({ leaseId }) => execute(leaseId),
       });
     } finally {
       const release = releaseExternalCallSlot as (() => void) | null;
@@ -10206,9 +10223,31 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               ...secretHeaderMarkers,
             },
             row: rowFetchScope,
+            // Edition 5 changes non-2xx responses from cached values to
+            // non-cacheable errors. Partition those receipts from editions
+            // 1–4 so a republished artifact makes a fresh request instead of
+            // inheriting a legacy error record.
+            ...(this.currentAuthoringContractEdition >= 5
+              ? {
+                  authoringContractEdition:
+                    this.currentAuthoringContractEdition,
+                }
+              : {}),
           }),
         ),
         staleAfterSeconds: options?.staleAfterSeconds,
+        transient: options?.transient === true,
+        onRecovered: (output) => {
+          if (!output.ok && this.currentAuthoringContractEdition >= 5) {
+            throw new CtxFetchHttpError(output);
+          }
+          return output;
+        },
+        shouldPersistFailure: (error) =>
+          !(
+            error instanceof CtxFetchHttpError &&
+            this.currentAuthoringContractEdition >= 5
+          ),
         execute: async ({ retainExternalCallSlot }) => {
           const method = (init.method ?? 'GET').toUpperCase();
           const secretHeaders = await this.resolveSecretAuth(secretAuth);
@@ -10216,6 +10255,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             ...normalizeFetchHeaders(init.headers),
             ...secretHeaders,
           };
+          if (headers['user-agent'] === undefined) {
+            headers['user-agent'] = 'Deepline Play Runtime';
+          }
           const fetchInit = { ...init, headers };
           delete fetchInit.auth;
           const boundaryId = this.durableBoundaryId(
@@ -10234,7 +10276,13 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           );
 
           const existing = this.checkpoint.resolvedBoundaries?.[boundaryId];
-          if (existing?.kind === 'fetch' && 'output' in existing) {
+          // A transient request deliberately has no durable recovery path, so
+          // its response stays in the running Play rather than a checkpoint.
+          if (
+            options?.transient !== true &&
+            existing?.kind === 'fetch' &&
+            'output' in existing
+          ) {
             this.log(`ctx.fetch(${url}): recovered response from checkpoint`);
             if (this.durableDirectToolResultsBackedByReceipts) {
               // The outer durable receipt is the replay authority in hosted
@@ -10315,6 +10363,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                       fetchImpl: this.#options.fetchImpl,
                       sensitiveHeaders: Object.keys(secretHeaderMarkers),
                       stripHeadersOnCrossOriginRedirect: true,
+                      headersOnCrossOriginRedirect: {
+                        'user-agent': 'Deepline Play Runtime',
+                      },
                     }),
                 });
                 bodyText = await readCtxFetchBody({
@@ -10366,6 +10417,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                 `ctx.fetch(${method} ${url}) failed while reading the response body.`,
               );
             }
+            const rawJson = parseJsonOrNull(bodyText);
             const redactedBodyText = this.secretRedactor.redactString(bodyText);
             const output: PlayFetchResponse = {
               ok: response.ok,
@@ -10376,12 +10428,21 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                 Object.fromEntries(response.headers.entries()),
               ) as Record<string, string>,
               bodyText: redactedBodyText,
-              json: this.secretRedactor.redactKnownSecrets(
-                parseJsonOrNull(bodyText),
-              ),
+              json: this.secretRedactor.redactKnownSecrets(rawJson),
             };
 
-            if (!this.durableDirectToolResultsBackedByReceipts) {
+            // 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
+            // their response-record behavior for the same upstream response.
+            if (!output.ok && this.currentAuthoringContractEdition >= 5) {
+              throw new CtxFetchHttpError(output);
+            }
+
+            if (
+              options?.transient !== true &&
+              !this.durableDirectToolResultsBackedByReceipts
+            ) {
               this.checkpoint.resolvedBoundaries = {
                 ...(this.checkpoint.resolvedBoundaries ?? {}),
                 [boundaryId]: {

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

@@ -697,26 +697,39 @@ export async function executeWithDurableRuntimeReceipt<T>(input: {
     isInFlightRuntimeReceipt(receipt) &&
     typeof receipt.runId === 'string' &&
     receipt.runId.trim() === input.runId;
-  const waitForRunningReceipt = async (): Promise<{
-    kind: 'recovered';
-    output: T;
-  }> => ({
-    kind: 'recovered',
-    output: await recoverCompletedReceipt(
-      await waitForCompletedRuntimeReceipt({
-        receiptKey: input.receiptKey,
-        store: input.store,
-        maxAttempts: input.runningReceiptWaitMaxAttempts,
-        delayMs: input.runningReceiptWaitDelayMs,
-        toolErrorSchemaVersion: input.toolErrorSchemaVersion,
-      }),
-      'in_flight',
-    ),
-  });
-  const waitForRunningReceiptOrTimeout = async (): Promise<{
-    kind: 'recovered';
-    output: T;
-  }> => waitForRunningReceipt();
+  const waitForRunningReceiptOrRelease = async (): Promise<
+    { kind: 'recovered'; output: T } | { kind: 'claimed' }
+  > => {
+    const maxAttempts =
+      input.runningReceiptWaitMaxAttempts ?? DURABLE_RECEIPT_WAIT_MAX_ATTEMPTS;
+    const delayMs =
+      input.runningReceiptWaitDelayMs ?? DURABLE_RECEIPT_WAIT_DELAY_MS;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+      if (attempt > 0) await sleepReceiptWait(delayMs);
+      const current = await input.store.get(input.receiptKey);
+      if (current?.status === 'completed' || current?.status === 'skipped') {
+        return {
+          kind: 'recovered',
+          output: await recoverCompletedReceipt(current, 'in_flight'),
+        };
+      }
+      if (current?.status === 'failed') {
+        throw runtimeReceiptFailureError(
+          current,
+          `ctx.${input.operation}(${input.id}): previous execution failed and cannot be reused`,
+          input.toolErrorSchemaVersion,
+        );
+      }
+      if (
+        (current?.status === 'queued' || current?.status === 'pending') &&
+        !current.leaseId &&
+        !current.leaseExpiresAt
+      ) {
+        return await reclaimReceipt();
+      }
+    }
+    throw new RuntimeReceiptWaitTimeoutError(input.receiptKey);
+  };
   const repairOrWaitForRunningReceipt = async (
     receipt: RuntimeStepReceipt,
   ): Promise<{ kind: 'recovered'; output: T } | { kind: 'claimed' }> => {
@@ -726,7 +739,7 @@ export async function executeWithDurableRuntimeReceipt<T>(input: {
       return { kind: 'claimed' };
     }
     try {
-      return await waitForRunningReceiptOrTimeout();
+      return await waitForRunningReceiptOrRelease();
     } catch (error) {
       if (error instanceof RuntimeReceiptWaitTimeoutError) {
         const recovered = await reclaimReceipt();
@@ -840,6 +853,24 @@ export async function executeWithDurableRuntimeReceipt<T>(input: {
     assertNoSecretTaint(result, `ctx.${input.operation} result`);
   } catch (error) {
     if (input.shouldPersistFailure?.(error) === false) {
+      // This error is deliberately not a durable execution result (for
+      // example, an HTTP non-2xx response under the current ctx.fetch
+      // contract). Release only the lease we still own so a later run can
+      // make a fresh, idempotency-protected attempt rather than inheriting a
+      // running or failed receipt.
+      const released = await input.store.release(
+        input.receiptKey,
+        input.runId,
+        ownedLeaseId,
+      );
+      if (
+        !released ||
+        (released.status !== 'queued' && released.status !== 'pending')
+      ) {
+        throw new Error(
+          `ctx.${input.operation}(${input.id}): non-cacheable execution failed but receipt ownership could not be released: ${input.formatError(error)}.`,
+        );
+      }
       throw error;
     }
     // The ownership is uncertain, so neither `fail` nor `release` is safe.

package/dist/bundling-sources/shared_libs/play-runtime/secret-capability.ts

@@ -129,7 +129,11 @@ export function valueContainsSecret(value: unknown): boolean {
   const seen = new WeakSet<object>();
   while (pending.length > 0) {
     const candidate = pending.pop();
-    if (isSecretValue(candidate) || isSecretAuth(candidate)) return true;
+    if (
+      isSecretValue(candidate) || isSecretAuth(candidate)
+    ) {
+      return true;
+    }
     if (typeof candidate === 'string') {
       if (SECRET_HANDLE_MARKER_RE.test(candidate)) return true;
       continue;

package/dist/bundling-sources/shared_libs/plays/authoring-contract.ts

@@ -7,9 +7,11 @@ import type { ToolExecutionErrorSchemaVersion } from './tool-execution-error';
 import type { PlayDataset, PlayDatasetInput, PlayDatasetRow } from './dataset';
 
 export const LEGACY_PLAY_AUTHORING_CONTRACT_EDITION = 1 as const;
-export const PLAY_AUTHORING_CONTRACT_EDITION = 4 as const;
+export const PLAY_AUTHORING_CONTRACT_EDITION = 5 as const;
 export const PLAY_AUTHORING_INPUT_SCHEMA_SNAPSHOT_EDITION = 3 as const;
-export const SUPPORTED_PLAY_AUTHORING_CONTRACT_EDITIONS = [1, 2, 3, 4] as const;
+export const SUPPORTED_PLAY_AUTHORING_CONTRACT_EDITIONS = [
+  1, 2, 3, 4, 5,
+] as const;
 
 export type PlayAuthoringContractEdition =
   (typeof SUPPORTED_PLAY_AUTHORING_CONTRACT_EDITIONS)[number];
@@ -49,6 +51,47 @@ export const PLAY_AUTHORING_CONTRACT_CHANGELOG = [
     newWritesEnd: null,
     readerRemoval: null,
   },
+  {
+    edition: 5,
+    changed:
+      'ctx.fetch throws a typed, redacted CtxFetchHttpError for non-2xx responses. Editions 1–4 continue to return the response record for every HTTP status.',
+    compatibilityOwner: 'Plays Runtime',
+    newWritesEnd: null,
+    readerRemoval: null,
+  },
+] as const;
+
+/**
+ * Customer-visible runtime capabilities that are not expressible as one
+ * `ctx.*` signature. The generated authoring reference renders this inventory
+ * directly; add a row here alongside any new supported runtime global or
+ * execution-boundary guarantee.
+ */
+export const PLAY_AUTHORING_RUNTIME_CAPABILITIES = [
+  {
+    capability: 'Durable external I/O',
+    surface: '`ctx.fetch`, `ctx.tools.execute`, `ctx.step`, `ctx.runPlay`',
+    contract:
+      'Use a `ctx.*` primitive for external work. Each primitive owns durable receipt identity and replay; raw I/O in an authored handler does not.',
+  },
+  {
+    capability: 'Web Crypto',
+    surface: '`crypto.subtle`',
+    contract:
+      'WebCrypto is available for standards-based signing, verification, encryption, and key import. Keep private material in `ctx.secrets`; `docs-examples/sdk-v2/github-app-jwt.play.ts` signs an RS256 GitHub App JWT and uses `staleAfterSeconds: 0` for its time-varying auth exchange.',
+  },
+  {
+    capability: 'Workspace secrets',
+    surface: '`ctx.secrets.get`, `.bearer`, `.header`',
+    contract:
+      'Declare the secret at the Play boundary, read it only at runtime, and never return or log it. Secret-bearing HTTP requests require HTTPS.',
+  },
+  {
+    capability: 'Freshness',
+    surface: '`staleAfterSeconds` on durable calls',
+    contract:
+      'This is call-receipt freshness: omitted/null reuses forever, zero always executes, and a positive integer is a TTL in seconds. It never changes dataset or request identity.',
+  },
 ] as const;
 
 export const PLAY_AUTHORING_CONTRACT_ISSUE_CODES = [
@@ -78,6 +121,7 @@ export const PLAY_AUTHORING_CONTRACT_ISSUE_CODES = [
   'play_authoring_fetch_secret_requires_tls',
   'play_authoring_fetch_idempotency_required',
   'play_authoring_fetch_key_reused_in_loop',
+  'play_authoring_fetch_http_error_branch',
   'play_authoring_binding_invalid',
   'play_authoring_input_schema_unresolved',
   'tool_response_raw_access',
@@ -842,12 +886,24 @@ export type PlayAuthoringRuntimeStepOptions = {
   staleAfterSeconds?: DurableCallStaleAfterSeconds;
 };
 
+/**
+ * Durable freshness for one `ctx.fetch` call. The key identifies the request;
+ * `staleAfterSeconds` controls when that completed request may be reused across
+ * Play runs. Omit it (or pass `null`) to reuse indefinitely, pass `0` to
+ * execute on every new run, or pass a positive number of seconds for a TTL.
+ *
+ * Use this for polling or periodically refreshing one external resource. It
+ * does not change dataset row identity.
+ *
+ */
 export type PlayAuthoringFetchOptions = {
   staleAfterSeconds?: DurableCallStaleAfterSeconds;
+  /** Run through Deepline's guarded outbound path without retaining a response receipt or checkpoint. Use this for short-lived credential exchanges or other response data that should stay in the running Play only. */
+  transient?: boolean;
 };
 
 /**
- * The value `ctx.fetch(...)` resolves to: a plain durable record, not a WHATWG `Response`. The body is read once at request time so the call can be checkpointed and replayed, so `bodyText` and `json` are already-materialized properties. There is no `.json()`, `.text()`, or `.body` to await — `await res.json()` is a type error, not a typing problem.
+ * A durable response record, not a WHATWG `Response`: read the already-materialized `bodyText` and `json` properties; do not call `.json()`, `.text()`, or `.body`.
  *
  * @sdkReference runtime 175 PlayFetchResponse
  */
@@ -870,6 +926,55 @@ export type PlayAuthoringFetchResponse = {
   json: unknown | null;
 };
 
+/**
+ * Edition 5+ `ctx.fetch` error for a non-2xx response. Its full readable body is secret-redacted; editions 1–4 retain `PlayFetchResponse { ok: false }`.
+ *
+ * @sdkReference runtime 178 CtxFetchHttpError
+ */
+export class CtxFetchHttpError extends Error {
+  /**
+   * Play source and the runtime are separately bundled. Recognize the stable
+   * public error code so `instanceof` works across that boundary as well.
+   */
+  static [Symbol.hasInstance](value: unknown): boolean {
+    return (
+      value !== null &&
+      typeof value === 'object' &&
+      (value as { code?: unknown }).code === 'CTX_FETCH_HTTP_ERROR'
+    );
+  }
+
+  /** Stable machine-readable HTTP-failure code. */
+  readonly code = 'CTX_FETCH_HTTP_ERROR' as const;
+  /** Upstream HTTP status. */
+  readonly status: number;
+  /** Upstream HTTP status text. */
+  readonly statusText: string;
+  /** Final response URL after redirects. */
+  readonly url: string;
+  /** Secret-redacted response headers. */
+  readonly headers: Record<string, string>;
+  /** Complete secret-redacted response body. */
+  readonly bodyText: string;
+  /** Eagerly parsed secret-redacted JSON, or null. */
+  readonly json: unknown | null;
+
+  /** Build the error from the durable response record. */
+  constructor(readonly response: PlayAuthoringFetchResponse) {
+    const body = response.bodyText || 'empty response body';
+    super(
+      `ctx.fetch(${response.url}) returned HTTP ${response.status}${response.statusText ? ` ${response.statusText}` : ''}: ${body}`,
+    );
+    this.name = 'CtxFetchHttpError';
+    this.status = response.status;
+    this.statusText = response.statusText;
+    this.url = response.url;
+    this.headers = response.headers;
+    this.bodyText = response.bodyText;
+    this.json = response.json;
+  }
+}
+
 export type PlayAuthoringCustomerDbQueryOptions = {
   maxRows?: number;
   timeoutMs?: number;
@@ -1008,7 +1113,8 @@ export interface PlayAuthoringRuntimeContext {
   ): Promise<T>;
 
   /**
-   * Execute a durable, replay-safe HTTP request.
+   * Execute a guarded HTTP request. By default it is durable and replay-safe; `staleAfterSeconds` governs only that completed call receipt, never dataset/request identity. Pass `{ transient: true }` for short-lived credential exchanges or other response data that must not be retained in a receipt or checkpoint. Edition 5+ throws `CtxFetchHttpError` for non-2xx; catch it only when the Play intentionally recovers, otherwise let it fail the Play. Editions 1–4 retain their previous response projections.
+   *
    * @sdkReference runtime 170 ctx.fetch(key, url, init)
    */
   fetch(
@@ -2541,8 +2647,9 @@ export const PLAY_AUTHORING_CLOUD_TYPE_DECLARATIONS = [
   "export type PlayCallExecution = 'inline';",
   `export type PlayCallOptions = { description: ${cloudReferenceType('ctx.runPlay.options.description')}; execution?: ${cloudReferenceType('ctx.runPlay.options.execution')}; timeoutMs?: ${cloudReferenceType('ctx.runPlay.options.timeoutMs')} };`,
   `export type RuntimeStepOptions = { semanticKey?: ${cloudReferenceType('ctx.step.semanticKey')}; staleAfterSeconds?: ${cloudReferenceType('ctx.step.staleAfterSeconds')} };`,
-  `export type FetchOptions = { staleAfterSeconds?: ${cloudReferenceType('ctx.fetch.staleAfterSeconds')} };`,
+  `export type FetchOptions = { staleAfterSeconds?: ${cloudReferenceType('ctx.fetch.staleAfterSeconds')}; transient?: boolean };`,
   'export type PlayFetchResponse = { ok: boolean; status: number; statusText: string; url: string; headers: Record<string, string>; bodyText: string; json: unknown | null };',
+  "export declare class CtxFetchHttpError extends Error { readonly code: 'CTX_FETCH_HTTP_ERROR'; readonly response: PlayFetchResponse; readonly status: number; readonly statusText: string; readonly url: string; readonly headers: Record<string, string>; readonly bodyText: string; readonly json: unknown | null; }",
   'export type StepResolver<Row, Value> = (row: Row, ctx: DeeplinePlayRuntimeContext, index: number, previousCell?: PreviousCell<Value>) => Value | Promise<Value>;',
   'export type DatasetColumnRunInput<Row, Value> = { readonly row: Row; readonly ctx: DeeplinePlayRuntimeContext; readonly index: number; readonly previousCell?: PreviousCell<Value> };',
   'export type DatasetColumnDefinition<Row, Value> = { readonly run: (input: DatasetColumnRunInput<Row, Value>) => Value | Promise<Value>; readonly runIf?: (row: Row, index: number) => boolean | Promise<boolean> };',

package/dist/bundling-sources/shared_libs/security/safe-fetch.ts

@@ -15,6 +15,8 @@ export type SafeFetchOptions = {
   sensitiveHeaders?: Iterable<string>;
   /** Drop every caller-supplied header when a redirect changes origin. */
   stripHeadersOnCrossOriginRedirect?: boolean;
+  /** Headers the trusted runtime may add after caller headers are stripped. */
+  headersOnCrossOriginRedirect?: HeadersInit;
 };
 
 function removeHeader(headers: Headers, name: string) {
@@ -32,6 +34,7 @@ function requestInitForRedirect(
   status: number,
   sensitiveHeaders: Iterable<string>,
   stripHeadersOnCrossOriginRedirect: boolean,
+  headersOnCrossOriginRedirect: HeadersInit | undefined,
 ): RequestInit {
   let headers = new Headers(init.headers);
   let method = String(init.method ?? 'GET').toUpperCase();
@@ -57,7 +60,7 @@ function requestInitForRedirect(
       // Callers that can construct credentials from plaintext secrets cannot
       // reliably identify every transformed value. Do not forward any caller
       // header across an origin boundary in that trust model.
-      headers = new Headers();
+      headers = new Headers(headersOnCrossOriginRedirect);
     } else {
       removeHeader(headers, 'authorization');
       removeHeader(headers, 'cookie');
@@ -88,6 +91,7 @@ export async function safePublicFetch(
   const sensitiveHeaders = options.sensitiveHeaders ?? [];
   const stripHeadersOnCrossOriginRedirect =
     options.stripHeadersOnCrossOriginRedirect === true;
+  const headersOnCrossOriginRedirect = options.headersOnCrossOriginRedirect;
   let currentUrl = assertPublicHttpUrl(input);
   let currentInit: RequestInit = {
     ...init,
@@ -135,6 +139,7 @@ export async function safePublicFetch(
       response.status,
       sensitiveHeaders,
       stripHeadersOnCrossOriginRedirect,
+      headersOnCrossOriginRedirect,
     );
     currentUrl = nextUrl;
   }