deepline 0.1.119 → 0.1.121

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

@@ -0,0 +1,159 @@
+import type { EmailStatusExtractorConfig } from './email-status';
+import type { DeeplineGetterValueMap } from './extractor-targets';
+
+export type ToolResultExecutionMetadata = {
+  idempotent: true;
+  cached: boolean;
+  source: 'live' | 'checkpoint' | 'cache';
+  cacheKey?: string;
+};
+
+export type ToolResultTargetMetadata = {
+  value: unknown;
+  path: string;
+};
+
+export type ToolResultListMetadata = {
+  path: string;
+  count: number | null;
+  keys: Record<string, string>;
+};
+
+export type ToolResultExtractorDescriptor = {
+  paths: readonly string[];
+  transforms?: readonly string[];
+  enum?: readonly string[];
+  overrides?: readonly ToolResultExtractorOverride[];
+  emailStatus?: EmailStatusExtractorConfig;
+};
+
+export type ToolResultExtractorOverride = {
+  paths: readonly string[];
+  equals?: string | number | boolean | null;
+  value: string | number | boolean | null;
+};
+
+export type ToolResultMetadata = {
+  toolId: string;
+  execution: ToolResultExecutionMetadata;
+  targets: Record<string, ToolResultTargetMetadata>;
+  lists: Record<string, ToolResultListMetadata>;
+  extractors?: Record<string, ToolResultExtractorDescriptor>;
+};
+
+export type ToolResultTargetAccessor<T = unknown> = ToolResultTargetMetadata & {
+  get(): T | null;
+};
+
+export type ToolResultListAccessor<
+  T = Record<string, unknown>,
+  TKey extends string = string,
+> = Omit<ToolResultListMetadata, 'keys'> & {
+  keys: Partial<Record<TKey, string>> & Record<string, string>;
+  get(): T[];
+};
+
+export type ToolResultMetadataInput = {
+  toolId: string;
+  extractors?: Record<string, ToolResultExtractorDescriptor>;
+  targetGetters?: Record<string, readonly string[]>;
+  listExtractorPaths?: readonly string[];
+  listIdentityGetters?: Record<string, readonly string[]>;
+};
+
+export type ToolResultEnvelope<
+  TData = unknown,
+  TMeta = Record<string, unknown>,
+> = {
+  data: TData;
+  meta?: TMeta;
+};
+
+export type SerializedToolExecuteResult = {
+  __kind: 'deepline.tool_execute_result.v1';
+  status: string;
+  toolResponse: {
+    raw: unknown;
+    meta?: Record<string, unknown>;
+  };
+  metadata: ToolResultMetadataInput;
+  execution: ToolResultExecutionMetadata;
+};
+
+export type ToolResponseEnvelope<
+  TData = unknown,
+  TMeta = Record<string, unknown>,
+> = {
+  raw: TData;
+  meta?: TMeta;
+};
+
+export type ToolExecuteResultBase<
+  TResult = unknown,
+  TMeta = Record<string, unknown>,
+> = {
+  status: string;
+  job_id?: string;
+  /** Deepline-owned execution/result metadata. */
+  meta?: Record<string, unknown>;
+  toolResponse: ToolResponseEnvelope<TResult, TMeta>;
+  extractedValues: Record<string, ToolResultTargetAccessor>;
+  extractedLists: Record<string, ToolResultListAccessor>;
+  /** Convenience alias for play code. Serialized output uses toolResponse. */
+  toolOutput: ToolResponseEnvelope<TResult, TMeta>;
+  _metadata: {
+    toolId: string;
+    execution: ToolResultExecutionMetadata;
+    targets: Record<string, { value: unknown; path: string }>;
+    extractors?: Record<string, ToolResultExtractorDescriptor>;
+    lists: Record<
+      string,
+      {
+        path: string;
+        count: number | null;
+        keys: Record<string, string>;
+      }
+    >;
+  };
+};
+
+export type ToolExecuteResultAccessors<
+  TExtracted extends Record<string, unknown> = Partial<DeeplineGetterValueMap>,
+  TLists extends Record<string, Record<string, unknown>> = Record<
+    string,
+    Record<string, unknown>
+  >,
+> = {
+  extractedValues: {
+    [K in keyof TExtracted]: ToolResultTargetAccessor<TExtracted[K]>;
+  };
+  extractedLists: {
+    [K in keyof TLists]: ToolResultListAccessor<TLists[K]>;
+  };
+};
+
+/**
+ * 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
+ * getters live under `extractedValues.<name>.get()`, and list getters live
+ * under `extractedLists.<name>.get()`.
+ *
+ * Use extractors first when a tool contract exposes them. Drop to
+ * `toolResponse.raw` when you need provider-specific fields or when debugging
+ * from persisted run rows.
+ *
+ * @sdkReference runtime 200
+ */
+export type ToolExecuteResult<
+  TResult = unknown,
+  TMeta = Record<string, unknown>,
+  TExtracted extends Record<string, unknown> = Partial<DeeplineGetterValueMap>,
+  TLists extends Record<string, Record<string, unknown>> = Record<
+    string,
+    Record<string, unknown>
+  >,
+> = ToolExecuteResultBase<TResult, TMeta> &
+  ToolExecuteResultAccessors<TExtracted, TLists>;

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

@@ -0,0 +1,33 @@
+type SpanLike = {
+  setAttribute: (key: string, value: unknown) => void;
+};
+
+type SpanOptions = {
+  tracer?: string;
+  attributes?: Record<string, unknown>;
+};
+
+export function setSpanAttributes(
+  span: SpanLike | null | undefined,
+  attributes: Record<string, unknown>,
+): void {
+  for (const [key, value] of Object.entries(attributes)) {
+    span?.setAttribute?.(key, value);
+  }
+}
+
+export async function withActiveSpan<T>(
+  _name: string,
+  options: SpanOptions,
+  fn: (span: SpanLike) => Promise<T>,
+): Promise<T> {
+  const attributes = new Map<string, unknown>(
+    Object.entries(options.attributes ?? {}),
+  );
+  const span: SpanLike = {
+    setAttribute(key, value) {
+      attributes.set(key, value);
+    },
+  };
+  return await fn(span);
+}

package/dist/bundling-sources/shared_libs/play-runtime/waterfall-replay.ts

@@ -0,0 +1,79 @@
+import type {
+  BatchResult,
+  PlayCheckpoint,
+  WaterfallRequest,
+} from './ctx-types';
+
+export class WaterfallReplayStore {
+  constructor(private readonly checkpoint: PlayCheckpoint) {}
+
+  checkpointKey(input: { rowId: number; rowKey?: string | null }): string {
+    return input.rowKey?.trim() || String(input.rowId);
+  }
+
+  getResolved(
+    queueKey: string,
+    input: {
+      rowId: number;
+      rowKey?: string | null;
+    },
+  ): { found: boolean; value: unknown } {
+    const resolved = this.checkpoint.resolvedWaterfalls[queueKey];
+    if (!resolved) {
+      return { found: false, value: undefined };
+    }
+    const durableKey = this.checkpointKey(input);
+    if (Object.prototype.hasOwnProperty.call(resolved, durableKey)) {
+      return { found: true, value: resolved[durableKey] };
+    }
+    return { found: false, value: undefined };
+  }
+
+  setResolved(
+    queueKey: string,
+    input: {
+      rowId: number;
+      rowKey?: string | null;
+    },
+    value: unknown,
+  ): void {
+    this.checkpoint.resolvedWaterfalls[queueKey] ??= {};
+    this.checkpoint.resolvedWaterfalls[queueKey]![this.checkpointKey(input)] =
+      value;
+  }
+
+  readProviderBatch(input: {
+    batchKey: string;
+    requests: readonly WaterfallRequest[];
+  }): Array<{ request: WaterfallRequest; result: unknown | null }> | null {
+    const cached = this.checkpoint.completedBatches[input.batchKey];
+    if (!cached) {
+      return null;
+    }
+    const recovered = cached.flatMap((entry) => {
+      const request = input.requests.find((candidate) =>
+        entry.rowKey
+          ? candidate.rowKey === entry.rowKey
+          : candidate.rowId === entry.rowId,
+      );
+      return request ? [{ request, result: entry.result }] : [];
+    });
+    return recovered.length > 0 ? recovered : null;
+  }
+
+  writeProviderBatch(
+    batchKey: string,
+    results: ReadonlyArray<{
+      request: WaterfallRequest;
+      result: unknown | null;
+    }>,
+  ): void {
+    this.checkpoint.completedBatches[batchKey] = results.map(
+      (entry): BatchResult => ({
+        rowId: entry.request.rowId,
+        rowKey: entry.request.rowKey ?? null,
+        result: entry.result,
+      }),
+    );
+  }
+}

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

@@ -0,0 +1,139 @@
+export type PlayStagedFileRef = {
+  storageKind: 'r2';
+  storageKey: string;
+  logicalPath: string;
+  fileName: string;
+  contentHash: string;
+  contentType: string;
+  bytes: number;
+};
+
+export type PlayVisualNodeProgress = {
+  completed?: number;
+  total?: number;
+  failed?: number;
+  message?: string;
+  updatedAt?: number;
+  startedAt?: number;
+  completedAt?: number;
+  artifactTableNamespace?: string | null;
+};
+
+export type PlayVisualNodeProgressMap = Record<string, PlayVisualNodeProgress>;
+
+export type ComputeBillingItem = {
+  itemId: string;
+  source: string;
+  unit: string;
+  units: number;
+  providerCostUsd: number;
+  metadata?: unknown;
+};
+
+const DAYTONA_COMPUTE_PRICING_USD = {
+  vcpuSecond: 0.000014,
+  memoryGiBSecond: 0.0000045,
+  storageGiBSecond: 0.00000003,
+  includedStorageGiB: 5,
+} as const;
+
+const TEMPORAL_COMPUTE_PRICING_USD = {
+  action: 50 / 1_000_000,
+} as const;
+
+const NEON_COMPUTE_PRICING_USD = {
+  cuHour: 0.106,
+  defaultCu: 1,
+} as const;
+
+function roundUsd(amount: number): number {
+  return Number(Math.max(0, amount).toFixed(12));
+}
+
+export function resolveDaytonaSandboxComputeItem(input: {
+  itemId: string;
+  source?: string;
+  wallTimeSeconds: number;
+  cpu: number;
+  memoryGiB: number;
+  diskGiB: number;
+  sandboxId?: string | null;
+  startedAt?: number;
+  endedAt?: number;
+}): ComputeBillingItem {
+  const billableSeconds = Math.max(1, Math.ceil(input.wallTimeSeconds));
+  const cpu = Math.max(0, input.cpu);
+  const memoryGiB = Math.max(0, input.memoryGiB);
+  const billableDiskGiB = Math.max(
+    0,
+    input.diskGiB - DAYTONA_COMPUTE_PRICING_USD.includedStorageGiB,
+  );
+  const providerCostUsd = roundUsd(
+    billableSeconds *
+      (cpu * DAYTONA_COMPUTE_PRICING_USD.vcpuSecond +
+        memoryGiB * DAYTONA_COMPUTE_PRICING_USD.memoryGiBSecond +
+        billableDiskGiB * DAYTONA_COMPUTE_PRICING_USD.storageGiBSecond),
+  );
+
+  return {
+    itemId: input.itemId,
+    source: input.source ?? 'daytona',
+    unit: 'sandbox_second',
+    units: billableSeconds,
+    providerCostUsd,
+    metadata: {
+      sandboxId: input.sandboxId ?? null,
+      cpu,
+      memoryGiB,
+      diskGiB: Math.max(0, input.diskGiB),
+      billableDiskGiB,
+      startedAt: input.startedAt,
+      endedAt: input.endedAt,
+    },
+  };
+}
+
+export function resolveTemporalComputeItem(input: {
+  itemId: string;
+  actions: number;
+  metadata?: unknown;
+}): ComputeBillingItem {
+  const actions = Math.max(0, Math.ceil(input.actions));
+  return {
+    itemId: input.itemId,
+    source: 'temporal',
+    unit: 'action',
+    units: actions,
+    providerCostUsd: roundUsd(actions * TEMPORAL_COMPUTE_PRICING_USD.action),
+    metadata: input.metadata,
+  };
+}
+
+export function resolveNeonComputeItem(input: {
+  itemId: string;
+  activeSeconds: number;
+  cu?: number;
+  metadata?: unknown;
+}): ComputeBillingItem {
+  const billableSeconds = Math.max(0, Math.ceil(input.activeSeconds));
+  const cu = Math.max(0, input.cu ?? NEON_COMPUTE_PRICING_USD.defaultCu);
+  return {
+    itemId: input.itemId,
+    source: 'neon',
+    unit: 'cu_second',
+    units: billableSeconds * cu,
+    providerCostUsd: roundUsd(
+      billableSeconds * cu * (NEON_COMPUTE_PRICING_USD.cuHour / 3600),
+    ),
+    metadata: {
+      activeSeconds: billableSeconds,
+      cu,
+      cuHourUsd: NEON_COMPUTE_PRICING_USD.cuHour,
+      ...(input.metadata && typeof input.metadata === 'object'
+        ? (input.metadata as Record<string, unknown>)
+        : input.metadata !== undefined
+          ? { inputMetadata: input.metadata }
+          : {}),
+    },
+  };
+}

package/dist/bundling-sources/shared_libs/plays/artifact-transport.ts

@@ -0,0 +1,14 @@
+import type { PlayBundleArtifact } from './artifact-types';
+
+const INLINE_SOURCE_MAP_PATTERN =
+  /\r?\n?\/\/# sourceMappingURL=data:application\/json;base64,[A-Za-z0-9+/=]+\s*$/;
+
+export function compactPlayArtifactForRuntimeTransport(
+  artifact: PlayBundleArtifact,
+): PlayBundleArtifact {
+  return {
+    ...artifact,
+    bundledCode: artifact.bundledCode.replace(INLINE_SOURCE_MAP_PATTERN, ''),
+    sourceMap: '',
+  };
+}

package/dist/bundling-sources/shared_libs/plays/artifact-types.ts

@@ -0,0 +1,49 @@
+export type PlayPackageImport = {
+  name: string;
+  version: string | null;
+};
+
+export type PlayImportPolicy = {
+  localFiles: string[];
+  nodeBuiltins: string[];
+  packages: PlayPackageImport[];
+};
+
+export type PlayRuntimeFeature =
+  | 'artifact_storage'
+  | 'checkpoint_resume'
+  | 'durable_sleep'
+  | 'packaged_files';
+
+export type PlayArtifactCompatibility = {
+  apiVersion: number;
+  artifactVersion: number;
+  minRunnerVersion: number;
+  runtimeFeatures: PlayRuntimeFeature[];
+  runtimeBackend?: string | null;
+};
+
+/**
+ * Identifies which runtime can consume this artifact:
+ *   - cjs_node20: Daytona / local-process (Node.js)
+ *   - esm_workers: Cloudflare Workers (V8 isolate)
+ */
+export type PlayArtifactKind = 'cjs_node20' | 'esm_workers';
+
+export type PlayBundleArtifact = {
+  codeFormat: 'cjs_module' | 'esm_module';
+  /** Defaults to cjs_node20 when not present (legacy artifacts). */
+  artifactKind?: PlayArtifactKind;
+  entryFile: string;
+  virtualFilename: string;
+  sourceHash: string;
+  graphHash: string;
+  artifactHash: string;
+  sourceMapHash: string;
+  bundledCode: string;
+  sourceMap: string;
+  importPolicy: PlayImportPolicy;
+  compatibility: PlayArtifactCompatibility;
+  generatedAt: number;
+  cacheHit: boolean;
+};

package/dist/bundling-sources/shared_libs/plays/compiler-manifest.ts

@@ -0,0 +1,41 @@
+import type { PlayArtifactKind } from '../play-runtime/backend';
+import type { PlayStaticPipeline } from './static-pipeline';
+
+export const PLAY_COMPILER_MANIFEST_VERSION = 1;
+
+export type PlayCompilerDependencyManifest = {
+  playName: string;
+  /** Original source path for direct imported definePlay dependencies. */
+  filePath?: string;
+  sourceHash: string;
+  graphHash: string;
+  artifactHash: string;
+  staticPipeline: PlayStaticPipeline;
+};
+
+export type PlayCompilerManifest = {
+  compilerVersion: number;
+  playName: string;
+  sourceHash: string;
+  graphHash: string;
+  artifactHash: string;
+  artifactKind?: PlayArtifactKind;
+  staticPipeline: PlayStaticPipeline;
+  importedPlayDependencies: PlayCompilerDependencyManifest[];
+};
+
+export type PlayRuntimeManifest = {
+  playName?: string;
+  graphHash: string;
+  artifactHash: string;
+  artifactStorageKey: string;
+  staticPipelineHash: string;
+  staticPipeline: PlayStaticPipeline;
+  compiledAt: number;
+  compilerVersion: string;
+  sourceCode?: string | null;
+  bundledCode?: string | null;
+  maxCreditsPerRun?: number | null;
+};
+
+export type PlayRuntimeManifestMap = Record<string, PlayRuntimeManifest>;

package/dist/bundling-sources/shared_libs/plays/dataset-summary.ts

@@ -0,0 +1,163 @@
+export type DatasetColumnExecutionBucket =
+  | 'queued'
+  | 'running'
+  | 'completed:executed'
+  | 'completed:reused'
+  | 'skipped:condition'
+  | 'skipped:missed'
+  | 'failed';
+
+export type DatasetColumnExecutionStats = Record<
+  DatasetColumnExecutionBucket,
+  string
+>;
+
+export type DatasetColumnSummary = {
+  non_empty?: string;
+  unique?: number;
+  execution?: DatasetColumnExecutionStats;
+  sample_value?: unknown;
+  sample_type?: string;
+  top_values?: Record<string, string>;
+};
+
+/**
+ * Persisted-row accounting for a dataset, sourced from the sheet summary's
+ * row-level stats (the single source of truth). `persisted` is every durable
+ * row (the count `runs export` returns); `succeeded`/`failed` partition it.
+ * `runs get --full` renders these so its row count matches what export emits.
+ */
+export type DatasetRowCounts = {
+  persisted: number;
+  succeeded: number;
+  failed: number;
+};
+
+export type DatasetSummary = {
+  total_rows: number;
+  /** Persisted/succeeded/failed breakdown when the sheet summary is available. */
+  rowCounts?: DatasetRowCounts;
+  columnStats: Record<string, DatasetColumnSummary>;
+};
+
+/**
+ * `rows: 12 persisted (9 succeeded, 3 failed)` — the canonical row-count line.
+ * Falls back to `rows: N persisted` when nothing failed/the breakdown is the
+ * full total, so the parenthetical only appears when it adds information.
+ */
+export function formatDatasetRowCountsLine(counts: DatasetRowCounts): string {
+  const { persisted, succeeded, failed } = counts;
+  if (succeeded === persisted && failed === 0) {
+    return `${persisted} persisted`;
+  }
+  return `${persisted} persisted (${succeeded} succeeded, ${failed} failed)`;
+}
+
+export type DatasetExecutionStatsInput = {
+  tableNamespace?: string;
+  columnStats: Record<
+    string,
+    {
+      queued?: number;
+      running?: number;
+      completed?: number;
+      cached?: number;
+      skipped?: number;
+      missed?: number;
+      failed?: number;
+    }
+  >;
+};
+
+export function datasetSummaryPercentText(
+  numerator: number,
+  denominator: number,
+): string {
+  return denominator > 0
+    ? `${numerator}/${denominator} (${Math.round((100 * numerator) / denominator)}%)`
+    : '0/0 (0%)';
+}
+
+function readCount(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0
+    ? Math.trunc(value)
+    : 0;
+}
+
+/**
+ * Sum of every per-cell execution bucket for a column. Each bucket is a
+ * terminal (or in-flight) state count for one cell of one row, so the sum is
+ * the number of cell attempts the column actually has — never less than any
+ * single bucket. We use this as the percentage denominator so no displayed
+ * execution stat can exceed 100%.
+ *
+ * Why not the persisted-row total: the persisted total counts distinct rows,
+ * but the column buckets can be sourced from a maintained transition-delta
+ * table that double-counts retried cells (e.g. a cell that fails then succeeds
+ * lands in both `failed` and `completed`). Dividing those numerators by the
+ * persisted-row total produced impossible figures like `executed=12/9 (133%)`.
+ * Summing the buckets is the semantically honest denominator: each percent is
+ * the share of this column's attempts that ended in that bucket.
+ */
+function executionAttemptTotal(
+  raw: DatasetExecutionStatsInput['columnStats'][string],
+): number {
+  return (
+    readCount(raw.queued) +
+    readCount(raw.running) +
+    readCount(raw.completed) +
+    readCount(raw.cached) +
+    readCount(raw.skipped) +
+    readCount(raw.missed) +
+    readCount(raw.failed)
+  );
+}
+
+export function formatDatasetExecutionStats(
+  raw: DatasetExecutionStatsInput['columnStats'][string],
+  // `persistedRowTotal` is kept for callers that pass the run's persisted row
+  // count, but it is intentionally NOT the denominator (see
+  // `executionAttemptTotal`). The denominator is the per-column attempt total,
+  // which guarantees every bucket is <=100%.
+  _persistedRowTotal: number,
+): DatasetColumnExecutionStats {
+  const denominator = executionAttemptTotal(raw);
+  const stats: DatasetColumnExecutionStats = {
+    queued: datasetSummaryPercentText(readCount(raw.queued), denominator),
+    running: datasetSummaryPercentText(readCount(raw.running), denominator),
+    'completed:executed': datasetSummaryPercentText(
+      readCount(raw.completed),
+      denominator,
+    ),
+    'completed:reused': datasetSummaryPercentText(
+      readCount(raw.cached),
+      denominator,
+    ),
+    'skipped:condition': datasetSummaryPercentText(
+      readCount(raw.skipped),
+      denominator,
+    ),
+    'skipped:missed': datasetSummaryPercentText(
+      readCount(raw.missed),
+      denominator,
+    ),
+    failed: datasetSummaryPercentText(readCount(raw.failed), denominator),
+  };
+  // Invariant guard: with an attempt-sum denominator no single bucket can
+  // exceed the denominator. If it ever does, the upstream summary is corrupt
+  // (a bucket count larger than the sum of all buckets is impossible) — flag it
+  // loudly as a data bug rather than silently capping.
+  if (
+    Object.values(stats).some((text) => {
+      const match = /\((\d+)%\)/.exec(text);
+      return match ? Number(match[1]) > 100 : false;
+    })
+  ) {
+    throw new Error(
+      `formatDatasetExecutionStats produced a >100% execution stat; column counts are corrupt: ${JSON.stringify(
+        raw,
+      )}`,
+    );
+  }
+  return stats;
+}