deepline 0.3.149 → 0.3.150

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

@@ -36,7 +36,7 @@ import type { ToolResultBilling } from '../../shared_libs/plays/tool-result-type
  * @module
  */
 import { resolveConfig } from './config.js';
-import { DeeplineError } from './errors.js';
+import { DeeplineError, ToolExecutionError } from './errors.js';
 import { HttpClient } from './http.js';
 import { PRODUCT_NOTIFICATION_SLACK_OAUTH_SCOPES } from '../../shared_libs/product-notifications/contract.js';
 import {
@@ -222,6 +222,114 @@ const MONITOR_NON_RETRYABLE_MUTATION_OPTIONS = {
   exactUrlOnly: true,
 };
 const RAW_V2_EXECUTE_RESPONSE_CONTRACT = RAW_V2_TOOL_RESPONSE_CONTRACT;
+const DEFAULT_EXECUTION_RECOVERY_TIMEOUT_MS = 15 * 60 * 1_000;
+
+function validateExecutionIdempotencyKey(key: string): void {
+  if (
+    typeof key !== 'string' ||
+    key.length < 1 ||
+    key.length > 200 ||
+    !/^[A-Za-z0-9._:-]+$/.test(key)
+  ) {
+    throw new DeeplineError(
+      'Execution idempotency keys must be 1–200 ASCII letters, digits, dots, underscores, colons, or hyphens.',
+      undefined,
+      'IDEMPOTENCY_KEY_INVALID',
+    );
+  }
+}
+
+function isExecutionInProgressResponse(value: unknown): boolean {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as { executionRecovery?: { state?: unknown } })
+      .executionRecovery === 'object' &&
+    (value as { executionRecovery: { state?: unknown } }).executionRecovery
+      .state === 'running'
+  );
+}
+
+function getExecutionRecoveryState(
+  value: unknown,
+): ExecutionRecovery['state'] | null {
+  if (
+    typeof value !== 'object' ||
+    value === null ||
+    typeof (value as { executionRecovery?: { state?: unknown } })
+      .executionRecovery !== 'object'
+  ) {
+    return null;
+  }
+  const state = (value as { executionRecovery: { state?: unknown } })
+    .executionRecovery.state;
+  return state === 'running' ||
+    state === 'completed' ||
+    state === 'outcome_unknown'
+    ? state
+    : null;
+}
+
+function isRecoverableExecutionAttemptError(error: unknown): boolean {
+  if (error instanceof ToolExecutionError) {
+    return (
+      error.code === 'EXECUTION_IN_PROGRESS' ||
+      (error.origin === 'deepline' &&
+        error.category === 'network' &&
+        error.networkScope === 'client_to_deepline')
+    );
+  }
+  return (
+    error instanceof DeeplineError &&
+    (error.code === 'EXECUTION_IN_PROGRESS' ||
+      (error.code?.startsWith('NETWORK_') === true &&
+        error.statusCode === undefined))
+  );
+}
+
+function isRecoverableExecutionLookupError(error: unknown): boolean {
+  if (isRecoverableExecutionAttemptError(error)) return true;
+  return (
+    error instanceof DeeplineError &&
+    (error.statusCode === 429 ||
+      (error.statusCode !== undefined && error.statusCode >= 500))
+  );
+}
+
+function timeoutWithinRecoveryBudget(
+  requestTimeoutMs: number | undefined,
+  defaultRequestTimeoutMs: number,
+  remainingMs: number,
+): number {
+  return Math.min(requestTimeoutMs ?? defaultRequestTimeoutMs, remainingMs);
+}
+
+function executionRecoveryError(input: {
+  toolId: string;
+  idempotencyKey: string;
+  code:
+    | 'EXECUTION_IN_PROGRESS'
+    | 'EXECUTION_OUTCOME_UNKNOWN'
+    | 'EXECUTION_RECOVERY_TIMEOUT';
+  message: string;
+}): ToolExecutionError {
+  return new ToolExecutionError(input.message, {
+    toolId: input.toolId,
+    provider: null,
+    operation: input.toolId,
+    code: input.code,
+    origin: 'deepline',
+    category:
+      input.code === 'EXECUTION_OUTCOME_UNKNOWN' ? 'unknown' : 'conflict',
+    retryable: input.code !== 'EXECUTION_OUTCOME_UNKNOWN',
+    statusCode: null,
+    requestId: null,
+    retryAfterMs: null,
+    networkKind: null,
+    networkScope: null,
+    publicDetails: { idempotencyKey: input.idempotencyKey },
+  });
+}
 const COMPILE_MANIFEST_RETRY_DELAYS_MS = [250, 1_000];
 const REGISTER_PLAY_ARTIFACTS_COMPILE_CONCURRENCY = 3;
 const REGISTER_PLAY_ARTIFACTS_MAX_BATCH_COUNT = 3;
@@ -547,6 +655,40 @@ type ExecuteToolRawOptions = {
   metadata?: Record<string, unknown>;
   timeout?: number;
   maxRetries?: number;
+  /** Reuse this stable key to recover or retry an ambiguous execution. */
+  idempotencyKey?: string;
+  /** Generate a key and enable recoverable execution before dispatch. */
+  recover?: boolean;
+  /** Called and awaited with the key before the first network request. */
+  onExecution?: (execution: { idempotencyKey: string }) => void | Promise<void>;
+  /** Maximum time to reconnect to an in-progress keyed execution. Defaults to 15 minutes. */
+  recoveryTimeoutMs?: number;
+};
+
+/** Durable state returned for a keyed tool execution. */
+export type ExecutionRecovery = {
+  /** Stable caller key used to resume or replay this execution. */
+  idempotencyKey: string;
+  /** Whether the execution is still running, completed, or has an unknown provider outcome. */
+  state: 'running' | 'completed' | 'outcome_unknown';
+  /** Whether this response came from an existing durable execution. */
+  replayed: boolean;
+  /** ISO timestamp after which the completed execution can no longer be replayed. */
+  expiresAt?: string;
+};
+
+/** Durable lookup result for a keyed tool execution. */
+export type ExecutionByKeyResult = {
+  /** Recovery state and the key that owns the execution. */
+  executionRecovery: ExecutionRecovery;
+  /** Provider tool associated with the execution. */
+  toolId: string;
+  /** Original server-owned billing request ID, allocated before provider dispatch. */
+  requestId?: string;
+  /** HTTP status saved with the original response, when it was terminal. */
+  responseStatus?: number;
+  /** Saved execution response, when one is available for replay. */
+  response?: unknown;
 };
 
 /**
@@ -3121,6 +3263,41 @@ export class DeeplineClient {
     input: Record<string, unknown>,
     options?: ExecuteToolRawOptions,
   ): Promise<ToolExecution<TData, TMeta>> {
+    // Snapshot JSON input before the caller's awaited onExecution callback and
+    // before any retry, so every POST is byte-equivalent in meaning.
+    const inputSnapshot = JSON.parse(JSON.stringify(input)) as Record<
+      string,
+      unknown
+    >;
+    const metadataSnapshot = options?.metadata
+      ? (JSON.parse(JSON.stringify(options.metadata)) as Record<
+          string,
+          unknown
+        >)
+      : undefined;
+    const idempotencyKey =
+      options?.idempotencyKey ??
+      (options?.recover ? crypto.randomUUID() : undefined);
+    if (idempotencyKey !== undefined) {
+      validateExecutionIdempotencyKey(idempotencyKey);
+      if (
+        options?.recoveryTimeoutMs !== undefined &&
+        (!Number.isFinite(options.recoveryTimeoutMs) ||
+          options.recoveryTimeoutMs < 0)
+      ) {
+        throw new DeeplineError(
+          'recoveryTimeoutMs must be a finite, non-negative number.',
+          undefined,
+          'IDEMPOTENCY_KEY_INVALID',
+        );
+      }
+      await options?.onExecution?.({ idempotencyKey });
+      const timeoutMs =
+        options?.timeout ?? resolveToolExecuteTimeoutMs(toolId, inputSnapshot);
+      await this.lookupExecutionByKey(idempotencyKey, timeoutMs);
+    }
+    const timeoutMs =
+      options?.timeout ?? resolveToolExecuteTimeoutMs(toolId, inputSnapshot);
     const headers = {
       [EXECUTE_RESPONSE_CONTRACT_HEADER]: RAW_V2_EXECUTE_RESPONSE_CONTRACT,
       [TOOL_EXECUTION_ERROR_SCHEMA_HEADER]: String(
@@ -3130,22 +3307,180 @@ export class DeeplineClient {
         ? { [INCLUDE_TOOL_METADATA_HEADER]: 'true' }
         : {}),
       [EXECUTE_RESPONSE_INTENT_HEADER]: options?.responseIntent ?? 'raw',
+      ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),
     };
-    const response = await this.http.post<ToolExecution<TData, TMeta>>(
-      `/api/v2/integrations/${encodeURIComponent(toolId)}/execute`,
-      {
-        payload: input,
-        ...(options?.metadata ? { metadata: options.metadata } : {}),
-      },
-      headers,
+    const request = (requestTimeoutMs: number | undefined) =>
+      this.http.post<ToolExecution<TData, TMeta>>(
+        `/api/v2/integrations/${encodeURIComponent(toolId)}/execute`,
+        {
+          payload: inputSnapshot,
+          ...(metadataSnapshot ? { metadata: metadataSnapshot } : {}),
+        },
+        headers,
+        {
+          timeout: requestTimeoutMs,
+          maxRetries: idempotencyKey ? 0 : (options?.maxRetries ?? 0),
+          exactUrlOnly: true,
+          toolId,
+          idempotencyKey,
+        },
+      );
+    let response: ToolExecution<TData, TMeta>;
+    let recoveryDeadline: number | null = null;
+    const recoveryTimeoutMs =
+      options?.recoveryTimeoutMs ?? DEFAULT_EXECUTION_RECOVERY_TIMEOUT_MS;
+    let retryDelayMs = 1_000;
+    const recoveryTimeoutError = () =>
+      executionRecoveryError({
+        toolId,
+        idempotencyKey: idempotencyKey!,
+        code: 'EXECUTION_RECOVERY_TIMEOUT',
+        message: `Execution recovery for ${idempotencyKey} did not finish before the recovery timeout. Inspect client.executions.getByKey() and resume with the same idempotency key.`,
+      });
+    const waitForRecoveryRetry = async (deadline: number) => {
+      const remainingMs = deadline - Date.now();
+      if (remainingMs <= 0) throw recoveryTimeoutError();
+      await new Promise((resolve) =>
+        setTimeout(resolve, Math.min(retryDelayMs, remainingMs)),
+      );
+      retryDelayMs = Math.min(retryDelayMs * 2, 5_000);
+    };
+    const lookupDuringRecovery = async () => {
+      while (true) {
+        const remainingMs = recoveryDeadline! - Date.now();
+        if (remainingMs <= 0) throw recoveryTimeoutError();
+        try {
+          return await this.lookupExecutionByKey(
+            idempotencyKey!,
+            timeoutWithinRecoveryBudget(
+              timeoutMs,
+              this.config.timeout,
+              remainingMs,
+            ),
+          );
+        } catch (error) {
+          if (!isRecoverableExecutionLookupError(error)) throw error;
+          await waitForRecoveryRetry(recoveryDeadline!);
+        }
+      }
+    };
+    while (true) {
+      const remainingMs =
+        recoveryDeadline === null ? null : recoveryDeadline - Date.now();
+      if (remainingMs !== null && remainingMs <= 0) {
+        throw recoveryTimeoutError();
+      }
+      try {
+        response = await request(
+          remainingMs === null
+            ? timeoutMs
+            : timeoutWithinRecoveryBudget(
+                timeoutMs,
+                this.config.timeout,
+                remainingMs,
+              ),
+        );
+        if (getExecutionRecoveryState(response) === 'outcome_unknown') {
+          if (!idempotencyKey) break;
+          throw executionRecoveryError({
+            toolId,
+            idempotencyKey,
+            code: 'EXECUTION_OUTCOME_UNKNOWN',
+            message: `The outcome of execution ${idempotencyKey} is unknown. Do not retry with a new key; inspect client.executions.getByKey().`,
+          });
+        }
+        if (!idempotencyKey || !isExecutionInProgressResponse(response)) {
+          break;
+        }
+        if (recoveryDeadline === null) {
+          recoveryDeadline = Date.now() + recoveryTimeoutMs;
+        }
+      } catch (error) {
+        if (
+          idempotencyKey &&
+          error instanceof DeeplineError &&
+          error.code === 'EXECUTION_OUTCOME_UNKNOWN'
+        ) {
+          throw executionRecoveryError({
+            toolId,
+            idempotencyKey,
+            code: 'EXECUTION_OUTCOME_UNKNOWN',
+            message: error.message,
+          });
+        }
+        if (!idempotencyKey || !isRecoverableExecutionAttemptError(error)) {
+          throw error;
+        }
+        if (recoveryDeadline === null) {
+          recoveryDeadline = Date.now() + recoveryTimeoutMs;
+        }
+      }
+      await waitForRecoveryRetry(recoveryDeadline!);
+      const recovered = await lookupDuringRecovery();
+      if (getExecutionRecoveryState(recovered) === 'outcome_unknown') {
+        throw executionRecoveryError({
+          toolId,
+          idempotencyKey,
+          code: 'EXECUTION_OUTCOME_UNKNOWN',
+          message: `The outcome of execution ${idempotencyKey} is unknown. Do not retry with a new key; inspect client.executions.getByKey().`,
+        });
+      }
+    }
+    const materialized = materializeToolExecutionResponse(response);
+    return idempotencyKey ? { ...materialized, idempotencyKey } : materialized;
+  }
+
+  /** Read the durable state of a keyed tool execution. */
+  async getExecutionByKey(
+    idempotencyKey: string,
+  ): Promise<ExecutionByKeyResult> {
+    validateExecutionIdempotencyKey(idempotencyKey);
+    const result = await this.lookupExecutionByKey(idempotencyKey);
+    if (!result) {
+      throw new DeeplineError(
+        `No execution exists for idempotency key ${idempotencyKey}.`,
+        404,
+        'EXECUTION_NOT_FOUND',
+      );
+    }
+    return result;
+  }
+
+  private async lookupExecutionByKey(
+    idempotencyKey: string,
+    timeoutMs?: number,
+  ): Promise<ExecutionByKeyResult | null> {
+    validateExecutionIdempotencyKey(idempotencyKey);
+    let supported = false;
+    const result = await this.http.get<ExecutionByKeyResult | null>(
+      `/api/v2/executions/by-key/${encodeURIComponent(idempotencyKey)}`,
       {
-        timeout: options?.timeout ?? resolveToolExecuteTimeoutMs(toolId, input),
-        maxRetries: options?.maxRetries ?? 0,
         exactUrlOnly: true,
-        toolId,
+        maxRetries: 0,
+        timeout: timeoutMs,
+        idempotencyKey,
+        allowNotFound: true,
+        onResponse: (response) => {
+          supported =
+            response.headers.get('X-Deepline-Idempotency-Supported') === 'true';
+        },
       },
     );
-    return materializeToolExecutionResponse(response);
+    if (!supported) {
+      throw new DeeplineError(
+        'This Deepline server does not support recoverable tool executions; no tool was dispatched.',
+        422,
+        'IDEMPOTENCY_NOT_SUPPORTED',
+      );
+    }
+    return result;
+  }
+
+  /** Public recovery namespace. */
+  get executions(): {
+    getByKey: (key: string) => Promise<ExecutionByKeyResult>;
+  } {
+    return { getByKey: (key) => this.getExecutionByKey(key) };
   }
 
   /**

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

@@ -76,6 +76,9 @@ interface RequestOptions {
   preserveRateLimitResponse?: boolean;
   /** Enables endpoint-specific structured tool failure mapping. */
   toolId?: string;
+  onResponse?: (response: Response) => void;
+  allowNotFound?: boolean;
+  idempotencyKey?: string;
 }
 
 interface StreamOptions {
@@ -423,6 +426,12 @@ export class HttpClient {
             signal: controller.signal,
           });
 
+          options?.onResponse?.(response);
+          if (response.status === 404 && options?.allowNotFound) {
+            clearTimeout(timeoutId);
+            return null as T;
+          }
+
           clearTimeout(timeoutId);
 
           const body = await response.text();
@@ -626,6 +635,9 @@ export class HttpClient {
                   : 'unavailable',
             networkScope: 'client_to_deepline',
             details: mappedNetworkError.details,
+            publicDetails: options.idempotencyKey
+              ? { idempotencyKey: options.idempotencyKey }
+              : null,
           },
         ),
         lastError,
@@ -652,7 +664,14 @@ export class HttpClient {
     path: string,
     options?: Pick<
       RequestOptions,
-      'retryApiErrors' | 'timeout' | 'maxRetries' | 'exactUrlOnly' | 'toolId'
+      | 'retryApiErrors'
+      | 'timeout'
+      | 'maxRetries'
+      | 'exactUrlOnly'
+      | 'toolId'
+      | 'onResponse'
+      | 'allowNotFound'
+      | 'idempotencyKey'
     >,
   ): Promise<T> {
     return this.request<T>(path, {
@@ -777,7 +796,14 @@ export class HttpClient {
     headers?: Record<string, string>,
     options?: Pick<
       RequestOptions,
-      'retryApiErrors' | 'timeout' | 'maxRetries' | 'exactUrlOnly' | 'toolId'
+      | 'retryApiErrors'
+      | 'timeout'
+      | 'maxRetries'
+      | 'exactUrlOnly'
+      | 'toolId'
+      | 'onResponse'
+      | 'allowNotFound'
+      | 'idempotencyKey'
     >,
   ): Promise<T> {
     return this.request<T>(path, {

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

@@ -128,6 +128,8 @@ export type {
   RunsTailOptions,
   StopAllRunsOptions,
   ToolExecution,
+  ExecutionRecovery,
+  ExecutionByKeyResult,
 } from './client.js';
 
 // ——— Monitors framework ———
@@ -288,6 +290,8 @@ export type {
   DeeplinePlaysNamespace,
   DeeplinePlayRuntimeContext,
   DeeplineToolsNamespace,
+  DeeplineToolExecuteResult,
+  DeeplineExecutionsNamespace,
   DefinedPlay,
   ColumnMap,
   ColumnResolver,

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

@@ -109,7 +109,11 @@ import type {
   ToolDefinition,
   ToolMetadata,
 } from './types.js';
-import type { ToolExecution } from './client.js';
+import type {
+  ExecutionByKeyResult,
+  ExecutionRecovery,
+  ToolExecution,
+} from './client.js';
 import type {
   DurableCallStaleAfterSeconds,
   PlayAuthoringBindings,
@@ -660,7 +664,26 @@ export type DeeplineToolsNamespace = {
   execute(
     toolId: string,
     input: Record<string, unknown>,
-  ): Promise<ToolExecuteResult>;
+    options?: {
+      idempotencyKey?: string;
+      recover?: boolean;
+      onExecution?: (execution: {
+        idempotencyKey: string;
+      }) => void | Promise<void>;
+      recoveryTimeoutMs?: number;
+    },
+  ): Promise<DeeplineToolExecuteResult>;
+};
+
+export type DeeplineToolExecuteResult = ToolExecuteResult & {
+  /** Stable key used to recover this direct tool execution, when enabled. */
+  idempotencyKey?: string;
+  executionRecovery?: ExecutionRecovery;
+};
+
+export type DeeplineExecutionsNamespace = {
+  /** Look up a recoverable tool execution by its stable idempotency key. */
+  getByKey(idempotencyKey: string): Promise<ExecutionByKeyResult>;
 };
 
 /**
@@ -1084,10 +1107,19 @@ export class DeeplineContext {
       execute: async (
         toolId: string,
         input: Record<string, unknown>,
-      ): Promise<ToolExecuteResult> => {
+        options?: {
+          idempotencyKey?: string;
+          recover?: boolean;
+          onExecution?: (execution: {
+            idempotencyKey: string;
+          }) => void | Promise<void>;
+          recoveryTimeoutMs?: number;
+        },
+      ): Promise<DeeplineToolExecuteResult> => {
         const response = await this.client.executeTool(toolId, input, {
           includeToolMetadata: true,
           responseIntent: 'dataset',
+          ...options,
         });
         return toolExecutionEnvelopeToResult(toolId, response, {
           client: this.client,
@@ -1097,6 +1129,11 @@ export class DeeplineContext {
     };
   }
 
+  /** Durable state for recoverable direct tool executions. */
+  get executions(): DeeplineExecutionsNamespace {
+    return { getByKey: (key) => this.client.getExecutionByKey(key) };
+  }
+
   /**
    * Play discovery and named-play handles.
    *
@@ -1506,7 +1543,7 @@ function toolExecutionEnvelopeToResult(
     client: DeeplineClient;
     input: Record<string, unknown>;
   },
-): ToolExecuteResult {
+): DeeplineToolExecuteResult {
   const raw = response.toolResponse?.raw ?? null;
   const rawV2 = response.toolResponse?.rawV2;
   const view = response.toolResponse?.view;
@@ -1516,7 +1553,7 @@ function toolExecutionEnvelopeToResult(
     : null;
   const toolMetadata = isRecord(metadata) ? metadata : {};
 
-  return attachSdkQueryResultDatasetResult(
+  const result: DeeplineToolExecuteResult = attachSdkQueryResultDatasetResult(
     fallbackToolId,
     createToolExecuteResult({
       status:
@@ -1553,6 +1590,19 @@ function toolExecutionEnvelopeToResult(
     }),
     options,
   );
+  const executionRecovery = isRecord(response.executionRecovery)
+    ? (response.executionRecovery as unknown as ExecutionRecovery)
+    : undefined;
+  // `createToolExecuteResult` installs `toolOutput` and `_metadata` as
+  // non-enumerable compatibility properties. Mutating the wrapper preserves
+  // those aliases while adding recovery fields to the same public result.
+  if (typeof response.idempotencyKey === 'string') {
+    result.idempotencyKey = response.idempotencyKey;
+  }
+  if (executionRecovery) {
+    result.executionRecovery = executionRecovery;
+  }
+  return result;
 }
 
 export function defineInput<TInput>(

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

@@ -200,7 +200,7 @@ export const SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: '0.3.149',
+  version: '0.3.150',
   updateSummary:
     'Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.',
   packageCapabilities: {

package/dist/bundling-sources/shared_libs/observability/scheduled-jobs.json

@@ -561,6 +561,24 @@
     "failureAlert": "vercel_route_wrapper",
     "domainReportRequired": true
   },
+  {
+    "id": "vercel.public-tool-execution-blob-cleanup",
+    "name": "Public tool execution blob cleanup",
+    "scheduler": "vercel_cron",
+    "cadence": "*/15 * * * *",
+    "timezone": "UTC",
+    "source": "apps/deepline-api/vercel.json",
+    "locator": "/api/v2/cron/public-tool-execution-blob-cleanup",
+    "owner": "integrations",
+    "criticality": "maintenance",
+    "purpose": "Delete expired public execution response and launch blobs while retaining idempotency key and fingerprint tombstones.",
+    "successDefinition": "Every claimed expired receipt's recorded blobs are confirmed absent before their references are cleared; no eligible receipts is a valid no-op.",
+    "failureDefinition": "An R2 deletion/absence check fails or the fenced tombstone cleanup acknowledgement cannot complete.",
+    "startGraceMs": 300000,
+    "runTimeoutMs": 1800000,
+    "failureAlert": "vercel_route_wrapper",
+    "domainReportRequired": true
+  },
   {
     "id": "vercel.scheduled-work-health-snapshot",
     "name": "Scheduled-work health snapshot",

package/dist/bundling-sources/shared_libs/play-data-plane/r2.ts

@@ -144,6 +144,39 @@ export async function r2ObjectExists(
   }
 }
 
+/**
+ * Confirm an R2 object is absent without confusing a HEAD/auth/network failure
+ * with a successful deletion.
+ */
+export async function confirmR2ObjectAbsent(
+  key: string,
+  kind: R2BucketKind = 'default',
+): Promise<boolean> {
+  const config = getR2Config(kind);
+  const client = getR2Client(config);
+  try {
+    await client.send(
+      new HeadObjectCommand({ Bucket: config.bucket, Key: key }),
+    );
+    return false;
+  } catch (error) {
+    const details = error as {
+      name?: string;
+      Code?: string;
+      $metadata?: { httpStatusCode?: number };
+    };
+    if (
+      details.$metadata?.httpStatusCode === 404 ||
+      details.name === 'NotFound' ||
+      details.name === 'NoSuchKey' ||
+      details.Code === 'NotFound' ||
+      details.Code === 'NoSuchKey'
+    )
+      return true;
+    throw error;
+  }
+}
+
 export async function uploadBufferToR2(input: {
   key: string;
   body: Buffer | Uint8Array;