deepline 0.2.74 → 0.3.1

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

@@ -51,6 +51,7 @@ export type AcquiredDaytonaSandbox = {
   daytonaOrganizationId: string;
   billingStartedAt: number;
   billingEndedAt?: number;
+  sandboxCapacityLeaseId?: string;
 };
 
 export type OneShotDaytonaSandboxLifecycle = {
@@ -118,6 +119,7 @@ type DaytonaCreateResult = {
   sandbox: DaytonaSandbox;
   attempt: number;
   attemptElapsedMs: number;
+  sandboxCapacityLeaseId?: string;
 };
 
 function daytonaCreateErrorClass(
@@ -133,6 +135,8 @@ function daytonaCreateErrorClass(
 async function rejectAcquiredSandbox(
   sandbox: DaytonaSandbox,
   reason: string,
+  reservation?: { leaseId: string },
+  releaseSandboxCapacity?: (leaseId: string) => Promise<void>,
 ): Promise<never> {
   try {
     await sandbox.delete(30);
@@ -143,6 +147,9 @@ async function rejectAcquiredSandbox(
       { cause: error },
     );
   }
+  if (reservation) {
+    await releaseSandboxCapacity?.(reservation.leaseId);
+  }
   throw new Error(reason);
 }
 
@@ -350,6 +357,8 @@ async function createRetriedOneShotDaytonaSandbox(input: {
   context: DaytonaExecutionContext;
   emitStage: DaytonaStageEmitter;
   observeCreateCall?: DaytonaCreateCallObserver;
+  reserveSandboxCapacity?: () => Promise<{ leaseId: string }>;
+  releaseSandboxCapacity?: (leaseId: string) => Promise<void>;
   nextProviderAttempt: () => number;
   startedAt: number;
 }): Promise<DaytonaCreateResult> {
@@ -372,6 +381,7 @@ async function createRetriedOneShotDaytonaSandbox(input: {
       occurredAtMs: attemptStartedAt,
       providerAttempt: attempt,
     });
+    const reservation = await input.reserveSandboxCapacity?.();
     let sandbox: DaytonaSandbox;
     try {
       sandbox = await createOneShotDaytonaSandbox({
@@ -381,6 +391,12 @@ async function createRetriedOneShotDaytonaSandbox(input: {
         sandboxName,
       });
     } catch (error) {
+      // A normal rejected create has no durable provider resource. A timeout
+      // can be ambiguous, so retain its lease until the crash TTL rather than
+      // admitting another sandbox against an unknown provider outcome.
+      if (reservation && !isDaytonaSandboxStartTimeout(String(error))) {
+        await input.releaseSandboxCapacity?.(reservation.leaseId);
+      }
       await input.observeCreateCall?.({
         type: 'daytona_create_call_failed',
         occurredAtMs: Date.now(),
@@ -407,6 +423,13 @@ async function createRetriedOneShotDaytonaSandbox(input: {
           sandboxName,
         });
         if (deleted) {
+          // The provider-confirmed reconciliation means this reservation can
+          // no longer represent a live sandbox. Release before returning the
+          // acquisition-unavailable result so Modal fallback is not blocked
+          // behind the unbound crash TTL.
+          if (reservation) {
+            await input.releaseSandboxCapacity?.(reservation.leaseId);
+          }
           throw new DaytonaSandboxAcquisitionUnavailableError(
             'daytona_sandbox_start_timeout',
             `${message} Timed-out Daytona sandbox was reconciled and deleted before fallback.`,
@@ -448,6 +471,7 @@ async function createRetriedOneShotDaytonaSandbox(input: {
       sandbox,
       attempt,
       attemptElapsedMs: acquiredAt - attemptStartedAt,
+      ...(reservation ? { sandboxCapacityLeaseId: reservation.leaseId } : {}),
     };
   }
   const message = `Daytona sandbox create failed across ${errors.length} bounded attempts: ${errors.join('; ')}`;
@@ -468,6 +492,8 @@ async function acquireOneShotDaytonaSandbox(input: {
   context: DaytonaExecutionContext;
   emitStage: DaytonaStageEmitter;
   observeCreateCall?: DaytonaCreateCallObserver;
+  reserveSandboxCapacity?: () => Promise<{ leaseId: string }>;
+  releaseSandboxCapacity?: (leaseId: string) => Promise<void>;
   nextProviderAttempt: () => number;
   startedAt: number;
 }): Promise<AcquiredDaytonaSandbox> {
@@ -493,6 +519,10 @@ async function acquireOneShotDaytonaSandbox(input: {
     await rejectAcquiredSandbox(
       result.sandbox,
       `Daytona sandbox resource boundary mismatch: expected cpu=${limits.cpu} memoryGiB=${limits.memoryGiB} diskGiB=${limits.diskGiB} gpu=${DAYTONA_SANDBOX_GPU}, granted cpu=${granted.cpu} memoryGiB=${granted.memoryGiB} diskGiB=${granted.diskGiB} gpu=${granted.gpu}`,
+      result.sandboxCapacityLeaseId
+        ? { leaseId: result.sandboxCapacityLeaseId }
+        : undefined,
+      input.releaseSandboxCapacity,
     );
   }
   const configuredOrganizationId =
@@ -506,6 +536,10 @@ async function acquireOneShotDaytonaSandbox(input: {
     await rejectAcquiredSandbox(
       result.sandbox,
       'Daytona sandbox organization routing mismatch. Refusing to run customer code in a sandbox whose observed organization differs from the configured organization.',
+      result.sandboxCapacityLeaseId
+        ? { leaseId: result.sandboxCapacityLeaseId }
+        : undefined,
+      input.releaseSandboxCapacity,
     );
   }
   let lookupOrganizationId: string | null = null;
@@ -528,6 +562,10 @@ async function acquireOneShotDaytonaSandbox(input: {
     return await rejectAcquiredSandbox(
       result.sandbox,
       'Daytona sandbox organization routing identity is missing. Refusing to run customer code without a durable cleanup routing domain.',
+      result.sandboxCapacityLeaseId
+        ? { leaseId: result.sandboxCapacityLeaseId }
+        : undefined,
+      input.releaseSandboxCapacity,
     );
   }
   const billingStartedAt = Date.now();
@@ -541,7 +579,14 @@ async function acquireOneShotDaytonaSandbox(input: {
     memoryGiB: granted.memoryGiB,
     diskGiB: granted.diskGiB,
   });
-  return { sandbox, daytonaOrganizationId, billingStartedAt };
+  return {
+    sandbox,
+    daytonaOrganizationId,
+    billingStartedAt,
+    ...(result.sandboxCapacityLeaseId
+      ? { sandboxCapacityLeaseId: result.sandboxCapacityLeaseId }
+      : {}),
+  };
 }
 
 export function createOneShotDaytonaSandboxLifecycle(input: {
@@ -549,6 +594,8 @@ export function createOneShotDaytonaSandboxLifecycle(input: {
   context: DaytonaExecutionContext;
   emitStage: DaytonaStageEmitter;
   observeCreateCall?: DaytonaCreateCallObserver;
+  reserveSandboxCapacity?: () => Promise<{ leaseId: string }>;
+  releaseSandboxCapacity?: (leaseId: string) => Promise<void>;
   startedAt?: number;
 }): OneShotDaytonaSandboxLifecycle {
   const orgId = validateDaytonaExecutionContext(input.context);
@@ -564,6 +611,8 @@ export function createOneShotDaytonaSandboxLifecycle(input: {
       context: input.context,
       emitStage: input.emitStage,
       observeCreateCall: input.observeCreateCall,
+      reserveSandboxCapacity: input.reserveSandboxCapacity,
+      releaseSandboxCapacity: input.releaseSandboxCapacity,
       nextProviderAttempt: () => {
         providerAttempt += 1;
         return providerAttempt;
@@ -594,6 +643,13 @@ export function createOneShotDaytonaSandboxLifecycle(input: {
       try {
         const acquired = await latestAcquiredSandboxPromise;
         await acquired.sandbox.delete(30);
+        // `dispose` has provider-confirmed that the sandbox is gone. This is
+        // normally the narrow cancellation window before the scheduler has
+        // durably recorded the resource, so no cleanup job will release an
+        // unbound lease on our behalf.
+        if (acquired.sandboxCapacityLeaseId) {
+          await input.releaseSandboxCapacity?.(acquired.sandboxCapacityLeaseId);
+        }
       } catch (error) {
         console.warn('[play-runner.daytona.dispose_failed_before_acquire]', {
           error: error instanceof Error ? error.message : String(error),

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

@@ -5,7 +5,10 @@ import type {
   PlayRunnerPreparedExecution,
   PlayRunnerPrepareInput,
 } from '../types';
-import { RuntimeResourceFenceLostError } from '../types';
+import {
+  isRuntimeSandboxCapacityLimitError,
+  RuntimeResourceFenceLostError,
+} from '../types';
 import { buildPlayRunnerBundle } from '../bundle';
 import { findPlayRunnerResult, parsePlayRunnerEvents } from '../runner-events';
 import type {
@@ -26,6 +29,7 @@ import {
   DaytonaSandboxAcquisitionUnavailableError,
   createDaytonaSandboxCleanupManager,
   createOneShotDaytonaSandboxLifecycle,
+  type AcquiredDaytonaSandbox,
   type DaytonaClient,
   type DaytonaExecutionContext,
   type DaytonaSandbox,
@@ -945,6 +949,10 @@ function prepareDaytonaExecution(
     emitStage: (stage, extra) =>
       emitDaytonaStage(callbacks, input.context, stage, extra),
     observeCreateCall: callbacks?.onRuntimeLifecycleEvent,
+    reserveSandboxCapacity: callbacks?.reserveSandboxCapacity
+      ? () => callbacks.reserveSandboxCapacity!('daytona')
+      : undefined,
+    releaseSandboxCapacity: callbacks?.releaseSandboxCapacity,
   });
   return {
     kind: 'daytona',
@@ -1055,22 +1063,12 @@ export const daytonaPlayRunnerBackend: PlayRunnerBackend = {
     };
     let cancellationRequested = false;
     let cancellationCleanupStarted = false;
-    let activeAcquiredResource: {
-      sandbox: DaytonaSandbox;
-      daytonaOrganizationId: string;
-      billingStartedAt: number;
-      billingEndedAt?: number;
-    } | null = null;
+    let activeAcquiredResource: AcquiredDaytonaSandbox | null = null;
     const uploadDeadlineBreaches: DaytonaUploadAttemptTiming[] = [];
     const reportedSandboxIds = new Set<string>();
     const reportedSandboxEndTimes = new Map<string, number | null>();
     const runtimeResourceReportErrors = new Set<unknown>();
-    const reportRuntimeResource = async (acquired: {
-      sandbox: DaytonaSandbox;
-      daytonaOrganizationId: string;
-      billingStartedAt: number;
-      billingEndedAt?: number;
-    }) => {
+    const reportRuntimeResource = async (acquired: AcquiredDaytonaSandbox) => {
       const sandbox = acquired.sandbox;
       const billingEndedAt = acquired.billingEndedAt ?? null;
       if (
@@ -1101,6 +1099,9 @@ export const daytonaPlayRunnerBackend: PlayRunnerBackend = {
           cpu: typeof sandbox.cpu === 'number' ? sandbox.cpu : null,
           memoryGiB: typeof sandbox.memory === 'number' ? sandbox.memory : null,
           diskGiB: typeof sandbox.disk === 'number' ? sandbox.disk : null,
+          ...(acquired.sandboxCapacityLeaseId
+            ? { sandboxCapacityLeaseId: acquired.sandboxCapacityLeaseId }
+            : {}),
         });
       } catch (error) {
         runtimeResourceReportErrors.add(error);
@@ -1109,12 +1110,9 @@ export const daytonaPlayRunnerBackend: PlayRunnerBackend = {
       reportedSandboxIds.add(sandbox.id);
       reportedSandboxEndTimes.set(sandbox.id, billingEndedAt);
     };
-    const reportRetiringRuntimeResource = async (acquired: {
-      sandbox: DaytonaSandbox;
-      daytonaOrganizationId: string;
-      billingStartedAt: number;
-      billingEndedAt?: number;
-    }) => {
+    const reportRetiringRuntimeResource = async (
+      acquired: AcquiredDaytonaSandbox,
+    ) => {
       try {
         await reportRuntimeResource(acquired);
       } catch (error) {
@@ -1429,6 +1427,9 @@ export const daytonaPlayRunnerBackend: PlayRunnerBackend = {
         }
         throw error;
       }
+      if (isRuntimeSandboxCapacityLimitError(error)) {
+        throw error;
+      }
       if (error instanceof DaytonaSandboxAcquisitionUnavailableError) {
         throw error;
       }

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

@@ -1,6 +1,9 @@
 import type { ModalClient } from 'modal';
 import type { PlayRunnerBackend, PlayRunnerCallbacks } from '../types';
-import { RuntimeResourceFenceLostError } from '../types';
+import {
+  isRuntimeSandboxCapacityLimitError,
+  RuntimeResourceFenceLostError,
+} from '../types';
 import { buildPlayRunnerBundle } from '../bundle';
 import type {
   PlayRunnerExecutionConfig,
@@ -23,6 +26,7 @@ import { stageRunnerPayload } from './daytona-payload-transport';
 import { captureDetachedDaytonaRunnerReadinessBaseline } from './daytona-session-execution';
 
 const MODAL_RUNNER_READY_TIMEOUT_MS = 30_000;
+const MODAL_CAPACITY_RELEASE_RETRY_DELAYS_MS = [0, 100, 500, 2_000] as const;
 type ModalSandbox = Awaited<ReturnType<ModalClient['sandboxes']['create']>>;
 
 export function modalSandboxLifetimeMs(
@@ -99,13 +103,38 @@ async function confirmDetachedModalRunnerReady(input: {
   );
 }
 
-async function terminateModalSandbox(sandbox: ModalSandbox): Promise<void> {
-  await sandbox.terminate().catch((error) => {
+async function terminateModalSandbox(sandbox: ModalSandbox): Promise<boolean> {
+  try {
+    // The default terminate call only acknowledges the request. Capacity may
+    // be released only after Modal confirms the sandbox itself has stopped.
+    await sandbox.terminate({ wait: true });
+    return true;
+  } catch (error) {
     console.warn('[play-runner.modal.terminate_failed]', {
       sandboxId: sandbox.sandboxId,
       error: error instanceof Error ? error.message : String(error),
     });
-  });
+    return false;
+  }
+}
+
+async function releaseModalSandboxCapacityAfterConfirmedTermination(input: {
+  leaseId: string;
+  release: NonNullable<PlayRunnerCallbacks['releaseSandboxCapacity']>;
+}): Promise<void> {
+  let lastError: unknown;
+  for (const delayMs of MODAL_CAPACITY_RELEASE_RETRY_DELAYS_MS) {
+    if (delayMs > 0) {
+      await new Promise<void>((resolve) => setTimeout(resolve, delayMs));
+    }
+    try {
+      await input.release(input.leaseId);
+      return;
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  throw lastError;
 }
 
 export const modalPlayRunnerBackend: PlayRunnerBackend = {
@@ -139,24 +168,35 @@ export const modalPlayRunnerBackend: PlayRunnerBackend = {
         createIfMissing: true,
       });
       const image = modalConfig.client.images.fromRegistry(modalConfig.image);
-      const sandbox = await modalConfig.client.sandboxes.create(app, image, {
-        cpu: MODAL_SANDBOX_CPU_CORES,
-        cpuLimit: MODAL_SANDBOX_CPU_CORES,
-        memoryMiB: MODAL_SANDBOX_MEMORY_MIB,
-        memoryLimitMiB: MODAL_SANDBOX_MEMORY_MIB,
-        timeoutMs: modalSandboxLifetimeMs(modalConfig.limits),
-        idleTimeoutMs: modalSandboxLifetimeMs(modalConfig.limits),
-        workdir: modalConfig.workdir,
-        tags: {
-          source: 'deepline-play-runner',
-          orgId: config.context.orgId ?? 'unknown',
-          workflowId: config.context.workflowId ?? 'unknown',
-          runId: config.context.runId ?? 'unknown',
-        },
-        ...(modalConfig.outboundCidrAllowlist
-          ? { outboundCidrAllowlist: modalConfig.outboundCidrAllowlist }
-          : {}),
-      });
+      const capacityReservation =
+        await callbacks?.reserveSandboxCapacity?.('modal');
+      const sandbox = await modalConfig.client.sandboxes
+        .create(app, image, {
+          cpu: MODAL_SANDBOX_CPU_CORES,
+          cpuLimit: MODAL_SANDBOX_CPU_CORES,
+          memoryMiB: MODAL_SANDBOX_MEMORY_MIB,
+          memoryLimitMiB: MODAL_SANDBOX_MEMORY_MIB,
+          timeoutMs: modalSandboxLifetimeMs(modalConfig.limits),
+          idleTimeoutMs: modalSandboxLifetimeMs(modalConfig.limits),
+          workdir: modalConfig.workdir,
+          tags: {
+            source: 'deepline-play-runner',
+            orgId: config.context.orgId ?? 'unknown',
+            workflowId: config.context.workflowId ?? 'unknown',
+            runId: config.context.runId ?? 'unknown',
+          },
+          ...(modalConfig.outboundCidrAllowlist
+            ? { outboundCidrAllowlist: modalConfig.outboundCidrAllowlist }
+            : {}),
+        })
+        .catch(async (error) => {
+          if (capacityReservation) {
+            await callbacks?.releaseSandboxCapacity?.(
+              capacityReservation.leaseId,
+            );
+          }
+          throw error;
+        });
       const billingStartedAt = Date.now();
       runtimeTiming.modalCreateMs = billingStartedAt - startedAt;
       emitModalStage(config.context, 'create:done', {
@@ -164,6 +204,7 @@ export const modalPlayRunnerBackend: PlayRunnerBackend = {
         elapsedMs: runtimeTiming.modalCreateMs,
       });
       let detached = false;
+      let setupError: unknown;
       let cancelExecution!: (error: Error) => void;
       const cancellationPromise = new Promise<never>((_resolve, reject) => {
         cancelExecution = reject;
@@ -192,6 +233,9 @@ export const modalPlayRunnerBackend: PlayRunnerBackend = {
             cpu: MODAL_SANDBOX_CPU_CORES,
             memoryGiB: MODAL_SANDBOX_MEMORY_MIB / 1024,
             diskGiB: 0,
+            ...(capacityReservation
+              ? { sandboxCapacityLeaseId: capacityReservation.leaseId }
+              : {}),
           });
         } catch (error) {
           runtimeResourceRegistrationError = error;
@@ -290,14 +334,45 @@ export const modalPlayRunnerBackend: PlayRunnerBackend = {
           tableNamespace: null,
           runtimeTiming,
         };
+      } catch (error) {
+        setupError = error;
+        throw error;
       } finally {
         callbacks?.cancellationSignal?.removeEventListener('abort', onCancel);
-        if (!detached) await terminateModalSandbox(sandbox);
+        if (!detached && (await terminateModalSandbox(sandbox))) {
+          // This branch synchronously confirms that the just-created resource
+          // is gone. Do not keep its admission lease until the cleanup loop
+          // sees a resource that no longer exists.
+          if (capacityReservation && callbacks?.releaseSandboxCapacity) {
+            try {
+              await releaseModalSandboxCapacityAfterConfirmedTermination({
+                leaseId: capacityReservation.leaseId,
+                release: callbacks.releaseSandboxCapacity,
+              });
+            } catch (releaseError) {
+              // The scheduler fence is the primary correctness signal. Keep
+              // it intact if its best-effort early capacity release is
+              // transiently unavailable; durable cleanup will retry release.
+              if (setupError) {
+                console.error('[play-runner.modal.capacity_release_failed]', {
+                  sandboxId: sandbox.sandboxId,
+                  error:
+                    releaseError instanceof Error
+                      ? releaseError.message
+                      : String(releaseError),
+                });
+              } else {
+                throw releaseError;
+              }
+            }
+          }
+        }
       }
     } catch (error) {
       if (
         error === runtimeResourceRegistrationError ||
-        error instanceof RuntimeResourceFenceLostError
+        error instanceof RuntimeResourceFenceLostError ||
+        isRuntimeSandboxCapacityLimitError(error)
       ) {
         throw error;
       }
@@ -335,7 +410,7 @@ export async function deleteModalSandboxById(input: {
       appId: expectedAppId,
     })) {
       if (sandbox.sandboxId !== input.sandboxId) continue;
-      await sandbox.terminate();
+      await sandbox.terminate({ wait: true });
       return { kind: 'deleted', appId: expectedAppId };
     }
     // Cleanup means ensure absent. An exact app-scoped inventory proving the

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

@@ -28,6 +28,8 @@ export type PlayRunnerRuntimeResource = {
   cpu?: number | null;
   memoryGiB?: number | null;
   diskGiB?: number | null;
+  /** Scheduler-only soft-capacity reservation made before provider create. */
+  sandboxCapacityLeaseId?: string;
 };
 
 export type RuntimeResourceTerminalReason =
@@ -64,6 +66,23 @@ export class RuntimeResourceFenceLostError extends Error {
   }
 }
 
+/**
+ * A scheduler-owned admission result crosses the provider-backend boundary.
+ * Keep it typed by name here so the shared backend can rethrow it without an
+ * import from the app-owned scheduler implementation.
+ */
+export const RUNTIME_SANDBOX_CAPACITY_LIMIT_ERROR_NAME =
+  'RuntimeSandboxCapacityLimitError';
+
+export function isRuntimeSandboxCapacityLimitError(
+  error: unknown,
+): error is Error {
+  return (
+    error instanceof Error &&
+    error.name === RUNTIME_SANDBOX_CAPACITY_LIMIT_ERROR_NAME
+  );
+}
+
 export interface PlayRunnerCallbacks {
   onLog?: (event: PlayRunnerLogEvent) => void;
   onCheckpoint?: (checkpoint: PlayCheckpoint) => void;
@@ -72,6 +91,12 @@ export interface PlayRunnerCallbacks {
   onRuntimeResourceAcquired?: (
     resource: PlayRunnerRuntimeResource,
   ) => void | Promise<void>;
+  /** Reserve one physical-sandbox slot immediately before a provider create. */
+  reserveSandboxCapacity?: (
+    provider: 'daytona' | 'modal',
+  ) => Promise<{ leaseId: string }>;
+  /** Release an unbound reservation when provider create never produced a resource. */
+  releaseSandboxCapacity?: (leaseId: string) => Promise<void>;
   /**
    * Durable scheduler-owned evidence for a provider create call. Backends
    * await this callback at the create boundary; it is not best-effort logging.

package/dist/bundling-sources/shared_libs/play-runtime/runtime-capacity-policy.ts

@@ -13,7 +13,6 @@ export const RUNTIME_CAPACITY_POLICY = {
     /** 32 Machines x 8 claim slots permits 256 concurrent launch/resume legs. */
     maxActiveLaneMachines: 32,
     workerSlotsPerMachine: 8,
-    perOrgConcurrency: 4,
     /** Queue age is an escape hatch for small-but-stuck backlogs. */
     scaleUpQueueAgeMs: 10_000,
     /** Bound one Fly reconciliation without turning backlog into a stampede. */
@@ -113,14 +112,6 @@ export function assertRuntimeCapacityPolicy(): void {
       'Receipt claim operations must leave at least five seconds for cancellation and response delivery.',
     );
   }
-  if (
-    RUNTIME_CAPACITY_POLICY.absurd.perOrgConcurrency >
-    ABSURD_GLOBAL_RUN_CONCURRENCY
-  ) {
-    throw new Error(
-      'Per-org runtime concurrency cannot exceed global runtime concurrency.',
-    );
-  }
   if (
     RUNTIME_CAPACITY_POLICY.absurd.activeLaneMachines >
     RUNTIME_CAPACITY_POLICY.absurd.maxActiveLaneMachines

package/dist/bundling-sources/shared_libs/play-runtime/tool-response-contract.ts

@@ -0,0 +1,89 @@
+/**
+ * Public tool-response contracts shared by the API, SDK, Play bundler, and
+ * runtime. A response contract is transport behavior, never Play authoring.
+ */
+export const V2_TOOL_RESPONSE_CONTRACT = 'v2-tool-response' as const;
+export const RAW_V2_TOOL_RESPONSE_CONTRACT = 'raw-v2' as const;
+
+export type ToolResponseContract =
+  | typeof V2_TOOL_RESPONSE_CONTRACT
+  | typeof RAW_V2_TOOL_RESPONSE_CONTRACT;
+
+export type ToolResponseView = 'data' | 'rawV2';
+
+export function isToolResponseContract(
+  value: unknown,
+): value is ToolResponseContract {
+  return (
+    value === V2_TOOL_RESPONSE_CONTRACT ||
+    value === RAW_V2_TOOL_RESPONSE_CONTRACT
+  );
+}
+
+export class UnsupportedToolResponseContractError extends Error {
+  constructor(value: unknown) {
+    super(
+      `Unsupported tool response contract ${String(value)}. Supported contracts: ${V2_TOOL_RESPONSE_CONTRACT}, ${RAW_V2_TOOL_RESPONSE_CONTRACT}.`,
+    );
+    this.name = 'UnsupportedToolResponseContractError';
+  }
+}
+
+/** Missing artifact compatibility predates canonical bodies and stays V2. */
+export function normalizeToolResponseContract(
+  value: unknown,
+): ToolResponseContract {
+  if (value == null) return V2_TOOL_RESPONSE_CONTRACT;
+  if (isToolResponseContract(value)) return value;
+  throw new UnsupportedToolResponseContractError(value);
+}
+
+export function legacyRawFromToolResponseRawV2(
+  rawV2: unknown,
+  view: ToolResponseView,
+  responseMeta?: Record<string, unknown>,
+): unknown {
+  const legacyRaw =
+    view === 'data' &&
+    rawV2 &&
+    typeof rawV2 === 'object' &&
+    !Array.isArray(rawV2)
+      ? (rawV2 as Record<string, unknown>).data
+      : rawV2;
+  // Before raw-v2, an async launch without a data envelope exposed
+  // Deepline's billing summary at `toolResponse.raw.deepline_billing`.
+  // The canonical response keeps it separate from provider data, so reattach
+  // it only to this derived legacy view.
+  const deeplineBilling = responseMeta?.deepline_billing;
+  if (
+    view === 'rawV2' &&
+    deeplineBilling !== undefined &&
+    legacyRaw &&
+    typeof legacyRaw === 'object' &&
+    !Array.isArray(legacyRaw)
+  ) {
+    return {
+      ...(legacyRaw as Record<string, unknown>),
+      deepline_billing: deeplineBilling,
+    };
+  }
+  return legacyRaw;
+}
+
+export function providerMetaFromToolResponseRawV2(
+  rawV2: unknown,
+  view: ToolResponseView,
+): Record<string, unknown> | undefined {
+  if (
+    view !== 'data' ||
+    !rawV2 ||
+    typeof rawV2 !== 'object' ||
+    Array.isArray(rawV2)
+  ) {
+    return undefined;
+  }
+  const meta = (rawV2 as Record<string, unknown>).meta;
+  return meta && typeof meta === 'object' && !Array.isArray(meta)
+    ? (meta as Record<string, unknown>)
+    : undefined;
+}

package/dist/bundling-sources/shared_libs/play-runtime/tool-result-types.ts

@@ -75,7 +75,7 @@ export type ToolResultEnvelope<
   meta?: TMeta;
 };
 
-export type SerializedToolExecuteResult = {
+export type SerializedToolExecuteResultV1 = {
   __kind: 'deepline.tool_execute_result.v1';
   status: string;
   job_id?: string;
@@ -98,11 +98,36 @@ export type SerializedToolExecuteResult = {
   execution: ToolResultExecutionMetadata;
 };
 
+/**
+ * Canonical receipt form. Provider data is stored once as `rawV2`; the legacy
+ * raw/meta view is recreated from the payload-free projection descriptor.
+ */
+export type SerializedToolExecuteResultV2 = Omit<
+  SerializedToolExecuteResultV1,
+  '__kind' | 'toolResponse'
+> & {
+  __kind: 'deepline.tool_execute_result.v2';
+  toolResponse: {
+    rawV2: unknown;
+    view: 'data' | 'rawV2';
+    /** Deepline-owned additions not already represented in `rawV2.meta`. */
+    responseMeta?: Record<string, unknown>;
+  };
+};
+
+export type SerializedToolExecuteResult =
+  | SerializedToolExecuteResultV1
+  | SerializedToolExecuteResultV2;
+
 export type ToolResponseEnvelope<
   TData = unknown,
   TMeta = Record<string, unknown>,
 > = {
   raw: TData;
+  /** Complete parsed and scrubbed provider response, materialized from raw-v2. */
+  rawV2?: unknown;
+  /** Durable descriptor for deriving the legacy raw view from `rawV2`. */
+  view?: 'data' | 'rawV2';
   meta?: TMeta;
 };
 
@@ -156,8 +181,9 @@ export type ToolExecuteResultAccessors<
  * Canonical result returned by Deepline tool execution.
  *
  * The top-level object is Deepline-owned execution metadata and semantic
- * extraction state. Raw tool/provider data lives under `toolResponse.raw`;
- * response metadata lives under `toolResponse.meta`. Semantic single-value
+ * extraction state. The canonical provider response lives under
+ * `toolResponse.rawV2`; `toolResponse.raw` remains the legacy compatibility
+ * projection. Response metadata lives under `toolResponse.meta`. Semantic single-value
  * getters live under `extractedValues.<name>.get()`, and list getters live
  * under `extractedLists.<name>.get()`.
  *