deepline 0.3.127 → 0.3.129

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

@@ -10,7 +10,7 @@ import type {
 } from '../protocol';
 
 export type PlayRunnerRuntimeResource = {
-  kind: 'daytona_sandbox' | 'modal_sandbox';
+  kind: 'daytona_sandbox' | 'modal_sandbox' | 'agentcore_runtime_session';
   sandboxId: string;
   /** Runtime estate that owns provider credentials and durable cleanup. */
   runtimeEnvironment?: 'preview' | 'production';
@@ -19,6 +19,12 @@ export type PlayRunnerRuntimeResource = {
   daytonaOrganizationId?: string;
   /** Stable, non-secret Modal ownership domain returned at acquisition. */
   modalAppId?: string;
+  /**
+   * Stable, non-secret ownership domain for a session-based runtime. The
+   * provider adapter supplies this value; the shared flow only persists it as
+   * the cleanup routing domain.
+   */
+  agentcoreRuntimeArn?: string;
   billingStartedAt: number;
   billingEndedAt?: number | null;
   /**
@@ -85,7 +91,7 @@ export type PlayRunnerRuntimeLifecycleEvent = {
  * resource identity to cross the no-replay boundary.
  */
 export type PlayRunnerCommandAcceptance = {
-  provider: 'daytona' | 'modal';
+  provider: 'daytona' | 'modal' | 'agentcore_runtime';
   sandboxId: string;
 };
 
@@ -171,7 +177,7 @@ export interface PlayRunnerCallbacks {
   onAmbiguousModalCreateResolved?: () => void | Promise<void>;
   /** Reserve one physical-sandbox slot immediately before a provider create. */
   reserveSandboxCapacity?: (
-    provider: 'daytona' | 'modal',
+    provider: 'daytona' | 'modal' | 'agentcore_runtime',
     providerAttempt?: number,
   ) => Promise<{ leaseId: string; providerOperationToken: string | null }>;
   /** Release an unbound reservation when provider create never produced a resource. */
@@ -182,11 +188,11 @@ export interface PlayRunnerCallbacks {
    * pre-code recovery outcome instead.
    */
   shouldAttemptSandboxProvider?: (
-    provider: 'daytona' | 'modal',
+    provider: 'daytona' | 'modal' | 'agentcore_runtime',
   ) => Promise<{ allowed: boolean; probeToken: string | null }>;
   /** A durably recorded resource may close only the probe that owns it. */
   markSandboxProviderHealthy?: (
-    provider: 'daytona' | 'modal',
+    provider: 'daytona' | 'modal' | 'agentcore_runtime',
     probeToken: string | null,
   ) => Promise<void>;
   /**

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

@@ -6,6 +6,10 @@ import type { PlayRunLedgerEvent } from './run-ledger';
 import type { WorkReceiptFailureKind } from './work-receipts';
 import type { ToolExecutionFailureV1 } from '../plays/tool-execution-error';
 import type { DocflowObservationUpsert } from './docflow-observation';
+import type {
+  RuntimeReceiptValueInlineFields,
+  RuntimeReceiptValueReference,
+} from './runtime-receipt-value';
 
 export type RuntimeAppendRunEventsAction = {
   action: 'append_run_events';
@@ -96,12 +100,16 @@ export type RuntimeReceiptAction =
       playName: string;
       runId: string;
       key: string;
+      /** Omit receipt outputs while probing completed-cache manifests. */
+      hydrateOutput?: boolean;
     }
   | {
       action: 'get_runtime_step_receipts';
       playName: string;
       runId: string;
       keys: string[];
+      /** Omit receipt outputs while probing completed-cache manifests. */
+      hydrateOutput?: boolean;
     }
   | {
       action: 'acquire_runtime_receipt_execution_lock';
@@ -123,6 +131,8 @@ export type RuntimeReceiptAction =
       playName: string;
       runId: string;
       key: string;
+      /** Omit terminal output bodies while establishing a receipt claim. */
+      hydrateOutput?: boolean;
       leaseId?: string;
       runAttempt?: number | null;
       leaseAware?: boolean;
@@ -135,6 +145,8 @@ export type RuntimeReceiptAction =
       playName: string;
       runId: string;
       keys: string[];
+      /** Omit terminal output bodies while establishing receipt claims. */
+      hydrateOutput?: boolean;
       leaseIds?: string[];
       runAttempt?: number | null;
       leaseAware?: boolean;
@@ -150,6 +162,7 @@ export type RuntimeReceiptAction =
       runAttempt?: number | null;
       leaseId?: string | null;
       output: unknown;
+      inlineFields?: RuntimeReceiptValueInlineFields;
     }
   | {
       action: 'release_runtime_step_receipt';
@@ -205,6 +218,18 @@ export type RuntimeReceiptAction =
       runId: string;
       receipts: RuntimeReceiptCompletion[];
     }
+  | {
+      /**
+       * New named action: the execution relay has already persisted the full
+       * serialized result to the receipt-owned R2 key. A receiver that does
+       * not know this action rejects it loudly; the runner then retries the
+       * established full-payload completion without replaying provider work.
+       */
+      action: 'complete_runtime_step_receipts_by_reference';
+      playName: string;
+      runId: string;
+      receipts: RuntimeReceiptReferenceCompletion[];
+    }
   | {
       action: 'fail_runtime_step_receipts';
       playName: string;
@@ -234,6 +259,11 @@ export type RuntimeReceiptLease = {
 
 export type RuntimeReceiptCompletion = RuntimeReceiptLease & {
   output: unknown;
+  inlineFields?: RuntimeReceiptValueInlineFields;
+};
+
+export type RuntimeReceiptReferenceCompletion = RuntimeReceiptLease & {
+  outputRef: RuntimeReceiptValueReference;
 };
 
 export type RuntimeReceiptFailure = RuntimeReceiptLease & {

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

@@ -0,0 +1,276 @@
+/**
+ * Wire compression for runtime API request bodies.
+ *
+ * WHY THIS EXISTS. A fixture sandbox sits ~95 ms from the Fly receipt gateway
+ * (Daytona eu, Fly iad). Measured on run 34104186304, a ~100 KB receipt
+ * completion request (12 receipts x ~8 KB) took 765 ms p50 on the runner's
+ * clock while the gateway's own `Server-Timing` accounted for 50 ms of it. The
+ * missing 700 ms is not the gateway and not the network's bandwidth: it is TCP
+ * congestion-window growth. A keep-alive connection that idles between
+ * completion batches has its cwnd reset toward the initial window (~10 MSS,
+ * ~14 KB), so a 100 KB upload is delivered over 5-8 round trips of ~95 ms each
+ * before the gateway has the whole body to parse. jai's ~1 MB completion
+ * requests pay the same arithmetic at ~5.4 s.
+ *
+ * Moving the sandbox region is an ops action and is being pursued separately.
+ * Independent of it, the round trips are a function of BYTES, so shrinking the
+ * body shrinks the wall directly. Measured gzip level 6 on realistic receipt
+ * payloads: high-entropy enrichment output compresses to ~24% (a 100 KB body
+ * becomes ~24 KB, which fits in 1-2 congestion windows instead of 5-8), and
+ * repetitive output to ~4-6%.
+ *
+ * COMPATIBILITY. A gateway that does not understand `content-encoding: gzip`
+ * would hand gzip bytes to `JSON.parse` and fail every request, so the client
+ * never compresses speculatively. It compresses only after it has seen the
+ * gateway advertise `x-deepline-runtime-api-accepts: gzip` on a response from
+ * that base URL. The first request to any origin is therefore always
+ * uncompressed, and an older gateway (or an app route that has not shipped the
+ * decoder) simply never advertises and never receives a compressed body. In the
+ * other direction, a newer gateway keeps accepting uncompressed bodies from
+ * older runners forever: the encoding is opt-in per request, not a version gate.
+ */
+
+import { gzip, gunzip } from 'node:zlib';
+import { promisify } from 'node:util';
+
+const gzipAsync = promisify(gzip);
+const gunzipAsync = promisify(gunzip);
+
+/**
+ * Bodies at or above this size are gzipped before they are sent.
+ *
+ * 16 KiB is one congestion window plus change. Below it the body already fits
+ * in the first flight of an established connection (initial window ~10 MSS,
+ * ~14 KB), so compressing buys no round trip — it only spends CPU on the
+ * runner's single vCPU and adds a gzip header the gateway has to inflate. At
+ * and above it, every ~14 KB removed from the wire removes roughly one ~95 ms
+ * round trip from the request (measured above: 100 KB = 765 ms client / 50 ms
+ * server; the ~700 ms difference is cwnd growth, not bandwidth).
+ *
+ * The threshold is compared against the UTF-8 byte length of the serialized
+ * body, not its character count.
+ */
+export const RUNTIME_API_REQUEST_COMPRESSION_MIN_BYTES = 16 * 1024;
+
+/**
+ * zlib level for request bodies. Level 6 is the measured optimum at one vCPU
+ * on the sandbox's ~15 Mbit/s link (51 runs, 6.17 MB raw batch): level 6
+ * costs 539 ms and ships 889 KB, level 1 costs 418 ms and ships 1306 KB, no
+ * gzip costs 183 ms and ships 6025 KB. Batches per second are bounded by
+ * whichever side binds: min(CPU, link) = 1.90 at level 6, 1.44 at level 1,
+ * 0.31 with no gzip. Level 1 saves 121 ms of CPU and buys 417 KB of wire that
+ * costs 223 ms. If the search moves, it moves up from 6, not down. See the
+ * cost table in `gzipRuntimeApiRequestBody`.
+ */
+export const RUNTIME_API_REQUEST_COMPRESSION_LEVEL = 6;
+
+/**
+ * The gateway's advertisement that it can decode compressed request bodies.
+ *
+ * Present on EVERY gateway response, including errors and health probes, so a
+ * client learns the capability from whatever response it happens to get first
+ * rather than needing a successful request of a particular action.
+ */
+export const RUNTIME_API_ACCEPTS_HEADER = 'x-deepline-runtime-api-accepts';
+
+/** The only encoding this contract defines. */
+export const RUNTIME_API_ACCEPTS_GZIP = 'gzip';
+
+/** Does an `x-deepline-runtime-api-accepts` value advertise gzip? */
+export function runtimeApiAcceptsHeaderAdvertisesGzip(
+  header: string | null | undefined,
+): boolean {
+  if (typeof header !== 'string') return false;
+  return header
+    .split(',')
+    .some((token) => token.trim().toLowerCase() === RUNTIME_API_ACCEPTS_GZIP);
+}
+
+/** Is a request's `content-encoding` gzip? */
+export function isGzipContentEncoding(
+  header: string | null | undefined,
+): boolean {
+  return typeof header === 'string' && header.trim().toLowerCase() === 'gzip';
+}
+
+/**
+ * Origins observed to advertise gzip, keyed by base URL origin.
+ *
+ * State is per process and per origin, never per request: a runner talks to one
+ * receipt gateway and one app runtime API for its whole life, so one observed
+ * response enables compression until that origin proves otherwise. The state
+ * cannot be monotonic: a rolling Fly fleet can route two requests for the same
+ * hostname to different Machine revisions, and an older revision cannot decode
+ * a gzip body even if its newer peer advertised support moments earlier.
+ */
+const gzipCapableOrigins = new Set<string>();
+
+function compressionOriginKey(baseUrl: string): string {
+  const trimmed = baseUrl.trim();
+  if (!trimmed) return '';
+  try {
+    return new URL(trimmed).origin;
+  } catch {
+    // A non-URL base is still a stable key; it just cannot be normalized.
+    return trimmed.replace(/\/$/, '');
+  }
+}
+
+/**
+ * Record what one response said about its gateway's request-decoding support.
+ *
+ * Called for every response, successful or not. A response that carries no
+ * advertisement teaches nothing and never revokes a prior advertisement.
+ */
+export function noteRuntimeApiCompressionCapability(input: {
+  baseUrl: string;
+  header: string | null | undefined;
+}): void {
+  if (!runtimeApiAcceptsHeaderAdvertisesGzip(input.header)) return;
+  const key = compressionOriginKey(input.baseUrl);
+  if (key) gzipCapableOrigins.add(key);
+}
+
+/**
+ * Forget an origin after its legacy JSON decoder rejected a gzip body.
+ *
+ * The caller retries that exact request as plain JSON before any durable action
+ * can have run. A subsequent response from a newer Machine may advertise gzip
+ * again, but a rolling hostname is never treated as permanently capable.
+ */
+export function revokeRuntimeApiCompressionCapability(baseUrl: string): void {
+  const key = compressionOriginKey(baseUrl);
+  if (key) gzipCapableOrigins.delete(key);
+}
+
+/**
+ * Is this the exact response emitted when a pre-gzip gateway parsed compressed
+ * bytes as JSON? Restrict the fallback to this known pre-dispatch failure so a
+ * normal 400 from a gzip-capable gateway is never replayed.
+ */
+export function isLegacyRuntimeApiGzipDecoderFailure(input: {
+  contentEncoding: RuntimeApiRequestBody['contentEncoding'];
+  status: number;
+  responseText: string;
+}): boolean {
+  if (input.contentEncoding !== 'gzip' || input.status !== 400) return false;
+  try {
+    const parsed = JSON.parse(input.responseText) as { error?: unknown };
+    return parsed.error === 'JSON body is required.';
+  } catch {
+    return false;
+  }
+}
+
+/** Has this origin advertised that it can decode gzipped request bodies? */
+export function runtimeApiOriginAcceptsGzip(baseUrl: string): boolean {
+  const key = compressionOriginKey(baseUrl);
+  return key ? gzipCapableOrigins.has(key) : false;
+}
+
+/** Forget every observed capability. Tests only; there is no production reset. */
+export function resetRuntimeApiCompressionCapabilities(): void {
+  gzipCapableOrigins.clear();
+}
+
+export type RuntimeApiRequestBody = {
+  /** What goes on the wire. */
+  body: string | Uint8Array;
+  /** `gzip` when compressed, otherwise null (send no `content-encoding`). */
+  contentEncoding: 'gzip' | null;
+  /** UTF-8 bytes of the serialized JSON, before any compression. */
+  rawBytes: number;
+  /** Bytes actually sent. Equals `rawBytes` when uncompressed. */
+  wireBytes: number;
+};
+
+/**
+ * Compress a serialized request body when it is worth compressing.
+ *
+ * ASYNC, NOT SYNC. Measured on this codebase's realistic receipt-completion
+ * payloads (level 6): a 100 KB body costs 2.2 ms and a 1 MB body 26.5 ms, and
+ * `gzipSync` and `promisify(gzip)` have the SAME wall (2.24/2.37 ms and
+ * 26.55/27.13 ms). Identical wall, but the async form runs on the libuv
+ * threadpool instead of blocking the runner's single-vCPU event loop, so the
+ * map keeps advancing rows during the compression of a large completion batch.
+ * A 26 ms synchronous stall on every 1 MB completion is exactly the kind of
+ * per-batch pause the throughput work is removing, so the free version wins.
+ */
+export async function gzipRuntimeApiRequestBody(input: {
+  serialized: string;
+  /** Compress only when the destination has advertised support. */
+  originAcceptsGzip: boolean;
+  minBytes?: number;
+}): Promise<RuntimeApiRequestBody> {
+  const rawBytes = Buffer.byteLength(input.serialized, 'utf8');
+  const minBytes = input.minBytes ?? RUNTIME_API_REQUEST_COMPRESSION_MIN_BYTES;
+  if (!input.originAcceptsGzip || rawBytes < minBytes) {
+    return {
+      body: input.serialized,
+      contentEncoding: null,
+      rawBytes,
+      wireBytes: rawBytes,
+    };
+  }
+  const compressed = await gzipAsync(Buffer.from(input.serialized, 'utf8'), {
+    level: RUNTIME_API_REQUEST_COMPRESSION_LEVEL,
+  });
+  return {
+    body: compressed,
+    contentEncoding: 'gzip',
+    rawBytes,
+    wireBytes: compressed.byteLength,
+  };
+}
+
+/**
+ * A gzipped request body whose DECOMPRESSED size exceeds the gateway limit.
+ *
+ * Loud and typed rather than a generic parse failure: a compressed body is the
+ * one shape where the transport's own byte guard cannot see the real size, so
+ * the caller must be told the limit it actually crossed. The gateway surfaces
+ * this as the same 413 an oversized uncompressed body gets.
+ */
+export class RuntimeApiDecompressedBodyTooLargeError extends Error {
+  constructor(
+    readonly maxBytes: number,
+    readonly wireBytes: number,
+  ) {
+    super(
+      `Runtime API request body decompressed to more than the ${maxBytes} byte limit ` +
+        `(gzip wire size ${wireBytes} bytes). Send fewer receipts per request.`,
+    );
+    this.name = 'RuntimeApiDecompressedBodyTooLargeError';
+  }
+}
+
+/**
+ * Inflate a gzipped request body under a hard output cap.
+ *
+ * `maxOutputLength` makes zlib abort the inflate as soon as the output crosses
+ * the cap, so a zip bomb costs the gateway the bytes it was actually sent plus
+ * one buffer of the limit — never the decompressed size. Without it a 500 KB
+ * body could expand to gigabytes before any byte guard downstream saw it.
+ *
+ * Async for the same reason the client compresses asynchronously: inflate is
+ * cheap (0.2 ms for 100 KB, 2.2 ms for 1 MB) but the gateway multiplexes many
+ * runners on one event loop, and the threadpool version costs ~1 ms more wall
+ * for work that no longer blocks every other in-flight request.
+ */
+export async function gunzipRuntimeApiRequestBody(input: {
+  body: Buffer;
+  maxBytes: number;
+}): Promise<Buffer> {
+  try {
+    return await gunzipAsync(input.body, { maxOutputLength: input.maxBytes });
+  } catch (error) {
+    const code = (error as { code?: unknown } | null)?.code;
+    if (code === 'ERR_BUFFER_TOO_LARGE' || code === 'ERR_OUT_OF_RANGE') {
+      throw new RuntimeApiDecompressedBodyTooLargeError(
+        input.maxBytes,
+        input.body.byteLength,
+      );
+    }
+    throw error;
+  }
+}