deepline 0.1.146 → 0.1.147

package/dist/bundling-sources/apps/play-runner-workers/src/runtime/output-datasets.ts

@@ -0,0 +1,363 @@
+import {
+  normalizePlayNameForSheet,
+  normalizeTableNamespace,
+  POSTGRES_IDENTIFIER_MAX_LENGTH,
+  sha256Hex,
+} from '../../../../shared_libs/plays/row-identity';
+import {
+  isSerializedPlayDataset,
+  type SerializedPlayDataset,
+} from '../../../../shared_libs/plays/dataset';
+
+export type OutputDatasetRow = Record<string, unknown>;
+
+export type PromotedOutputDataset = {
+  path: string;
+  tableNamespace: string;
+  rows: OutputDatasetRow[];
+  handle: unknown;
+};
+
+export type ProjectedResultDatasetHandle = {
+  path: string;
+  tableNamespace: string;
+  datasetKind: 'csv' | 'map' | null;
+  handle: unknown;
+};
+
+type ProjectTerminalResultOptions = {
+  playName?: string | null;
+  reservedTableNamespaces?: Iterable<string>;
+};
+
+type DatasetFactory = (input: {
+  path: string;
+  tableNamespace: string;
+  rows: OutputDatasetRow[];
+}) => unknown;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isDatasetLike(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  return (
+    typeof value.datasetId === 'string' &&
+    typeof value.count === 'function' &&
+    typeof value.peek === 'function' &&
+    typeof value.toJSON === 'function'
+  );
+}
+
+function datasetMetadata(value: unknown): Record<string, unknown> | null {
+  if (!isDatasetLike(value)) return null;
+  try {
+    const metadata = (value as { toJSON(): unknown }).toJSON();
+    return isRecord(metadata) ? metadata : null;
+  } catch {
+    return null;
+  }
+}
+
+function isRowArray(
+  value: unknown,
+  path: readonly string[],
+): value is OutputDatasetRow[] {
+  if (!Array.isArray(value)) return false;
+  if (value.length === 0) return isLikelyRowOutputPath(path);
+  return value.every(isRecord);
+}
+
+const NON_ROW_ARRAY_OUTPUT_KEYS = new Set([
+  'actions',
+  'columns',
+  'errors',
+  'logs',
+  'messages',
+  'next',
+  'preview',
+  'render',
+  'steps',
+  'warnings',
+]);
+
+function isLikelyRowOutputPath(path: readonly string[]): boolean {
+  if (path.length === 0) return true;
+  let leaf = '';
+  try {
+    leaf = normalizeTableNamespace(path.at(-1) ?? '');
+  } catch {
+    return false;
+  }
+  if (NON_ROW_ARRAY_OUTPUT_KEYS.has(leaf)) return false;
+  return /(^|_)(rows?|results?|records?|items?|leads?|people|contacts?|companies|accounts?)(_|$)/.test(
+    leaf,
+  );
+}
+
+function tableNamespaceForPath(path: readonly string[]): string {
+  const raw = path.length > 0 ? path.join('_') : 'rows';
+  try {
+    return normalizeTableNamespace(raw);
+  } catch {
+    const hash = sha256Hex(raw).slice(0, 10);
+    const leaf = path.at(-1) ?? 'rows';
+    let prefix = 'rows';
+    try {
+      prefix = normalizeTableNamespace(leaf).slice(0, 52) || 'rows';
+    } catch {
+      prefix = 'rows';
+    }
+    return normalizeTableNamespace(`${prefix}_${hash}`);
+  }
+}
+
+const MIN_GENERATED_RESULT_NAMESPACE_LENGTH = 9;
+
+function maxTableNamespaceLengthForPlay(playName: string | null | undefined) {
+  if (!playName) {
+    return POSTGRES_IDENTIFIER_MAX_LENGTH;
+  }
+  let playNameLength: number;
+  try {
+    playNameLength = normalizePlayNameForSheet(playName).length;
+  } catch {
+    throw new Error(
+      `Play name ${JSON.stringify(
+        playName,
+      )} cannot be used to create generated result dataset table names. ` +
+        'Shorten the play name or use only identifier-safe characters.',
+    );
+  }
+  const maxLength = POSTGRES_IDENTIFIER_MAX_LENGTH - playNameLength - 1;
+  if (maxLength < MIN_GENERATED_RESULT_NAMESPACE_LENGTH) {
+    throw new Error(
+      `Play name ${JSON.stringify(
+        playName,
+      )} leaves only ${maxLength} characters for generated result dataset table names. ` +
+        `Shorten the play name so result datasets have at least ${MIN_GENERATED_RESULT_NAMESPACE_LENGTH} characters of namespace budget.`,
+    );
+  }
+  return maxLength;
+}
+
+function boundTableNamespace(
+  value: string,
+  hashInput: string,
+  maxLength: number,
+): string {
+  const normalized = normalizeTableNamespace(value);
+  if (normalized.length <= maxLength) {
+    return normalized;
+  }
+
+  const hash = sha256Hex(hashInput).slice(0, 10);
+  if (maxLength <= 12) {
+    return normalizeTableNamespace(`r${hash}`.slice(0, maxLength));
+  }
+
+  const suffix = `_${hash}`;
+  const prefix = normalized.slice(0, maxLength - suffix.length) || 'r';
+  return normalizeTableNamespace(`${prefix}${suffix}`);
+}
+
+function resultTableNamespaceForPath(
+  path: readonly string[],
+  maxLength: number,
+): string {
+  const base = tableNamespaceForPath(path);
+  const raw = `result_${base}`;
+  const hashInput = path.join('.') || 'rows';
+  try {
+    return boundTableNamespace(raw, hashInput, maxLength);
+  } catch {
+    const hash = sha256Hex(path.join('.')).slice(0, 10);
+    return boundTableNamespace(
+      `result_${base.slice(0, 45)}_${hash}`,
+      hashInput,
+      maxLength,
+    );
+  }
+}
+
+function seedUsedNamespaces(
+  namespaces: Iterable<string> | undefined,
+): Set<string> {
+  const usedNamespaces = new Set<string>();
+  for (const namespace of namespaces ?? []) {
+    try {
+      usedNamespaces.add(normalizeTableNamespace(namespace));
+    } catch {
+      // Ignore malformed historical metadata; result datasets still get a
+      // result-prefixed namespace and local collision disambiguation.
+    }
+  }
+  return usedNamespaces;
+}
+
+function disambiguateTableNamespace(
+  tableNamespace: string,
+  path: readonly string[],
+  usedNamespaces: Set<string>,
+  maxLength: number,
+): string {
+  if (!usedNamespaces.has(tableNamespace)) {
+    usedNamespaces.add(tableNamespace);
+    return tableNamespace;
+  }
+
+  const hash = sha256Hex(path.join('.')).slice(0, 10);
+  let candidate = boundTableNamespace(
+    `${tableNamespace}_${hash}`,
+    `${path.join('.')}:collision`,
+    maxLength,
+  );
+  let suffix = 2;
+  while (usedNamespaces.has(candidate)) {
+    candidate = boundTableNamespace(
+      `${tableNamespace}_${hash}_${suffix}`,
+      `${path.join('.')}:collision:${suffix}`,
+      maxLength,
+    );
+    suffix += 1;
+  }
+  usedNamespaces.add(candidate);
+  return candidate;
+}
+
+export function projectTerminalResultDatasets(
+  value: unknown,
+  createDataset: DatasetFactory,
+  options: ProjectTerminalResultOptions = {},
+): {
+  result: unknown;
+  datasets: PromotedOutputDataset[];
+  handles: ProjectedResultDatasetHandle[];
+} {
+  const datasets: PromotedOutputDataset[] = [];
+  const handles: ProjectedResultDatasetHandle[] = [];
+  const seen = new WeakMap<object, unknown>();
+  const seenHandles = new WeakSet<object>();
+  const usedNamespaces = seedUsedNamespaces(options.reservedTableNamespaces);
+  const maxTableNamespaceLength = maxTableNamespaceLengthForPlay(
+    options.playName,
+  );
+
+  const rememberHandle = (handle: unknown, path: readonly string[]): void => {
+    if (!isRecord(handle) || seenHandles.has(handle)) return;
+    const metadata = datasetMetadata(handle);
+    const tableNamespace =
+      typeof metadata?.tableNamespace === 'string'
+        ? metadata.tableNamespace
+        : null;
+    if (!tableNamespace) return;
+    seenHandles.add(handle);
+    const datasetKind =
+      metadata?.datasetKind === 'csv' || metadata?.datasetKind === 'map'
+        ? metadata.datasetKind
+        : null;
+    handles.push({
+      path: path.length > 0 ? path.join('.') : 'rows',
+      tableNamespace,
+      datasetKind,
+      handle,
+    });
+  };
+
+  const promoteRows = (
+    rows: OutputDatasetRow[],
+    path: readonly string[],
+  ): unknown => {
+    const resolvedPath = path.length > 0 ? path.join('.') : 'rows';
+    const tableNamespace = disambiguateTableNamespace(
+      resultTableNamespaceForPath(path, maxTableNamespaceLength),
+      path,
+      usedNamespaces,
+      maxTableNamespaceLength,
+    );
+    const handle = createDataset({
+      path: resolvedPath,
+      tableNamespace,
+      rows,
+    });
+    datasets.push({
+      path: resolvedPath,
+      tableNamespace,
+      rows,
+      handle,
+    });
+    rememberHandle(handle, path);
+    return handle;
+  };
+
+  const visit = (
+    candidate: unknown,
+    path: string[],
+    depth: number,
+  ): unknown => {
+    if (depth > 20 || candidate == null) return candidate;
+    if (isDatasetLike(candidate)) {
+      rememberHandle(candidate, path);
+      return candidate;
+    }
+    if (isSerializedPlayDataset(candidate)) {
+      return candidate;
+    }
+    if (isLikelyRowOutputPath(path) && isRowArray(candidate, path)) {
+      return promoteRows(candidate, path.length > 0 ? path : ['rows']);
+    }
+    if (Array.isArray(candidate)) {
+      return candidate.map((entry, index) =>
+        visit(entry, [...path, String(index)], depth + 1),
+      );
+    }
+    if (!isRecord(candidate)) return candidate;
+    const cached = seen.get(candidate);
+    if (cached) return cached;
+    const out: Record<string, unknown> = {};
+    seen.set(candidate, out);
+    for (const [key, child] of Object.entries(candidate)) {
+      out[key] = visit(child, [...path, key], depth + 1);
+    }
+    return out;
+  };
+
+  return {
+    result: visit(value, [], 0),
+    datasets,
+    handles,
+  };
+}
+
+type SerializedDatasetHydrator = (
+  dataset: SerializedPlayDataset<Record<string, unknown>>,
+) => unknown;
+
+export function hydrateSerializedResultDatasets(
+  value: unknown,
+  hydrateDataset: SerializedDatasetHydrator,
+): unknown {
+  const seen = new WeakMap<object, unknown>();
+
+  function visit(candidate: unknown, depth: number): unknown {
+    if (depth > 20 || candidate == null) return candidate;
+    if (isSerializedPlayDataset<Record<string, unknown>>(candidate)) {
+      return hydrateDataset(candidate);
+    }
+    if (Array.isArray(candidate)) {
+      return candidate.map((entry) => visit(entry, depth + 1));
+    }
+    if (!isRecord(candidate)) return candidate;
+    const cached = seen.get(candidate);
+    if (cached) return cached;
+    const out: Record<string, unknown> = {};
+    seen.set(candidate, out);
+    for (const [key, child] of Object.entries(candidate)) {
+      out[key] = visit(child, depth + 1);
+    }
+    return out;
+  }
+
+  return visit(value, 0);
+}

package/dist/bundling-sources/apps/play-runner-workers/src/runtime/result-dataset-persistence.ts

@@ -0,0 +1,50 @@
+import { augmentSheetContractWithDatasetFields } from '../../../../shared_libs/play-data-plane/sheet-contract';
+import type { PlaySheetContract } from '../../../../shared_libs/plays/static-pipeline';
+import type { OutputDatasetRow } from './output-datasets';
+
+export type StableResultDatasetPersistenceContract = {
+  sheetContract: PlaySheetContract;
+  cachedChunks: OutputDatasetRow[][] | null;
+  rowCount: number;
+};
+
+export async function collectStableResultDatasetPersistenceContract(input: {
+  contract: PlaySheetContract;
+  chunks:
+    | AsyncIterable<readonly OutputDatasetRow[]>
+    | Iterable<readonly OutputDatasetRow[]>;
+  cacheChunks?: boolean;
+}): Promise<StableResultDatasetPersistenceContract> {
+  const fields = new Set<string>();
+  const cachedChunks: OutputDatasetRow[][] | null = input.cacheChunks
+    ? []
+    : null;
+  let rowCount = 0;
+
+  for await (const chunk of input.chunks) {
+    if (chunk.length === 0) continue;
+    rowCount += chunk.length;
+    for (const row of chunk) {
+      for (const field of Object.keys(row)) {
+        fields.add(field);
+      }
+    }
+    if (cachedChunks) {
+      cachedChunks.push(chunk.map((row) => ({ ...row })));
+    }
+  }
+
+  const unionRow =
+    fields.size === 0
+      ? []
+      : [Object.fromEntries([...fields].map((field) => [field, null]))];
+
+  return {
+    sheetContract: augmentSheetContractWithDatasetFields({
+      contract: input.contract,
+      rows: unionRow,
+    }),
+    cachedChunks,
+    rowCount,
+  };
+}

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

@@ -101,10 +101,11 @@ export const SDK_RELEASE = {
   // 0.1.108 ships explicit dataset column/tool recompute policy and removes
   // the SDK enrich generator's one-second stale policy.
   // 0.1.110 ships authored V2 prebuilts and required top-level play descriptions.
-  version: '0.1.146',
-  apiContract: '2026-06-dataset-column-cell-stale-hard-cutover',
+  // 0.1.111 ships dataset-native tool list getters and result row datasets.
+  version: '0.1.147',
+  apiContract: '2026-06-dataset-handle-results-hard-cutover',
   supportPolicy: {
-    latest: '0.1.146',
+    latest: '0.1.147',
     minimumSupported: '0.1.53',
     deprecatedBelow: '0.1.53',
     commandMinimumSupported: [
@@ -116,61 +117,93 @@ export const SDK_RELEASE = {
       },
       {
         command: 'plays',
-        minimumSupported: '0.1.110',
+        minimumSupported: '0.1.111',
         reason:
-          'Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays.',
+          'Play file commands now use dataset-native list getters and result row datasets.',
       },
       {
         command: 'plays run',
-        minimumSupported: '0.1.110',
+        minimumSupported: '0.1.111',
         reason:
-          'Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays.',
+          'Play run results now promote row-shaped outputs into dataset handles for safe export.',
       },
       {
         command: 'run',
         displayCommand: 'plays run',
-        minimumSupported: '0.1.110',
+        minimumSupported: '0.1.111',
         reason:
-          'Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays.',
+          'Play run results now promote row-shaped outputs into dataset handles for safe export.',
       },
       {
         command: 'plays check',
-        minimumSupported: '0.1.110',
+        minimumSupported: '0.1.111',
         reason:
-          'Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays.',
+          'Play file checks now validate dataset-native list getter authoring.',
       },
       {
         command: 'check',
         displayCommand: 'plays check',
-        minimumSupported: '0.1.110',
+        minimumSupported: '0.1.111',
         reason:
-          'Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays.',
+          'Play file checks now validate dataset-native list getter authoring.',
       },
       {
         command: 'plays publish',
-        minimumSupported: '0.1.110',
+        minimumSupported: '0.1.111',
         reason:
-          'Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays.',
+          'Published play artifacts now target dataset-native list getters and result row datasets.',
       },
       {
         command: 'publish',
         displayCommand: 'plays publish',
-        minimumSupported: '0.1.110',
+        minimumSupported: '0.1.111',
         reason:
-          'Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays.',
+          'Published play artifacts now target dataset-native list getters and result row datasets.',
       },
       {
         command: 'plays set-live',
-        minimumSupported: '0.1.110',
+        minimumSupported: '0.1.111',
         reason:
-          'Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays.',
+          'Published play artifacts now target dataset-native list getters and result row datasets.',
       },
       {
         command: 'set-live',
         displayCommand: 'plays set-live',
-        minimumSupported: '0.1.110',
+        minimumSupported: '0.1.111',
         reason:
-          'Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays.',
+          'Published play artifacts now target dataset-native list getters and result row datasets.',
+      },
+      {
+        command: 'runs',
+        minimumSupported: '0.1.111',
+        reason:
+          'Run result rows now render as dataset handles with explicit export commands.',
+      },
+      {
+        command: 'runs get',
+        minimumSupported: '0.1.111',
+        reason:
+          'Run result rows now render as dataset handles with explicit export commands.',
+      },
+      {
+        command: 'get',
+        displayCommand: 'runs get',
+        minimumSupported: '0.1.111',
+        reason:
+          'Run result rows now render as dataset handles with explicit export commands.',
+      },
+      {
+        command: 'runs export',
+        minimumSupported: '0.1.111',
+        reason:
+          'Run result row datasets now use the dataset-handle export contract.',
+      },
+      {
+        command: 'export',
+        displayCommand: 'runs export',
+        minimumSupported: '0.1.111',
+        reason:
+          'Run result row datasets now use the dataset-handle export contract.',
       },
     ],
     autoUpdatePatchLag: 2,

package/dist/bundling-sources/sdk/src/tool-output.ts

@@ -25,7 +25,7 @@
  */
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 
 /**
  * Result of converting a tool response to a list of records.
@@ -236,18 +236,26 @@ export function tryConvertToList(
     : [];
 
   if (listExtractorPaths.length > 0) {
+    let emptyMatch: ListConversionResult | null = null;
     for (const root of candidateRoots(payload)) {
       for (const extractorPath of listExtractorPaths) {
         const resolved = getByDottedPath(root.value, extractorPath);
         const rows = normalizeRows(resolved);
-        if (rows && rows.length > 0) {
-          const sourcePath = root.path
-            ? `${root.path}.${extractorPath}`
-            : extractorPath;
+        if (!rows) {
+          continue;
+        }
+        const sourcePath = root.path
+          ? `${root.path}.${extractorPath}`
+          : extractorPath;
+        if (rows.length > 0) {
           return { rows, strategy: 'configured_paths', sourcePath };
         }
+        emptyMatch ??= { rows, strategy: 'configured_paths', sourcePath };
       }
     }
+    if (emptyMatch) {
+      return emptyMatch;
+    }
   }
 
   for (const root of candidateRoots(payload)) {
@@ -321,9 +329,12 @@ export function writeJsonOutputFile(payload: unknown, stem: string): string {
 export function writeCsvOutputFile(
   rows: Array<Record<string, unknown>>,
   stem: string,
+  options?: { outPath?: string },
 ): { path: string; rowCount: number; columns: string[]; preview: string } {
-  const outputDir = ensureOutputDir();
-  const outputPath = join(outputDir, `${stem}_${Date.now()}.csv`);
+  const outputPath = options?.outPath
+    ? options.outPath
+    : join(ensureOutputDir(), `${stem}_${Date.now()}.csv`);
+  mkdirSync(dirname(outputPath), { recursive: true });
   const seen = new Set<string>();
   const columns: string[] = [];
   for (const row of rows) {

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

@@ -1,5 +1,6 @@
 import type { EmailStatusExtractorConfig } from './email-status';
 import type { DeeplineGetterValueMap } from './extractor-targets';
+import type { PlayDataset } from '../plays/dataset';
 
 export type ToolResultExecutionMetadata = {
   idempotent: true;
@@ -50,7 +51,7 @@ export type ToolResultListAccessor<
   TKey extends string = string,
 > = Omit<ToolResultListMetadata, 'keys'> & {
   keys: Partial<Record<TKey, string>> & Record<string, string>;
-  get(): T[];
+  get(): PlayDataset<T>;
 };
 
 export type ToolResultMetadataInput = {