deepline 0.3.44 → 0.3.45

package/dist/bundling-sources/shared_libs/play-runtime/sandbox-runs/runner-backend-adapter.ts

@@ -0,0 +1,304 @@
+import type {
+  PlayRunnerBackend,
+  PlayRunnerCallbacks,
+  PlayRunnerRuntimeLifecycleEvent,
+  PlayRunnerRuntimeResource,
+} from '../runner-backends/types';
+import { SandboxRunnerPreCodeDeferralError } from '../runner-backends/types';
+import type {
+  PlayCheckpoint,
+  PlayExecutionEvent,
+  PlayRowUpdate,
+} from '../ctx-types';
+import type {
+  PlayRunnerExecutionConfig,
+  PlayRunnerLogEvent,
+  PlayRunnerResult,
+} from '../protocol';
+import type {
+  SandboxExecutionLifecycle,
+  SandboxExecutionPort,
+  SandboxExecutionPortOutcome,
+  SandboxExecutionResource,
+} from './contract';
+
+/**
+ * The named scheduler read needed by an already-running runner. It is not a
+ * generic callback bag: it is the one scheduler observation the backend needs
+ * to turn accepted detached work into a safe suspension.
+ */
+export type SandboxRunnerReadiness = (input: {
+  baselineHeartbeatAt?: string | null;
+}) => Promise<{ ready: boolean; heartbeatAt: string | null } | null>;
+
+/** Progress is orthogonal to sandbox lifecycle and remains a separate port. */
+export type SandboxRunnerProgress = {
+  onLog?: (event: PlayRunnerLogEvent) => void;
+  onCheckpoint?: (checkpoint: PlayCheckpoint) => void;
+  onRowUpdate?: (update: PlayRowUpdate) => void;
+  onExecutionEvent?: (event: PlayExecutionEvent) => void;
+};
+
+/**
+ * Existing runner results have a broader status vocabulary than Sandbox Runs.
+ * The worker owns retry/terminal policy, so it must make this conversion
+ * explicit rather than letting the adapter guess whether a failed result is
+ * safe to retry.
+ */
+export type SandboxRunnerResultInterpreter = (input: {
+  result: PlayRunnerResult;
+}) =>
+  | SandboxExecutionPortOutcome<PlayRunnerResult>
+  | Promise<SandboxExecutionPortOutcome<PlayRunnerResult>>;
+
+export type SandboxRunnerBackendAdapterDependencies = {
+  backend: PlayRunnerBackend;
+  readiness: SandboxRunnerReadiness;
+  interpretResult: SandboxRunnerResultInterpreter;
+  cancellationSignal?: AbortSignal;
+  progress?: SandboxRunnerProgress;
+};
+
+/**
+ * Concrete Adapter from the long-lived PlayRunnerBackend callback protocol to
+ * the Sandbox Runs Interface.
+ *
+ * This is intentionally the only place that builds a PlayRunnerCallbacks bag.
+ * Callers supply named scheduler ports and receive the deep Sandbox Runs
+ * lifecycle; runner-backend compatibility remains local to this Adapter.
+ */
+export function createPlayRunnerBackendSandboxExecutionAdapter(
+  dependencies: SandboxRunnerBackendAdapterDependencies,
+): SandboxExecutionPort<
+  PlayRunnerExecutionConfig,
+  PlayCheckpoint,
+  unknown,
+  PlayRunnerResult
+> {
+  return {
+    async execute({ execution, lifecycle }) {
+      if (execution.mode.kind === 'detached_observation') {
+        throw new Error(
+          'PlayRunnerBackend Sandbox Runs Adapter cannot observe a detached runner; the scheduler must resolve persisted runner state without invoking a backend.',
+        );
+      }
+      if (execution.mode.kind === 'fresh') {
+        const admission = await lifecycle.beforeFirstProviderCreate();
+        if (admission.kind === 'pre_code_deferred') return admission;
+      }
+      const resources = new Map<string, SandboxExecutionResource>();
+      const callbacks = createRunnerCallbacks({
+        lifecycle,
+        resources,
+        readiness: dependencies.readiness,
+        cancellationSignal: dependencies.cancellationSignal,
+        progress: dependencies.progress,
+      });
+      let result: PlayRunnerResult;
+      try {
+        result = await dependencies.backend.execute(
+          execution.launch,
+          callbacks,
+        );
+      } catch (error) {
+        if (error instanceof SandboxRunnerPreCodeDeferralError) {
+          return { kind: 'pre_code_deferred', reason: error.reason };
+        }
+        throw error;
+      }
+      const outcome = await dependencies.interpretResult({ result });
+      return outcome.kind === 'suspended' &&
+        result.status === 'suspended' &&
+        result.suspension.kind === 'detached_runner'
+        ? { ...outcome, requiresDetachedRunnerReadiness: true }
+        : outcome;
+    },
+  };
+}
+
+function createRunnerCallbacks(input: {
+  lifecycle: SandboxExecutionLifecycle;
+  resources: Map<string, SandboxExecutionResource>;
+  readiness: SandboxRunnerReadiness;
+  cancellationSignal?: AbortSignal;
+  progress?: SandboxRunnerProgress;
+}): PlayRunnerCallbacks {
+  const remember = (resource: PlayRunnerRuntimeResource) => {
+    const converted = toSandboxResource(resource);
+    input.resources.set(resourceKey(converted), converted);
+    return converted;
+  };
+  const requireResource = (
+    provider: 'daytona' | 'modal',
+    sandboxId: string,
+  ) => {
+    const resource = input.resources.get(`${provider}:${sandboxId}`);
+    if (!resource) {
+      throw new Error(
+        `PlayRunnerBackend reported ${provider} command acceptance for ${sandboxId} before recording its Sandbox Runs resource fact.`,
+      );
+    }
+    return resource;
+  };
+
+  return {
+    cancellationSignal: input.cancellationSignal,
+    onLog: input.progress?.onLog,
+    onCheckpoint: input.progress?.onCheckpoint,
+    onRowUpdate: input.progress?.onRowUpdate,
+    onExecutionEvent: input.progress?.onExecutionEvent,
+    readDetachedRunnerReadiness: async (baselineHeartbeatAt) =>
+      await input.readiness({ baselineHeartbeatAt }),
+    onRuntimeResourceAcquired: async (resource) => {
+      await input.lifecycle.recordResource(remember(resource));
+    },
+    onLateRuntimeResourceAcquired: async (resource) => {
+      await input.lifecycle.recordLateResource(remember(resource));
+    },
+    onAmbiguousModalCreateIntent: async (intent) => {
+      await input.lifecycle.recordCreateIntent({
+        provider: 'modal',
+        routingDomain: intent.modalAppId,
+        runtimeEnvironment: intent.runtimeEnvironment,
+        correlation: intent.tags,
+        ...(intent.sandboxCapacityLeaseId
+          ? { capacityLeaseId: intent.sandboxCapacityLeaseId }
+          : {}),
+      });
+    },
+    onAmbiguousModalCreateResolved: async () => {
+      await input.lifecycle.resolveCreateIntent();
+    },
+    reserveSandboxCapacity: async (provider, providerAttempt) => {
+      const outcome = await input.lifecycle.reserveCapacity({
+        provider,
+        providerAttempt,
+      });
+      if (outcome.kind !== 'reserved') {
+        throw new SandboxRunnerPreCodeDeferralError(outcome.reason);
+      }
+      return {
+        leaseId: outcome.leaseId,
+        providerOperationToken: outcome.providerOperationToken ?? null,
+      };
+    },
+    releaseSandboxCapacity: async (leaseId) => {
+      await input.lifecycle.releaseCapacity({ leaseId });
+    },
+    shouldAttemptSandboxProvider: async (provider) =>
+      await input.lifecycle.claimProviderCircuit({ provider }),
+    markSandboxProviderHealthy: async (provider, probeToken) => {
+      await input.lifecycle.markProviderHealthy({ provider, probeToken });
+    },
+    onRuntimeLifecycleEvent: async (event) => {
+      await input.lifecycle.recordProviderLifecycleEvent(
+        toProviderLifecycleEvent(event),
+      );
+    },
+    onRunnerCommandAccepted: ({ provider, sandboxId }) => {
+      const resource = requireResource(provider, sandboxId);
+      input.lifecycle.commandAccepted({ provider, resource });
+    },
+    onDetachedRunnerReady: ({
+      provider,
+      sandboxId,
+      boundaryId,
+      baselineHeartbeatAt,
+    }) => {
+      const resource = requireResource(provider, sandboxId);
+      input.lifecycle.runnerReady({
+        provider,
+        resource,
+        observation: { boundaryId, baselineHeartbeatAt },
+      });
+    },
+  };
+}
+
+function toSandboxResource(
+  resource: PlayRunnerRuntimeResource,
+): SandboxExecutionResource {
+  const isModal = resource.kind === 'modal_sandbox';
+  return {
+    kind: resource.kind,
+    provider: isModal ? 'modal' : 'daytona',
+    resourceId: resource.sandboxId,
+    routingDomain: isModal
+      ? (resource.modalAppId ?? null)
+      : (resource.daytonaOrganizationId ?? null),
+    billingStartedAtMs: resource.billingStartedAt,
+    billingEndedAtMs: resource.billingEndedAt ?? null,
+    lateAcquired: resource.lateAcquired,
+    maxBillingDurationSeconds: resource.maxBillingDurationSeconds ?? null,
+    cpu: resource.cpu ?? null,
+    memoryGiB: resource.memoryGiB ?? null,
+    diskGiB: resource.diskGiB ?? null,
+    // Historical Daytona facts use `daytonaEnvironment`; normalize it at the
+    // portable boundary so the cleanup job stays in the resource's actual
+    // runtime lane rather than falling back to production.
+    runtimeEnvironment:
+      resource.runtimeEnvironment ??
+      resource.daytonaEnvironment ??
+      'production',
+    ...(resource.sandboxCapacityLeaseId
+      ? { capacityLeaseId: resource.sandboxCapacityLeaseId }
+      : {}),
+  };
+}
+
+/**
+ * Rehydrate the established scheduler storage representation at the concrete
+ * Postgres Adapter seam. The portable Sandbox Runs contract remains free of
+ * runner-backend compatibility fields such as `sandboxId` and
+ * `daytonaOrganizationId`.
+ */
+export function playRunnerRuntimeResourceFromSandboxExecutionResource(
+  resource: SandboxExecutionResource,
+): PlayRunnerRuntimeResource {
+  const isModal = resource.provider === 'modal';
+  if (resource.kind === 'local_process' || resource.provider === 'local') {
+    throw new Error(
+      'The PlayRunnerBackend Sandbox Runs Adapter cannot persist a local process as a physical runtime resource.',
+    );
+  }
+  return {
+    kind: isModal ? 'modal_sandbox' : 'daytona_sandbox',
+    sandboxId: resource.resourceId,
+    runtimeEnvironment: resource.runtimeEnvironment,
+    ...(isModal
+      ? { modalAppId: resource.routingDomain ?? undefined }
+      : {
+          daytonaEnvironment: resource.runtimeEnvironment,
+          daytonaOrganizationId: resource.routingDomain ?? undefined,
+        }),
+    billingStartedAt: resource.billingStartedAtMs,
+    billingEndedAt: resource.billingEndedAtMs ?? null,
+    lateAcquired: resource.lateAcquired,
+    maxBillingDurationSeconds: resource.maxBillingDurationSeconds ?? null,
+    cpu: resource.cpu ?? null,
+    memoryGiB: resource.memoryGiB ?? null,
+    diskGiB: resource.diskGiB ?? null,
+    ...(resource.capacityLeaseId
+      ? { sandboxCapacityLeaseId: resource.capacityLeaseId }
+      : {}),
+  };
+}
+
+function resourceKey(resource: SandboxExecutionResource): string {
+  return `${resource.provider}:${resource.resourceId}`;
+}
+
+function toProviderLifecycleEvent(event: PlayRunnerRuntimeLifecycleEvent) {
+  const type = event.type.replace('daytona_', '') as
+    | 'create_call_started'
+    | 'create_call_succeeded'
+    | 'create_call_failed';
+  return {
+    provider: 'daytona' as const,
+    type,
+    providerAttempt: event.providerAttempt,
+    occurredAtMs: event.occurredAtMs,
+    ...(event.sandboxId ? { resourceId: event.sandboxId } : {}),
+    ...(event.errorClass ? { errorClass: event.errorClass } : {}),
+  };
+}

package/dist/bundling-sources/shared_libs/play-runtime/sandbox-runs/testkit.ts

@@ -0,0 +1,83 @@
+import type {
+  SandboxAcquisition,
+  SandboxRunDependencies,
+  SandboxRunInput,
+  SandboxRunResource,
+  SandboxRunnerObservation,
+} from './contract';
+
+type RecordingEvent =
+  | { kind: 'acquire'; input: SandboxRunInput }
+  | { kind: 'record'; resource: SandboxRunResource }
+  | { kind: 'start'; resource: SandboxRunResource }
+  | { kind: 'observe'; resource: SandboxRunResource };
+
+type RecordingPlan<Handle> = {
+  acquisition: SandboxAcquisition<Handle>;
+  record?: 'recorded' | 'fence_lost';
+  start?:
+    | { kind: 'command_accepted'; observation: SandboxRunnerObservation }
+    | { kind: 'not_started'; reason: string }
+    | { kind: 'start_unknown'; reason: string };
+  observe?:
+    | { kind: 'heartbeat_observed'; heartbeatAt: string }
+    | {
+        kind: 'terminal_observed';
+        terminal: 'completed' | 'failed' | 'cancelled';
+      }
+    | { kind: 'unconfirmed'; reason: string };
+};
+
+/**
+ * Test-only real recording ports. They model the Module Interface rather than
+ * spying on a runner-backend file or duplicating its implementation.
+ */
+export function createRecordingSandboxRunPorts<Handle>(
+  plan: RecordingPlan<Handle>,
+): SandboxRunDependencies<Handle> & {
+  events(): readonly RecordingEvent[];
+} {
+  const events: RecordingEvent[] = [];
+  return {
+    acquire: {
+      async acquire(input) {
+        events.push({ kind: 'acquire', input });
+        return plan.acquisition;
+      },
+    },
+    resourceFacts: {
+      async record(input) {
+        events.push({ kind: 'record', resource: input.resource });
+        return { kind: plan.record ?? 'recorded' };
+      },
+    },
+    runner: {
+      async start(input) {
+        events.push({ kind: 'start', resource: input.resource });
+        return (
+          plan.start ?? {
+            kind: 'command_accepted',
+            observation: {
+              boundaryId: `detached-runner:${input.attempt.runId}:${input.attempt.number}`,
+              baselineHeartbeatAt: null,
+            },
+          }
+        );
+      },
+    },
+    observer: {
+      async observe(input) {
+        events.push({ kind: 'observe', resource: input.resource });
+        return (
+          plan.observe ?? {
+            kind: 'heartbeat_observed',
+            heartbeatAt: '2026-08-26T00:00:01.000Z',
+          }
+        );
+      },
+    },
+    events() {
+      return events;
+    },
+  };
+}

package/dist/bundling-sources/shared_libs/play-runtime/tool-call/always-fresh-adapter.ts

@@ -0,0 +1,50 @@
+import type { ToolExecuteResult } from '../tool-result';
+import {
+  createToolCallJob,
+  type ToolCallDispatcher,
+  type ToolCallInput,
+} from './index';
+
+/**
+ * The authored facts for an operation that is deliberately not durable.
+ *
+ * There is no compatibility identity here by design.  A provider adapter
+ * receives `providerOperationKey: null` and must therefore omit the
+ * provider-idempotency header.  Repeating this call means repeating the
+ * physical provider operation, even when the two calls are otherwise equal.
+ */
+export type AlwaysFreshToolCallInput = Omit<
+  ToolCallInput,
+  'execution' | 'compatibility'
+> & {
+  execution: Omit<ToolCallInput['execution'], 'persistence'>;
+};
+
+export type AlwaysFreshToolCall = {
+  call(input: AlwaysFreshToolCallInput): Promise<ToolExecuteResult>;
+};
+
+/**
+ * Adapts the receiptless direct/map runtime paths onto ToolCall.
+ *
+ * This is not an in-memory receipt implementation.  It selects ToolCall's
+ * explicit `always-fresh` protocol, which validates the same authored facts
+ * as a receipt-backed call while making no durable claim, recovery, heartbeat,
+ * completion, or provider-operation assertion.
+ */
+export function createAlwaysFreshToolCallAdapter(input: {
+  dispatcher: ToolCallDispatcher;
+}): AlwaysFreshToolCall {
+  const toolCall = createToolCallJob({ dispatcher: input.dispatcher });
+  return {
+    async call(call) {
+      return await toolCall.call({
+        ...call,
+        execution: {
+          ...call.execution,
+          persistence: 'always-fresh',
+        },
+      });
+    },
+  };
+}

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

@@ -0,0 +1,135 @@
+import type { ToolExecuteResult } from '../tool-result';
+
+/** The response transformation requested by the authored Play artifact. */
+export type ToolCallResultFormat = 'legacy' | 'v2' | 'raw-v2';
+
+/**
+ * Transitional identities supplied by the existing runtime.
+ *
+ * The result receipt and provider-operation identities deliberately remain
+ * caller-owned until the new Integration Operation store has replaced the
+ * historical cache/fence records. ToolCall must pass them through unchanged:
+ * deriving replacement keys here would strand completed work or redispatch a
+ * provider operation during the rolling migration.
+ */
+export type ToolCallCompatibilityIdentity = {
+  resultReceiptKey: string;
+  providerOperationKey: string;
+};
+
+/**
+ * Whether this call has a durable Tool Result Receipt.  An always-fresh call
+ * is intentionally not a forced variant of a cached call: it has neither a
+ * receipt to replay nor a provider-operation identity to send downstream.
+ */
+export type ToolCallPersistence = 'receipt' | 'always-fresh';
+
+/** Facts from the authored call; neither headers nor credentials cross here. */
+export type ToolCallInput = {
+  scope: {
+    organizationId: string;
+    /** The play-local execution/cache boundary selected by the program. */
+    playScope: string;
+  };
+  tool: {
+    id: string;
+    providerActionVersion: string;
+  };
+  payload: Record<string, unknown>;
+  authorization?: {
+    /** Opaque digest; credential material never enters this Module. */
+    scopeDigest?: string | null;
+  };
+  output: {
+    /** Dataset/raw/row-artifact distinguish provider-operation intent. */
+    intent: string;
+    format: ToolCallResultFormat;
+    revision?: string | null;
+  };
+  execution: {
+    /** The dispatcher Adapter owns the direct/map implementation difference. */
+    mode: 'direct' | 'map';
+    ownerRunId: string;
+    force?: boolean;
+    /** Defaults to a durable result receipt for compatibility callers. */
+    persistence?: ToolCallPersistence;
+  };
+  /**
+   * Existing durable identities.  They must be absent for always-fresh calls:
+   * inventing a local key would silently turn a receiptless operation into a
+   * provider-idempotent one.
+   */
+  compatibility?: ToolCallCompatibilityIdentity;
+};
+
+export type ToolCallReceiptLease = {
+  leaseId: string;
+  ownerRunId: string;
+};
+
+/** Lets an Adapter preserve the runtime's cached versus in-flight result ABI. */
+export type ToolCallReceiptRecoverySource = 'cache' | 'in_flight';
+
+/** Durable Tool Result Receipt lifecycle, independent of a storage engine. */
+export type ToolResultReceipts = {
+  claim(input: {
+    resultReceiptKey: string;
+    ownerRunId: string;
+    force: boolean;
+  }): Promise<
+    | { kind: 'completed'; result: ToolExecuteResult }
+    | { kind: 'owned'; lease: ToolCallReceiptLease }
+    | { kind: 'following' }
+  >;
+  recover(input: {
+    resultReceiptKey: string;
+    ownerRunId: string;
+    source: ToolCallReceiptRecoverySource;
+  }): Promise<ToolExecuteResult>;
+  heartbeat(input: {
+    resultReceiptKey: string;
+    lease: ToolCallReceiptLease;
+  }): Promise<'active' | 'completed' | 'lost'>;
+  complete(input: {
+    resultReceiptKey: string;
+    lease: ToolCallReceiptLease;
+    result: ToolExecuteResult;
+  }): Promise<
+    | { kind: 'stored'; result: ToolExecuteResult }
+    | { kind: 'existing'; result: ToolExecuteResult }
+  >;
+  fail(input: {
+    resultReceiptKey: string;
+    lease: ToolCallReceiptLease;
+    error: unknown;
+  }): Promise<void>;
+};
+
+/** Direct and map execution are Adapter choices, never separate public jobs. */
+export type ToolCallDispatcher = {
+  dispatch(input: {
+    call: ToolCallInput;
+    /** Null means the adapter must not emit a provider-idempotency identity. */
+    providerOperationKey: string | null;
+    /** Null means this is a receiptless, always-fresh physical call. */
+    receipt: ToolCallReceiptLease | null;
+  }): Promise<ToolExecuteResult>;
+};
+
+export type ToolCallDependencies = {
+  /** Required only by the durable-receipt branch. */
+  resultReceipts?: ToolResultReceipts;
+  dispatcher: ToolCallDispatcher;
+};
+
+/** The intentionally small public Interface of the Tool Call Module. */
+export type ToolCallJob = {
+  call(input: ToolCallInput): Promise<ToolExecuteResult>;
+};
+
+export class ToolCallReceiptLeaseLostError extends Error {
+  constructor(resultReceiptKey: string) {
+    super(`Lost Tool Result Receipt lease for ${resultReceiptKey}.`);
+    this.name = 'ToolCallReceiptLeaseLostError';
+  }
+}