deepline 0.1.249 → 0.1.251

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

@@ -80,6 +80,13 @@ import type {
 import type { PlayStagedFileRef } from './plays/local-file-discovery.js';
 import type { PlayCompilerManifest } from '../../shared_libs/plays/compiler-manifest.js';
 import type { EnrichCompiledConfig } from './cli/enrich-play-compiler.js';
+import { RUNTIME_ENVIRONMENT_TOKEN_HEADER } from '../../shared_libs/play-runtime/coordinator-headers.js';
+import {
+  normalizePlayRuntimeEnvironment,
+  normalizePlayRuntimeNamespace,
+  normalizePlayRuntimeSelection,
+  type PlayRuntimeSelection,
+} from '../../shared_libs/play-runtime/runtime-environment.js';
 
 const TERMINAL_PLAY_STATUSES = new Set(['completed', 'failed', 'cancelled']);
 const INCLUDE_TOOL_METADATA_HEADER = 'x-deepline-include-tool-metadata';
@@ -109,6 +116,75 @@ function resolvePlayRunIntegrationMode(
   );
 }
 
+function resolvePlayRunRuntimeSelection(
+  request: StartPlayRunRequest,
+): PlayRuntimeSelection | undefined {
+  if (request.runtime !== undefined) {
+    const runtime = normalizePlayRuntimeSelection(request.runtime);
+    if (!runtime) {
+      throw new DeeplineError(
+        'runtime must be exactly { environment: "preview", namespace } with namespace matching ^[a-z][a-z0-9-]{0,30}$.',
+        undefined,
+        'INVALID_RUNTIME_SELECTION',
+      );
+    }
+    return runtime;
+  }
+  // These variables select where the app executes a run, not which app the
+  // SDK calls. DEEPLINE_API_BASE_URL still chooses the app host. Environment
+  // opts into remote preview routing, namespace names the isolated lane, and
+  // the token only authorizes that selection. Omitting all three leaves the
+  // app free to use its native runtime (local for a local app, prod for prod).
+  const configured = process.env.DEEPLINE_RUNTIME_ENVIRONMENT?.trim();
+  const configuredNamespace = process.env.DEEPLINE_RUNTIME_NAMESPACE?.trim();
+  const configuredToken =
+    process.env.DEEPLINE_RUNTIME_ENVIRONMENT_TOKEN?.trim();
+  if (!configured) {
+    if (configuredNamespace || configuredToken) {
+      throw new DeeplineError(
+        'DEEPLINE_RUNTIME_ENVIRONMENT=preview and DEEPLINE_RUNTIME_NAMESPACE are required when runtime selection configuration is present.',
+        undefined,
+        'INVALID_RUNTIME_ENVIRONMENT',
+      );
+    }
+    return undefined;
+  }
+  const environment = normalizePlayRuntimeEnvironment(configured);
+  if (!environment) {
+    throw new DeeplineError(
+      `DEEPLINE_RUNTIME_ENVIRONMENT supports only explicit preview selection. Received "${configured}". Omit it to use the app-native runtime.`,
+      undefined,
+      'INVALID_RUNTIME_ENVIRONMENT',
+    );
+  }
+  const namespace = normalizePlayRuntimeNamespace(configuredNamespace);
+  if (!namespace) {
+    throw new DeeplineError(
+      'DEEPLINE_RUNTIME_NAMESPACE is required for preview and must match ^[a-z][a-z0-9-]{0,30}$.',
+      undefined,
+      'INVALID_RUNTIME_NAMESPACE',
+    );
+  }
+  return { environment, namespace };
+}
+
+function runtimeSelectionHeaders(
+  runtime: PlayRuntimeSelection | undefined,
+): Record<string, string> | undefined {
+  if (!runtime) return undefined;
+  // Keep the credential out of the typed runtime payload. The app consumes it
+  // at the HTTP boundary and never forwards it to Fly, Absurd, or Daytona.
+  const token = process.env.DEEPLINE_RUNTIME_ENVIRONMENT_TOKEN?.trim();
+  if (!token) {
+    throw new DeeplineError(
+      'DEEPLINE_RUNTIME_ENVIRONMENT_TOKEN is required for explicit preview runtime selection.',
+      undefined,
+      'RUNTIME_ENVIRONMENT_TOKEN_REQUIRED',
+    );
+  }
+  return { [RUNTIME_ENVIRONMENT_TOKEN_HEADER]: token };
+}
+
 function normalizeTestPolicyOverrides(
   value: unknown,
   source: string,
@@ -1577,6 +1653,7 @@ export class DeeplineClient {
     const testPolicyOverrides =
       request.testPolicyOverrides ?? parseEnvTestPolicyOverrides();
     const forceToolRefresh = request.forceToolRefresh === true;
+    const runtime = resolvePlayRunRuntimeSelection(request);
     const response = await this.http.post<Record<string, unknown>>(
       '/api/v2/plays/run',
       {
@@ -1619,9 +1696,10 @@ export class DeeplineClient {
         // defaults to absurd; callers normally omit this field.
         ...(request.profile ? { profile: request.profile } : {}),
         ...(integrationMode ? { integrationMode } : {}),
+        ...(runtime ? { runtime } : {}),
         ...(testPolicyOverrides ? { testPolicyOverrides } : {}),
       },
-      undefined,
+      runtimeSelectionHeaders(runtime),
       // A start can reach the server even when its response is lost or times
       // out. Retrying this mutation without an idempotency key can create a
       // second root run, so callers must resolve ambiguous failures explicitly.
@@ -1649,6 +1727,7 @@ export class DeeplineClient {
     const testPolicyOverrides =
       request.testPolicyOverrides ?? parseEnvTestPolicyOverrides();
     const forceToolRefresh = request.forceToolRefresh === true;
+    const runtime = resolvePlayRunRuntimeSelection(request);
     const body = {
       ...(request.name ? { name: request.name } : {}),
       ...(request.revisionId ? { revisionId: request.revisionId } : {}),
@@ -1687,6 +1766,7 @@ export class DeeplineClient {
         : {}),
       ...(request.profile ? { profile: request.profile } : {}),
       ...(integrationMode ? { integrationMode } : {}),
+      ...(runtime ? { runtime } : {}),
       ...(testPolicyOverrides ? { testPolicyOverrides } : {}),
     };
     for await (const event of this.http.streamSse<PlayLiveEvent>(
@@ -1694,6 +1774,7 @@ export class DeeplineClient {
       {
         method: 'POST',
         body,
+        headers: runtimeSelectionHeaders(runtime),
         signal: options?.signal,
       },
     )) {

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

@@ -113,7 +113,7 @@ export const SDK_RELEASE = {
   // runtime intentionally no longer compiles at publish or launch time.
   // 0.1.242 removes the retired Workers/ESM compiler, generated bundles, and
   // deploy-time artifact migration. Play authoring now has one CJS contract.
-  version: '0.1.249',
+  version: '0.1.251',
   apiContract: '2026-07-cjs-absurd-only-play-runtime-hard-cutover',
   supportPolicy: {
     minimumSupported: '0.1.53',

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

@@ -1,4 +1,5 @@
 import type { PlayCompilerManifest } from '../../shared_libs/plays/compiler-manifest';
+import type { PlayRuntimeSelection } from '../../shared_libs/play-runtime/runtime-environment';
 import type {
   DeeplineToolCategory,
   PlayBootstrapFinderKind,
@@ -1226,6 +1227,8 @@ export interface StartPlayRunRequest {
   profile?: string;
   /** Optional per-run provider execution mode for eval/smoke runs. */
   integrationMode?: 'live' | 'eval_stub' | 'fixture';
+  /** Internal runtime estate selection. The app host remains unchanged. */
+  runtime?: PlayRuntimeSelection;
   /** Internal/dev-only runtime policy overrides for black-box durability tests. */
   testPolicyOverrides?: Record<string, unknown>;
 }

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

@@ -1542,13 +1542,17 @@ export class PlayContextImpl {
       this.#options.workflowId &&
       this.#options.runId
     ) {
-      const response = await fetch(
-        `${this.#options.baseUrl.replace(/\/$/, '')}${PLAY_RUNTIME_API_COMPAT_PATH}`,
-        {
+      const url = `${this.#options.baseUrl.replace(/\/$/, '')}${PLAY_RUNTIME_API_COMPAT_PATH}`;
+      const requestId = `ctx-secret-${crypto.randomUUID()}`;
+      const startedAt = Date.now();
+      let response: Response;
+      try {
+        response = await fetch(url, {
           method: 'POST',
           headers: {
             Authorization: `Bearer ${this.#options.executorToken}`,
             'Content-Type': 'application/json',
+            'x-deepline-request-id': requestId,
             ...(await this.vercelProtectionHeaders()),
           },
           body: JSON.stringify({
@@ -1556,11 +1560,89 @@ export class PlayContextImpl {
             name: auth.secret.name,
             playName: this.#options.playName,
           }),
-        },
-      );
-      if (response.ok) {
-        const payload = (await response.json()) as { value?: unknown };
-        value = typeof payload.value === 'string' ? payload.value : null;
+        });
+      } catch (error) {
+        const diagnostic = describeTransportError(error);
+        this.log(
+          `[runtime.secret_resolution_failure] ${JSON.stringify({
+            stage: 'transport',
+            secret_name: auth.secret.name,
+            gateway_origin: transportGatewayOriginForDiagnostic(url),
+            request_id: requestId,
+            elapsed_ms: Date.now() - startedAt,
+            error: diagnostic,
+          })}`,
+        );
+        throw new Error(
+          `Secret ${auth.secret.name} resolution transport failed (request_id=${requestId}): ${diagnostic.message ?? 'unknown transport error'}`,
+        );
+      }
+
+      const responseDiagnostic = {
+        stage: response.ok ? 'invalid_response' : 'http_response',
+        secret_name: auth.secret.name,
+        gateway_origin: transportGatewayOriginForDiagnostic(url),
+        request_id: requestId,
+        elapsed_ms: Date.now() - startedAt,
+        http_status: response.status,
+        status_text: response.statusText || null,
+        content_type: response.headers.get('content-type'),
+        server: response.headers.get('server'),
+        vercel_request_id:
+          response.headers.get('x-vercel-id') ??
+          response.headers.get('x-vercel-request-id'),
+        response_request_id: response.headers.get('x-deepline-request-id'),
+        error_code: response.headers.get('x-deepline-error-code'),
+        retry_after: response.headers.get('retry-after'),
+      };
+      if (!response.ok) {
+        this.log(
+          `[runtime.secret_resolution_failure] ${JSON.stringify(responseDiagnostic)}`,
+        );
+        throw new Error(
+          `Secret ${auth.secret.name} is not available to this run (resolution status=${response.status}, request_id=${requestId}).`,
+        );
+      }
+
+      let payload: unknown;
+      try {
+        payload = await response.json();
+      } catch (error) {
+        this.log(
+          `[runtime.secret_resolution_failure] ${JSON.stringify({
+            ...responseDiagnostic,
+            response_kind: 'invalid_json',
+            parse_error_name:
+              error instanceof Error ? error.name : typeof error,
+          })}`,
+        );
+        throw new Error(
+          `Secret ${auth.secret.name} is not available to this run (invalid resolution response, request_id=${requestId}).`,
+        );
+      }
+
+      value =
+        payload &&
+        typeof payload === 'object' &&
+        !Array.isArray(payload) &&
+        typeof (payload as { value?: unknown }).value === 'string'
+          ? (payload as { value: string }).value
+          : null;
+      if (!value) {
+        this.log(
+          `[runtime.secret_resolution_failure] ${JSON.stringify({
+            ...responseDiagnostic,
+            response_kind:
+              payload === null
+                ? 'null'
+                : Array.isArray(payload)
+                  ? 'array'
+                  : typeof payload,
+          })}`,
+        );
+        throw new Error(
+          `Secret ${auth.secret.name} is not available to this run (missing resolution value, request_id=${requestId}).`,
+        );
       }
     } else {
       throw new Error(
@@ -6997,7 +7079,9 @@ export class PlayContextImpl {
                 Object.fromEntries(response.headers.entries()),
               ) as Record<string, string>,
               bodyText: redactedBodyText,
-              json: this.secretRedactor.redact(parseJsonOrNull(bodyText)),
+              json: this.secretRedactor.redactKnownSecrets(
+                parseJsonOrNull(bodyText),
+              ),
             };
 
             this.checkpoint.resolvedBoundaries = {

package/dist/bundling-sources/shared_libs/play-runtime/coordinator-headers.ts

@@ -28,6 +28,13 @@ export const WORKER_CALLBACK_URL_OVERRIDE_HEADER =
   'x-deepline-worker-callback-url';
 export const RUNTIME_SCHEDULER_SCHEMA_OVERRIDE_HEADER =
   'x-deepline-runtime-scheduler-schema';
+/**
+ * CLI-to-app credential used only to authorize a typed runtime-environment
+ * selection. It is deliberately separate from the coordinator credential:
+ * selecting an approved environment must not grant access to runtime callbacks.
+ */
+export const RUNTIME_ENVIRONMENT_TOKEN_HEADER =
+  'x-deepline-runtime-environment-token';
 /**
  * Internal top-level `profile=absurd` launches, including deploy canaries, use
  * this header to pin an exact candidate release before activation. Public API

package/dist/bundling-sources/shared_libs/play-runtime/daytona-runtime-config.ts

@@ -27,10 +27,17 @@ export function daytonaClientOptions(apiKey: string): DaytonaClientOptions {
   };
 }
 
-export function loadDaytonaRequiredConfig(): DaytonaRequiredConfig {
-  const apiKey = process.env.DAYTONA_API_KEY?.trim();
+export function loadDaytonaRequiredConfig(
+  options: {
+    environment?: 'preview' | 'production' | null;
+  } = {},
+): DaytonaRequiredConfig {
+  const environment = options.environment ?? null;
+  const keyName =
+    environment === 'preview' ? 'DAYTONA_API_KEY_PREVIEW' : 'DAYTONA_API_KEY';
+  const apiKey = process.env[keyName]?.trim();
   if (!apiKey) {
-    throw new Error('Missing required Daytona configuration: DAYTONA_API_KEY.');
+    throw new Error(`Missing required Daytona configuration: ${keyName}.`);
   }
   return {
     apiKey,

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

@@ -53,6 +53,13 @@ const RUNTIME_RECEIPT_GATEWAY_TRANSPORT_RETRY_PATTERN =
   /AppRuntimeApiTransportError: App runtime API transport exhausted action=(?:get|claim|mark|complete|fail|heartbeat|release|skip)_runtime_step_receipts?/i;
 const RUNTIME_API_TRANSPORT_RETRY_PATTERN =
   /\bRuntime API request to .+ failed before receiving a response:\s*(?:fetch failed|connection (?:terminated|timed out|closed|reset)|ECONNRESET|ETIMEDOUT|ECONNREFUSED)\b/i;
+// The ready fence precedes customer play execution. A failed detached start is
+// safe to retry only when the runner never wrote its ready marker or attempted
+// the start acknowledgement, and Daytona has no exit evidence. This covers a
+// transient Daytona control-plane blind spot where the accepted command cannot
+// be inspected, while keeping post-start and crash failures terminal.
+const RUNTIME_SANDBOX_UNSTARTED_RETRY_PATTERN =
+  /DaytonaRunnerInitializationError:\s*RUNTIME_SANDBOX_START_FAILED[\s\S]*Marker diagnosis:\s*ready_marker_unavailable[\s\S]*"readyMarkerObserved"\s*:\s*false[\s\S]*"startAcknowledgementAttempted"\s*:\s*false[\s\S]*"exitCode"\s*:\s*null[\s\S]*"exitCodeFile"\s*:\s*null/i;
 const DAYTONA_INFRASTRUCTURE_RETRY_PATTERN =
   /\b(?:Request failed with status code (?:408|429|500|502|503|504)|ECONNRESET|ECONNREFUSED|ETIMEDOUT|UND_ERR_CONNECT_TIMEOUT|fetch failed|socket hang up|Daytona sandbox create failed across|Daytona sandbox create did not complete)\b/i;
 
@@ -446,6 +453,7 @@ export function retryableRuntimeInitializationFailureReason(
   | 'runtime_postgres_connect'
   | 'runtime_api_transport'
   | 'runtime_receipt_gateway_transport'
+  | 'runtime_sandbox_unstarted'
   | null {
   if (result.status !== 'failed') return null;
   if (RUNTIME_POSTGRES_CONNECT_RETRY_PATTERN.test(result.error)) {
@@ -455,6 +463,13 @@ export function retryableRuntimeInitializationFailureReason(
     return 'runtime_receipt_gateway_transport';
   }
   const rowsProcessed = Number(result.stats?.rowsProcessed ?? 0);
+  if (
+    rowsProcessed === 0 &&
+    result.steps.length === 0 &&
+    RUNTIME_SANDBOX_UNSTARTED_RETRY_PATTERN.test(result.error)
+  ) {
+    return 'runtime_sandbox_unstarted';
+  }
   if (
     rowsProcessed === 0 &&
     result.steps.length === 0 &&
@@ -624,6 +639,10 @@ export const daytonaPlayRunnerBackend: PlayRunnerBackend = {
         await callbacks?.onRuntimeResourceAcquired?.({
           kind: 'daytona_sandbox',
           sandboxId: sandbox.id,
+          daytonaEnvironment:
+            process.env.DEEPLINE_RUNTIME_ENVIRONMENT === 'preview'
+              ? 'preview'
+              : 'production',
           billingStartedAt: acquired.billingStartedAt,
           billingEndedAt,
           cpu: typeof sandbox.cpu === 'number' ? sandbox.cpu : null,

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

@@ -12,6 +12,7 @@ import type {
 export type PlayRunnerRuntimeResource = {
   kind: 'daytona_sandbox';
   sandboxId: string;
+  daytonaEnvironment?: 'preview' | 'production';
   billingStartedAt: number;
   billingEndedAt?: number | null;
   terminalReason?: RuntimeResourceTerminalReason | null;

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

@@ -0,0 +1,44 @@
+export const PLAY_RUNTIME_ENVIRONMENTS = ['preview'] as const;
+
+export type PlayRuntimeEnvironment = (typeof PLAY_RUNTIME_ENVIRONMENTS)[number];
+
+export type PlayRuntimeSelection = {
+  environment: 'preview';
+  /** Caller-named isolation scope inside a remote runtime environment. */
+  namespace: string;
+};
+
+const PLAY_RUNTIME_NAMESPACE_PATTERN = /^[a-z][a-z0-9-]{0,30}$/;
+
+export function normalizePlayRuntimeNamespace(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const normalized = value.trim();
+  return PLAY_RUNTIME_NAMESPACE_PATTERN.test(normalized) ? normalized : null;
+}
+
+/** Validate the selector as one value so the SDK and server cannot drift. */
+export function normalizePlayRuntimeSelection(
+  value: unknown,
+): PlayRuntimeSelection | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  if (
+    Object.keys(record).some(
+      (key) => key !== 'environment' && key !== 'namespace',
+    ) ||
+    record.environment !== 'preview'
+  ) {
+    return null;
+  }
+  const namespace = normalizePlayRuntimeNamespace(record.namespace);
+  return namespace ? { environment: 'preview', namespace } : null;
+}
+
+export function normalizePlayRuntimeEnvironment(
+  value: unknown,
+): PlayRuntimeEnvironment | null {
+  return typeof value === 'string' &&
+    PLAY_RUNTIME_ENVIRONMENTS.includes(value as PlayRuntimeEnvironment)
+    ? (value as PlayRuntimeEnvironment)
+    : null;
+}

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

@@ -76,6 +76,7 @@ export function redactSecretLikeString(value: string): string {
 export type SecretRedactionContext = {
   register(value: string): void;
   redactString(value: string): string;
+  redactKnownSecrets<T>(value: T): T;
   redact<T>(value: T): T;
 };
 
@@ -129,9 +130,26 @@ export function createSecretRedactionContext(
     return value;
   }
 
+  function redactKnownSecrets<T>(value: T): T {
+    if (typeof value === 'string') return redactString(value) as T;
+    if (Array.isArray(value)) {
+      return value.map((entry) => redactKnownSecrets(entry)) as T;
+    }
+    if (value && typeof value === 'object') {
+      return Object.fromEntries(
+        Object.entries(value).map(([key, entry]) => [
+          key,
+          redactKnownSecrets(entry),
+        ]),
+      ) as T;
+    }
+    return value;
+  }
+
   return {
     register,
     redactString,
+    redactKnownSecrets,
     redact,
   };
 }