deepline 0.3.128 → 0.3.129

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

@@ -114,6 +114,7 @@ import {
 import {
   normalizePlayRuntimeEnvironment,
   normalizePlayRuntimeNamespace,
+  normalizePlayRuntimeSandboxPlacementPolicy,
   normalizePlayRuntimeSelection,
   type PlayRuntimeSelection,
 } from '../../shared_libs/play-runtime/runtime-environment.js';
@@ -304,7 +305,7 @@ function resolvePlayRunRuntimeSelection(
     const runtime = normalizePlayRuntimeSelection(request.runtime);
     if (!runtime) {
       throw new DeeplineError(
-        'runtime must be { environment: "preview", namespace, backend?: "daytona" | "modal" } with namespace matching ^[a-z][a-z0-9-]{0,30}$.',
+        'runtime must be { environment: "preview", namespace, backend?: "daytona" | "modal", sandboxPlacementPolicy?: "policy_name@1" } with namespace matching ^[a-z][a-z0-9-]{0,30}$.',
         undefined,
         'INVALID_RUNTIME_SELECTION',
       );
@@ -320,8 +321,10 @@ function resolvePlayRunRuntimeSelection(
   const configuredNamespace = process.env.DEEPLINE_RUNTIME_NAMESPACE?.trim();
   const configuredToken =
     process.env.DEEPLINE_RUNTIME_ENVIRONMENT_TOKEN?.trim();
+  const configuredPlacementPolicy =
+    process.env.DEEPLINE_RUNTIME_SANDBOX_PLACEMENT_POLICY?.trim();
   if (!configured) {
-    if (configuredNamespace || configuredToken) {
+    if (configuredNamespace || configuredToken || configuredPlacementPolicy) {
       // Name the variables that are actually set. This branch is almost always
       // hit by a stale value auto-loaded from a .env/.env.local rather than by
       // a deliberate export, so the message has to say where to look and how
@@ -329,6 +332,9 @@ function resolvePlayRunRuntimeSelection(
       const present: string[] = [];
       if (configuredNamespace) present.push('DEEPLINE_RUNTIME_NAMESPACE');
       if (configuredToken) present.push('DEEPLINE_RUNTIME_ENVIRONMENT_TOKEN');
+      if (configuredPlacementPolicy) {
+        present.push('DEEPLINE_RUNTIME_SANDBOX_PLACEMENT_POLICY');
+      }
       const isPlural = present.length > 1;
       throw new DeeplineError(
         [
@@ -359,18 +365,37 @@ function resolvePlayRunRuntimeSelection(
       'INVALID_RUNTIME_NAMESPACE',
     );
   }
-  const configuredBackend = process.env.DEEPLINE_PLAY_RUNNER_BACKEND?.trim();
-  if (!configuredBackend) {
-    return { environment, namespace };
-  }
-  if (configuredBackend !== 'daytona' && configuredBackend !== 'modal') {
+  const configuredBackendValue =
+    process.env.DEEPLINE_PLAY_RUNNER_BACKEND?.trim();
+  const configuredBackend =
+    configuredBackendValue === 'daytona' || configuredBackendValue === 'modal'
+      ? configuredBackendValue
+      : undefined;
+  if (configuredBackendValue && !configuredBackend) {
     throw new DeeplineError(
-      `DEEPLINE_PLAY_RUNNER_BACKEND must be daytona or modal for preview runtime selection. Received "${configuredBackend}".`,
+      `DEEPLINE_PLAY_RUNNER_BACKEND must be daytona or modal for preview runtime selection. Received "${configuredBackendValue}".`,
       undefined,
       'INVALID_RUNTIME_BACKEND',
     );
   }
-  return { environment, namespace, backend: configuredBackend };
+  if (
+    configuredPlacementPolicy &&
+    !normalizePlayRuntimeSandboxPlacementPolicy(configuredPlacementPolicy)
+  ) {
+    throw new DeeplineError(
+      `DEEPLINE_RUNTIME_SANDBOX_PLACEMENT_POLICY must be a versioned placement policy id such as daytona_only@1. Received "${configuredPlacementPolicy}".`,
+      undefined,
+      'INVALID_RUNTIME_SANDBOX_PLACEMENT_POLICY',
+    );
+  }
+  return {
+    environment,
+    namespace,
+    ...(configuredBackend ? { backend: configuredBackend } : {}),
+    ...(configuredPlacementPolicy
+      ? { sandboxPlacementPolicy: configuredPlacementPolicy }
+      : {}),
+  };
 }
 
 function runtimeSelectionHeaders(

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

@@ -550,6 +550,28 @@ export class HttpClient {
             throw lastError;
           }
 
+          // Vercel's deployment-protection interstitial is served as a 2xx
+          // HTML page, so it never reaches the !ok branch above. Without this
+          // the caller receives a string where it expected JSON and reports
+          // whatever field it found missing — an expired `vercel login` shows
+          // up as an unrelated validation error several layers away.
+          if (typeof parsed === 'string') {
+            const interstitial = detectHtmlErrorBody(
+              body,
+              response.headers.get('content-type'),
+            );
+            if (interstitial) {
+              throw new DeeplineError(
+                `${this.config.baseUrl} returned a deployment-protection page ` +
+                  'instead of JSON. Set VERCEL_PROTECTION_BYPASS_TOKEN, or run ' +
+                  '`vercel login` if the CLI session expired.',
+                response.status,
+                'DEPLOYMENT_PROTECTED',
+                { htmlErrorPage: true },
+              );
+            }
+          }
+
           return parsed as T;
         } catch (error) {
           clearTimeout(timeoutId);

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.128',
+  version: '0.3.129',
   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/play-data-plane/r2.ts

@@ -3,6 +3,7 @@ import {
   PutObjectCommand,
   GetObjectCommand,
   HeadObjectCommand,
+  DeleteObjectCommand,
 } from '@aws-sdk/client-s3';
 import { NodeHttpHandler } from '@smithy/node-http-handler';
 import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
@@ -203,6 +204,27 @@ export async function getBufferFromR2(
   return Buffer.from(bytes);
 }
 
+/**
+ * Delete one immutable runtime object. Callers must retain their own durable
+ * deletion intent and confirm absence with HEAD before they acknowledge this
+ * operation: object storage and Postgres do not share a transaction.
+ */
+export async function deleteR2Object(
+  key: string,
+  kind: R2BucketKind = 'default',
+): Promise<void> {
+  const startedAt = Date.now();
+  const config = getR2Config(kind);
+  const client = getR2Client(config);
+  await client.send(
+    new DeleteObjectCommand({
+      Bucket: config.bucket,
+      Key: key,
+    }),
+  );
+  logR2Perf('delete', key, startedAt, { kind });
+}
+
 export async function createSignedR2ReadUrl(input: {
   key: string;
   kind?: R2BucketKind;

package/dist/bundling-sources/shared_libs/play-runtime/app-runtime-api.ts

@@ -47,6 +47,14 @@ import {
   LEGACY_RUNTIME_RECEIPT_WIRE_HEADER,
 } from './/runtime-contract';
 import { PLAY_RUNTIME_API_COMPAT_PATH } from './/runtime-api-paths';
+import {
+  RUNTIME_API_ACCEPTS_HEADER,
+  gzipRuntimeApiRequestBody,
+  isLegacyRuntimeApiGzipDecoderFailure,
+  noteRuntimeApiCompressionCapability,
+  revokeRuntimeApiCompressionCapability,
+  runtimeApiOriginAcceptsGzip,
+} from './/runtime-api-compression';
 import {
   PLAY_RUNTIME_TEST_FAULT_HEADER,
   recognizedRuntimeTestFaultCount,
@@ -302,9 +310,143 @@ export type WorkerRuntimeApiContext = {
   requestTimeoutMs?: number | null;
   /** A higher-level writer owns retries and preserves the exact request body. */
   retryPolicy?: 'default' | 'none';
+  /**
+   * Observe the gateway request identity of a SUCCESSFUL response. Failures
+   * already carry it on the thrown error; a success carried it nowhere, so a
+   * response the caller found surprising could not be traced back to the
+   * gateway record that produced it.
+   */
+  onResponseMeta?: (meta: RuntimeApiResponseMeta) => void;
   signal?: AbortSignal;
 };
 
+/**
+ * The receipt gateway's own account of a request, from its `Server-Timing`
+ * response header. Its `runtime.gateway.action.finished` durationMs starts
+ * AFTER authentication, so auth, body parse, and pool wait are invisible in
+ * gateway logs and observable only here — against `roundTripMs`, the client's
+ * measured wall for the same request, which is the only number that includes
+ * the network.
+ */
+export type RuntimeGatewayServerTiming = {
+  authLaunchMs: number | null;
+  authVerifyMs: number | null;
+  bodyParseMs: number | null;
+  /**
+   * Gunzip of a compressed request body, inside `bodyParseMs`. Null when the
+   * request was not compressed or the gateway predates the entry.
+   */
+  bodyInflateMs: number | null;
+  dispatchPoolMs: number | null;
+  /**
+   * Slowest durable receipt-value persistence in this completion request.
+   * This sits inside `dispatchCallbackMs`; null means the gateway predates the
+   * measurement rather than that a persistence took no time.
+   */
+  receiptValuePersistMs: number | null;
+  dispatchCallbackMs: number | null;
+  authSession: 'hit' | 'miss' | 'coalesced' | 'unknown' | null;
+};
+
+export type RuntimeApiResponseMeta = {
+  action: RuntimeApiRequest['action'];
+  requestId: string | null;
+  /** Client-measured wall of the responding attempt: request send to response. */
+  roundTripMs?: number | null;
+  /** Absent when the gateway sent no `Server-Timing` header. */
+  serverTiming?: RuntimeGatewayServerTiming | null;
+  /**
+   * Serialized JSON bytes of the request body, before compression. Set on
+   * every request, so `wire / raw` across a run is the compression ratio the
+   * transport actually achieved — including the uncompressed requests, which
+   * is the honest denominator.
+   */
+  requestBodyRawBytes?: number | null;
+  /** Bytes actually put on the wire. Equals `requestBodyRawBytes` uncompressed. */
+  requestBodyWireBytes?: number | null;
+  /**
+   * Runner-local wall spent serializing the JSON body once for this retry
+   * ladder. It is deliberately outside `roundTripMs`: this synchronous work
+   * occupies the sandbox CPU before any request can leave the process.
+   */
+  requestBodySerializeMs?: number | null;
+  /**
+   * Runner-local wall spent packing the successful request attempt for the
+   * wire (gzip when the gateway has advertised support). This is also outside
+   * `roundTripMs`, so a CPU-bound encoder cannot masquerade as gateway or
+   * network time.
+   */
+  requestBodyPackMs?: number | null;
+};
+
+const RUNTIME_GATEWAY_AUTH_SESSION_VALUES = new Set([
+  'hit',
+  'miss',
+  'coalesced',
+]);
+
+/**
+ * Parse a receipt gateway `Server-Timing` header into its known entries.
+ *
+ * Deliberately total: an absent, empty, or malformed header yields nulls
+ * rather than an error. This is diagnostic instrumentation on the durable
+ * receipt path, and a gateway that changes its header must never be able to
+ * fail a run.
+ */
+export function parseRuntimeGatewayServerTiming(
+  header: string | null | undefined,
+): RuntimeGatewayServerTiming | null {
+  if (typeof header !== 'string' || !header.trim()) return null;
+  const durations = new Map<string, number>();
+  let authSession: RuntimeGatewayServerTiming['authSession'] = null;
+  for (const rawEntry of header.split(',')) {
+    const parts = rawEntry.split(';');
+    const name = parts[0]?.trim().toLowerCase();
+    if (!name) continue;
+    for (const parameter of parts.slice(1)) {
+      const separator = parameter.indexOf('=');
+      if (separator < 0) continue;
+      const key = parameter.slice(0, separator).trim().toLowerCase();
+      const value = parameter
+        .slice(separator + 1)
+        .trim()
+        .replace(/^"|"$/g, '');
+      if (key === 'dur') {
+        // `Number('')` is 0, which would turn a truncated header into a
+        // confident zero — the one reading this instrument must never produce.
+        const parsed = value === '' ? Number.NaN : Number(value);
+        if (Number.isFinite(parsed)) durations.set(name, parsed);
+      } else if (key === 'desc' && name === 'auth_session' && value !== '') {
+        authSession = RUNTIME_GATEWAY_AUTH_SESSION_VALUES.has(value)
+          ? (value as 'hit' | 'miss' | 'coalesced')
+          : 'unknown';
+      }
+    }
+  }
+  const duration = (name: string): number | null =>
+    durations.has(name) ? durations.get(name)! : null;
+  const timing: RuntimeGatewayServerTiming = {
+    authLaunchMs: duration('auth_launch'),
+    authVerifyMs: duration('auth_verify'),
+    bodyParseMs: duration('body_parse'),
+    bodyInflateMs: duration('body_inflate'),
+    dispatchPoolMs: duration('dispatch_pool'),
+    receiptValuePersistMs: duration('receipt_value_persist'),
+    dispatchCallbackMs: duration('dispatch_callback'),
+    authSession,
+  };
+  const carriesSomething =
+    authSession !== null ||
+    timing.authLaunchMs !== null ||
+    timing.authVerifyMs !== null ||
+    timing.bodyParseMs !== null ||
+    timing.bodyInflateMs !== null ||
+    timing.dispatchPoolMs !== null ||
+    timing.receiptValuePersistMs !== null ||
+    timing.dispatchCallbackMs !== null;
+  return carriesSomething ? timing : null;
+}
+
 const APP_RUNTIME_API_RETRY_DELAYS_MS = [100, 250, 500, 1_000] as const;
 const APP_RUNTIME_API_RECEIPT_RETRY_DELAYS_MS = [
   250, 500, 1_000, 2_000, 4_000, 8_000, 12_000,
@@ -1269,8 +1411,39 @@ async function postAppRuntimeApi<TResponse>(
       context.requestTimeoutMs ?? APP_RUNTIME_API_DEFAULT_REQUEST_TIMEOUT_MS,
     ),
   );
+  // Serialize ONCE for the whole retry ladder: the body is identical across
+  // attempts (that identity is what makes a receipt retry safe), so a second
+  // `JSON.stringify` of a megabyte payload would be pure cost.
+  const serializationStartedAt = Date.now();
+  const serializedBody = JSON.stringify(body);
+  const requestBodySerializeMs = Math.max(
+    0,
+    Date.now() - serializationStartedAt,
+  );
 
-  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+  let forceUncompressedNextAttempt = false;
+  let usedLegacyDecoderFallback = false;
+  // A legacy decoder rejection is known to be pre-dispatch, so it earns one
+  // immediate plain-JSON resend even when the caller disabled normal retries.
+  // It does not consume an application retry attempt or sleep.
+  let attempt = 1;
+  while (attempt <= maxAttempts) {
+    // Re-evaluated per attempt rather than hoisted: the capability can be
+    // learned from THIS request's own first attempt (or from a sibling request
+    // that landed in between), so a retry compresses as soon as the origin has
+    // advertised, without waiting for the next call.
+    const packingStartedAt = Date.now();
+    const wireBody = await gzipRuntimeApiRequestBody({
+      serialized: serializedBody,
+      originAcceptsGzip:
+        !forceUncompressedNextAttempt && runtimeApiOriginAcceptsGzip(baseUrl),
+    });
+    forceUncompressedNextAttempt = false;
+    const requestBodyPackMs = Math.max(0, Date.now() - packingStartedAt);
+    // Started AFTER the body is packed: `roundTripMs` is the request's wall
+    // from send to parsed response, and it is read against the gateway's own
+    // `Server-Timing` to isolate the network. Folding local compression into it
+    // would show up as network cost that no round trip explains.
     const attemptStartedAt = Date.now();
     const transportAttemptId = randomUUID();
     const requestSignal = context.signal
@@ -1285,7 +1458,12 @@ async function postAppRuntimeApi<TResponse>(
       response = await runtimeFetch(resolveAppRuntimeApiUrl(context), {
         method: 'POST',
         headers: {
+          // The payload is JSON either way; `content-encoding` describes only
+          // how those JSON bytes were packed for the wire.
           'content-type': 'application/json',
+          ...(wireBody.contentEncoding
+            ? { 'content-encoding': wireBody.contentEncoding }
+            : {}),
           authorization: `Bearer ${token}`,
           [LEGACY_RUNTIME_RECEIPT_WIRE_HEADER]: String(
             LEGACY_RUNTIME_RECEIPT_WIRE_FORMAT,
@@ -1304,7 +1482,14 @@ async function postAppRuntimeApi<TResponse>(
               }
             : {}),
         },
-        body: JSON.stringify(body),
+        // DOM fetch accepts ArrayBuffer, while Node 24 deliberately rejects a
+        // Uint8Array backed by an arbitrary ArrayBufferLike. Copy only the
+        // compressed branch into an exact ArrayBuffer; its wire bytes remain
+        // identical and the plain JSON fast path stays allocation-free.
+        body:
+          typeof wireBody.body === 'string'
+            ? wireBody.body
+            : Uint8Array.from(wireBody.body).buffer,
         signal: requestSignal,
       });
       const preferredMachineId =
@@ -1338,6 +1523,7 @@ async function postAppRuntimeApi<TResponse>(
           retryDelayMs,
         });
         await sleep(retryDelayMs);
+        attempt += 1;
         continue;
       }
       recordAppRuntimeRetryFailure({
@@ -1364,6 +1550,21 @@ async function postAppRuntimeApi<TResponse>(
         boundaryLabel,
       });
     }
+    // Learn the capability from EVERY response, including 4xx/5xx: an error
+    // response still proves the gateway that produced it can decode a
+    // compressed body, and a run whose first request fails must not be stuck
+    // sending uncompressed bodies for the rest of its life. Deliberately
+    // outside the fetch try/catch and defensive: this is rollout
+    // instrumentation, and a header read must never be able to fail — or be
+    // misreported as — a durable request.
+    try {
+      noteRuntimeApiCompressionCapability({
+        baseUrl,
+        header: response.headers?.get(RUNTIME_API_ACCEPTS_HEADER),
+      });
+    } catch {
+      // A response without readable headers teaches nothing; it never fails.
+    }
     if (response.ok) {
       try {
         const parsed = (await response.json()) as TResponse;
@@ -1383,6 +1584,28 @@ async function postAppRuntimeApi<TResponse>(
           maxAttempts,
           finalAttemptStartedAt: attemptStartedAt,
         });
+        if (context.onResponseMeta) {
+          try {
+            context.onResponseMeta({
+              action: body.action,
+              requestId:
+                response.headers.get('x-deepline-request-id')?.trim() || null,
+              // Request send to parsed response, on the runner's clock. The
+              // gateway's own timings are subtracted from this to leave the
+              // network and TLS cost of the hop.
+              roundTripMs: Date.now() - attemptStartedAt,
+              serverTiming: parseRuntimeGatewayServerTiming(
+                response.headers.get('server-timing'),
+              ),
+              requestBodyRawBytes: wireBody.rawBytes,
+              requestBodyWireBytes: wireBody.wireBytes,
+              requestBodySerializeMs,
+              requestBodyPackMs,
+            });
+          } catch {
+            // Observation must never affect durable delivery.
+          }
+        }
         return parsed;
       } catch (error) {
         await retryAppRuntimeBodyTimeoutOrThrow({
@@ -1396,6 +1619,7 @@ async function postAppRuntimeApi<TResponse>(
           httpStatus: response.status,
           boundaryLabel,
         });
+        attempt += 1;
         continue;
       }
     }
@@ -1441,6 +1665,23 @@ async function postAppRuntimeApi<TResponse>(
         retryAfterMs: appRuntimeRetryAfterMs(response, ''),
         boundaryLabel,
       });
+      attempt += 1;
+      continue;
+    }
+    if (
+      !usedLegacyDecoderFallback &&
+      isLegacyRuntimeApiGzipDecoderFailure({
+        contentEncoding: wireBody.contentEncoding,
+        status: response.status,
+        responseText,
+      })
+    ) {
+      // An older gateway reached through a rolling hostname rejected gzip
+      // before JSON parsing, so no runtime action was dispatched. Demote the
+      // hostname capability and resend the same serialized request plain.
+      revokeRuntimeApiCompressionCapability(baseUrl);
+      forceUncompressedNextAttempt = true;
+      usedLegacyDecoderFallback = true;
       continue;
     }
     const responseCode = appRuntimeErrorCode(response, responseText);
@@ -1481,6 +1722,7 @@ async function postAppRuntimeApi<TResponse>(
         httpStatus: response.status,
       });
       await sleep(retryDelayMs);
+      attempt += 1;
       continue;
     }
     recordAppRuntimeRetryFailure({
@@ -2393,6 +2635,27 @@ export async function completeRuntimeStepReceiptsViaAppRuntime(
   });
 }
 
+/**
+ * Publish receipt-owned R2 references written by the trusted execution relay.
+ * This deliberately has its own action name so an older gateway rejects it
+ * instead of treating a missing legacy `output` as a successful null write.
+ */
+export async function completeRuntimeStepReceiptsByReferenceViaAppRuntime(
+  context: WorkerRuntimeApiContext,
+  input: Omit<
+    Extract<
+      RuntimeApiRequest,
+      { action: 'complete_runtime_step_receipts_by_reference' }
+    >,
+    'action'
+  >,
+): Promise<Array<RuntimeStepReceipt | null>> {
+  return await postAppRuntimeApi<Array<RuntimeStepReceipt | null>>(context, {
+    action: 'complete_runtime_step_receipts_by_reference',
+    ...input,
+  });
+}
+
 export async function failRuntimeStepReceiptViaAppRuntime(
   context: WorkerRuntimeApiContext,
   input: Omit<