deepline 0.1.180 → 0.1.182

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

@@ -52,7 +52,12 @@ type PathSegment = string | number | '*';
 
 const SERIALIZED_TOOL_EXECUTE_RESULT_KIND = 'deepline.tool_execute_result.v1';
 const SERIALIZED_TOOL_RESULT_LIST_PREVIEW_LIMIT = 5;
+const LIVE_TOOL_RESULT_LIST_DATASET_REGISTRY_LIMIT = 256;
 const SERIALIZED_TOOL_LIST_ROWS = Symbol('deepline.serialized_tool_list_rows');
+const liveToolResultListDatasets = new Map<
+  string,
+  PlayDataset<Record<string, unknown>>
+>();
 
 const TARGET_FALLBACK_KEYS: Record<string, readonly RegExp[]> = {
   email: [/^email$/i, /^address$/i, /email/i],
@@ -1169,6 +1174,9 @@ export function readList(
   if (selector) {
     const paths = Array.isArray(selector) ? selector : [selector];
     const declaredList = findDeclaredListAccessor(result, paths);
+    if (declaredList && preservedSerializedListRows(result)) {
+      return declaredList.get();
+    }
     const found = findFirstTargetByPath(resultRootOf(result), paths)?.value;
     const rows = normalizeRows(found);
     if (rows) {
@@ -1186,6 +1194,55 @@ export function readList(
   return Object.values(result.extractedLists)[0]?.get() ?? [];
 }
 
+export function attachToolResultListDataset<T extends Record<string, unknown>>(
+  result: ToolExecuteResult,
+  input: {
+    name: string;
+    path: string;
+    dataset: PlayDataset<T>;
+    count: number;
+    keys?: Record<string, string>;
+  },
+): ToolExecuteResult {
+  const existing = result._metadata.lists[input.name];
+  result._metadata.lists[input.name] = {
+    path: input.path,
+    count: input.count,
+    keys: input.keys ?? existing?.keys ?? {},
+  };
+  const accessor = {
+    path: input.path,
+    count: input.count,
+    keys: result._metadata.lists[input.name].keys,
+  } as ToolResultListAccessor<T>;
+  Object.defineProperty(accessor, 'get', {
+    value() {
+      return input.dataset;
+    },
+    enumerable: false,
+  });
+  result.extractedLists[input.name] = accessor;
+  const serialized = input.dataset.toJSON();
+  let root: unknown = { toolResponse: { raw: result.toolResponse.raw } };
+  const candidates = [...candidateResultPaths(input.path)].filter(
+    (candidate, index, all) => all.indexOf(candidate) === index,
+  );
+  for (const candidate of candidates) {
+    if (!Array.isArray(getAtPath(root, candidate))) continue;
+    root = replaceAtPath(root, candidate, serialized.preview);
+    break;
+  }
+  if (
+    isRecord(root) &&
+    isRecord(root.toolResponse) &&
+    Object.prototype.hasOwnProperty.call(root.toolResponse, 'raw')
+  ) {
+    result.toolResponse.raw = root.toolResponse.raw;
+    result.toolOutput.raw = root.toolResponse.raw;
+  }
+  return result;
+}
+
 function normalizeListPathForMatch(path: string): string {
   return path.replace(/\[(?:\*|\d+)\]$/g, '');
 }
@@ -1237,10 +1294,12 @@ function serializedListDatasetsFromResult(
 ): Record<string, SerializedPlayDataset<Record<string, unknown>>> | undefined {
   const entries = Object.entries(value.extractedLists).flatMap(
     ([name, accessor]) => {
-      const serialized = accessor.get().toJSON();
+      const dataset = accessor.get();
+      const serialized = dataset.toJSON();
       if (!isSerializedPlayDataset<Record<string, unknown>>(serialized)) {
         return [];
       }
+      rememberLiveToolResultListDataset(serialized.datasetId, dataset);
       return [
         [
           name,
@@ -1255,6 +1314,32 @@ function serializedListDatasetsFromResult(
   return entries.length > 0 ? Object.fromEntries(entries) : undefined;
 }
 
+function rememberLiveToolResultListDataset(
+  datasetId: string,
+  dataset: PlayDataset<Record<string, unknown>>,
+): void {
+  if (!datasetId) return;
+  liveToolResultListDatasets.delete(datasetId);
+  liveToolResultListDatasets.set(datasetId, dataset);
+  while (
+    liveToolResultListDatasets.size > LIVE_TOOL_RESULT_LIST_DATASET_REGISTRY_LIMIT
+  ) {
+    const oldest = liveToolResultListDatasets.keys().next().value;
+    if (typeof oldest !== 'string') break;
+    liveToolResultListDatasets.delete(oldest);
+  }
+}
+
+function readLiveToolResultListDataset(
+  serialized: SerializedPlayDataset<Record<string, unknown>>,
+): PlayDataset<Record<string, unknown>> | null {
+  const dataset = liveToolResultListDatasets.get(serialized.datasetId);
+  if (!dataset) return null;
+  const current = dataset.toJSON();
+  if (current.count !== serialized.count) return null;
+  return dataset;
+}
+
 function serializedListRowsFromRaw(input: {
   raw: unknown;
   metadata: ToolResultMetadataInput;
@@ -1273,11 +1358,13 @@ function serializedListRowsFromRaw(input: {
 function preservedSerializedListRows(
   value: ToolExecuteResult,
 ): Record<string, Array<Record<string, unknown>>> | undefined {
-  const rows = (value as ToolExecuteResult & {
-    [SERIALIZED_TOOL_LIST_ROWS]?:
-      | Record<string, Array<Record<string, unknown>>>
-      | undefined;
-  })[SERIALIZED_TOOL_LIST_ROWS];
+  const rows = (
+    value as ToolExecuteResult & {
+      [SERIALIZED_TOOL_LIST_ROWS]?:
+        | Record<string, Array<Record<string, unknown>>>
+        | undefined;
+    }
+  )[SERIALIZED_TOOL_LIST_ROWS];
   return rows && Object.keys(rows).length > 0 ? rows : undefined;
 }
 
@@ -1301,10 +1388,7 @@ function serializedListRowsFromResult(input: {
   const entries = [...names].flatMap((name) => {
     const dataset = input.listDatasets?.[name];
     const preservedRows = preserved?.[name];
-    if (
-      preservedRows &&
-      (!dataset || preservedRows.length >= dataset.count)
-    ) {
+    if (preservedRows && (!dataset || preservedRows.length >= dataset.count)) {
       return [[name, preservedRows]] as const;
     }
     const rows = rawRows?.[name];
@@ -1352,6 +1436,41 @@ function serializedRawWithListPreviews(input: {
     : input.raw;
 }
 
+function rawWithSerializedListRows(input: {
+  raw: unknown;
+  lists: Record<string, ToolResultListMetadata>;
+  listDatasets:
+    | Record<string, SerializedPlayDataset<Record<string, unknown>>>
+    | undefined;
+  listRows: Record<string, Array<Record<string, unknown>>> | undefined;
+}): unknown {
+  if (!input.listRows || Object.keys(input.listRows).length === 0) {
+    return input.raw;
+  }
+
+  let root: unknown = { toolResponse: { raw: input.raw } };
+  for (const [name, rows] of Object.entries(input.listRows)) {
+    const sourcePath =
+      input.listDatasets?.[name]?.sourceLabel ??
+      input.lists[name]?.path ??
+      name;
+    const candidates = [...candidateResultPaths(sourcePath)].filter(
+      (candidate, index, all) => all.indexOf(candidate) === index,
+    );
+    for (const candidate of candidates) {
+      if (!Array.isArray(getAtPath(root, candidate))) continue;
+      root = replaceAtPath(root, candidate, rows);
+      break;
+    }
+  }
+
+  return isRecord(root) &&
+    isRecord(root.toolResponse) &&
+    Object.prototype.hasOwnProperty.call(root.toolResponse, 'raw')
+    ? root.toolResponse.raw
+    : input.raw;
+}
+
 function createDatasetFromSerializedToolList(
   serialized: SerializedPlayDataset<Record<string, unknown>>,
   rows?: Array<Record<string, unknown>>,
@@ -1411,6 +1530,12 @@ function applySerializedListDatasets(
 ): ToolExecuteResult {
   if (!listDatasets) return result;
   if (listRows && Object.keys(listRows).length > 0) {
+    result.toolResponse.raw = rawWithSerializedListRows({
+      raw: result.toolResponse.raw,
+      lists: result._metadata.lists,
+      listDatasets,
+      listRows,
+    });
     Object.defineProperty(result, SERIALIZED_TOOL_LIST_ROWS, {
       value: listRows,
       enumerable: false,
@@ -1422,10 +1547,9 @@ function applySerializedListDatasets(
     if (!isSerializedPlayDataset<Record<string, unknown>>(serialized)) {
       continue;
     }
-    const dataset = createDatasetFromSerializedToolList(
-      serialized,
-      listRows?.[name],
-    );
+    const dataset =
+      readLiveToolResultListDataset(serialized) ??
+      createDatasetFromSerializedToolList(serialized, listRows?.[name]);
     const existingMetadata = result._metadata.lists[name];
     result._metadata.lists[name] = {
       path: serialized.sourceLabel ?? existingMetadata?.path ?? name,
@@ -1528,9 +1652,7 @@ export function deserializeToolExecuteResult(
         jobId: value.job_id,
         result: {
           data: value.toolResponse.raw,
-          ...(value.toolResponse.meta
-            ? { meta: value.toolResponse.meta }
-            : {}),
+          ...(value.toolResponse.meta ? { meta: value.toolResponse.meta } : {}),
         },
         metadata: value.metadata,
         execution: value.execution,

package/dist/cli/index.js

@@ -623,10 +623,10 @@ var SDK_RELEASE = {
   // 0.1.154 removes the short-lived generated enrich StepOptions recompute
   // fields shipped in 0.1.153.
   // 0.1.175 ships loud `deepline enrich` empty-waterfall reporting.
-  version: "0.1.180",
+  version: "0.1.182",
   apiContract: "2026-06-dataset-handle-results-hard-cutover",
   supportPolicy: {
-    latest: "0.1.180",
+    latest: "0.1.182",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53",
     commandMinimumSupported: [
@@ -2742,11 +2742,14 @@ var DeeplineClient = class {
     const headers = {
       [EXECUTE_RESPONSE_CONTRACT_HEADER]: V2_EXECUTE_RESPONSE_CONTRACT,
       ...options?.includeToolMetadata ? { [INCLUDE_TOOL_METADATA_HEADER]: "true" } : {},
-      ...options?.responseIntent ? { [EXECUTE_RESPONSE_INTENT_HEADER]: options.responseIntent } : {}
+      [EXECUTE_RESPONSE_INTENT_HEADER]: options?.responseIntent ?? "raw"
     };
     return this.http.post(
       `/api/v2/integrations/${encodeURIComponent(toolId)}/execute`,
-      { payload: input2 },
+      {
+        payload: input2,
+        ...options?.metadata ? { metadata: options.metadata } : {}
+      },
       headers,
       {
         forbiddenAsApiError: true,
@@ -7331,7 +7334,7 @@ async function fetchCsvRenderHealth(url) {
   }
 }
 async function waitForRenderHealth(url, state) {
-  const deadline = Date.now() + 5e3;
+  const deadline = Date.now() + 15e3;
   while (Date.now() < deadline) {
     if (isOwnedCsvRenderHealth(await fetchCsvRenderHealth(url), state)) {
       return true;
@@ -9745,7 +9748,7 @@ async function traceCliSpan(phase, fields, run) {
 }
 
 // src/cli/play-check-hints.ts
-var EXTRACTED_GETTER_ERROR_HINT = "Deepline hint: extractedValues/extractedLists .get() only works for declared Deepline getters listed by `deepline tools describe <tool> --json`. Use `toolExecutionResult.toolResponse.raw` for provider/tool-specific fields.";
+var EXTRACTED_GETTER_ERROR_HINT = "Deepline hint: extractedValues/extractedLists .get() only works for declared Deepline getters listed by `deepline tools describe <tool> --json`. Use `toolExecutionResult.toolResponse.raw` for provider/tool-specific scalar fields, and `toolExecutionResult.extractedLists.<name>.get()` for declared row/list outputs.";
 var DATASET_API_HINT = "Deepline hint: PlayDataset is lazy and durable. Use `.peek(n)` for a small preview or `.materialize()` when you intentionally need rows in memory; do not use `.rows`, `.toArray()`, or array methods directly on the dataset handle.";
 var ROW_PROPERTY_HINT = "Deepline hint: this row type only contains fields produced by the CSV/schema and previous map steps. Check source column casing and the exact output field names from earlier steps before scaling.";
 var TOOLS_EXECUTE_SIGNATURE_HINT = "Deepline hint: ctx.tools.execute requires a request object: `ctx.tools.execute({ id, tool, input, description })`. The stable `id` is required for logs, metadata, and receipt attachment; provider-call reuse is based on play, tool, semantic input, auth scope, provider action version, and cache policy.";
@@ -24026,7 +24029,7 @@ function toolMetadataJsonForDescribe(tool, requestedToolId) {
     runtimeOutputHelp: {
       contract: "tools describe shows declared schema and Deepline getters; it is not an observed provider response.",
       getterScope: "extractedValues/extractedLists .get() only works for declared Deepline getters listed in usageGuidance.toolExecutionResult.",
-      rawToolResponse: "Use toolExecutionResult.toolResponse.raw for provider/tool-specific fields, fields in outputSchema that are not declared getters, and debugging.",
+      rawToolResponse: "Use toolExecutionResult.toolResponse.raw for provider/tool-specific scalar fields, fields in outputSchema that are not declared getters, and debugging. For declared row/list outputs, use extractedLists.<name>.get(); raw row arrays may be inline previews.",
       invalidGetterHint: "If TypeScript says an extractedValues/extractedLists property does not exist, that field is not a declared Deepline getter.",
       observeActualShape: observedOutputCommand,
       observedOutput: observedOutputCommand,
@@ -24052,9 +24055,9 @@ function usageGuidanceWithAccessDefaults(usageGuidance) {
       },
       rawToolResponse: {
         expression: "toolExecutionResult.toolResponse.raw",
-        meaning: "Raw tool response for provider/tool-specific fields and debugging."
+        meaning: "Raw tool response for provider/tool-specific scalar fields and bounded debugging. Declared row/list outputs should use extractedLists.<name>.get(); raw row arrays may be inline previews."
       },
-      invalidGetterHint: "If TypeScript says an extractedValues/extractedLists property does not exist, that field is not a declared Deepline getter; use toolResponse.raw for provider/tool-specific fields.",
+      invalidGetterHint: "If TypeScript says an extractedValues/extractedLists property does not exist, that field is not a declared Deepline getter; use toolResponse.raw for provider/tool-specific scalar fields, and extractedLists.<name>.get() for declared row/list outputs.",
       ...existingAccess
     }
   };

package/dist/cli/index.mjs

@@ -608,10 +608,10 @@ var SDK_RELEASE = {
   // 0.1.154 removes the short-lived generated enrich StepOptions recompute
   // fields shipped in 0.1.153.
   // 0.1.175 ships loud `deepline enrich` empty-waterfall reporting.
-  version: "0.1.180",
+  version: "0.1.182",
   apiContract: "2026-06-dataset-handle-results-hard-cutover",
   supportPolicy: {
-    latest: "0.1.180",
+    latest: "0.1.182",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53",
     commandMinimumSupported: [
@@ -2727,11 +2727,14 @@ var DeeplineClient = class {
     const headers = {
       [EXECUTE_RESPONSE_CONTRACT_HEADER]: V2_EXECUTE_RESPONSE_CONTRACT,
       ...options?.includeToolMetadata ? { [INCLUDE_TOOL_METADATA_HEADER]: "true" } : {},
-      ...options?.responseIntent ? { [EXECUTE_RESPONSE_INTENT_HEADER]: options.responseIntent } : {}
+      [EXECUTE_RESPONSE_INTENT_HEADER]: options?.responseIntent ?? "raw"
     };
     return this.http.post(
       `/api/v2/integrations/${encodeURIComponent(toolId)}/execute`,
-      { payload: input2 },
+      {
+        payload: input2,
+        ...options?.metadata ? { metadata: options.metadata } : {}
+      },
       headers,
       {
         forbiddenAsApiError: true,
@@ -7334,7 +7337,7 @@ async function fetchCsvRenderHealth(url) {
   }
 }
 async function waitForRenderHealth(url, state) {
-  const deadline = Date.now() + 5e3;
+  const deadline = Date.now() + 15e3;
   while (Date.now() < deadline) {
     if (isOwnedCsvRenderHealth(await fetchCsvRenderHealth(url), state)) {
       return true;
@@ -9772,7 +9775,7 @@ async function traceCliSpan(phase, fields, run) {
 }
 
 // src/cli/play-check-hints.ts
-var EXTRACTED_GETTER_ERROR_HINT = "Deepline hint: extractedValues/extractedLists .get() only works for declared Deepline getters listed by `deepline tools describe <tool> --json`. Use `toolExecutionResult.toolResponse.raw` for provider/tool-specific fields.";
+var EXTRACTED_GETTER_ERROR_HINT = "Deepline hint: extractedValues/extractedLists .get() only works for declared Deepline getters listed by `deepline tools describe <tool> --json`. Use `toolExecutionResult.toolResponse.raw` for provider/tool-specific scalar fields, and `toolExecutionResult.extractedLists.<name>.get()` for declared row/list outputs.";
 var DATASET_API_HINT = "Deepline hint: PlayDataset is lazy and durable. Use `.peek(n)` for a small preview or `.materialize()` when you intentionally need rows in memory; do not use `.rows`, `.toArray()`, or array methods directly on the dataset handle.";
 var ROW_PROPERTY_HINT = "Deepline hint: this row type only contains fields produced by the CSV/schema and previous map steps. Check source column casing and the exact output field names from earlier steps before scaling.";
 var TOOLS_EXECUTE_SIGNATURE_HINT = "Deepline hint: ctx.tools.execute requires a request object: `ctx.tools.execute({ id, tool, input, description })`. The stable `id` is required for logs, metadata, and receipt attachment; provider-call reuse is based on play, tool, semantic input, auth scope, provider action version, and cache policy.";
@@ -24072,7 +24075,7 @@ function toolMetadataJsonForDescribe(tool, requestedToolId) {
     runtimeOutputHelp: {
       contract: "tools describe shows declared schema and Deepline getters; it is not an observed provider response.",
       getterScope: "extractedValues/extractedLists .get() only works for declared Deepline getters listed in usageGuidance.toolExecutionResult.",
-      rawToolResponse: "Use toolExecutionResult.toolResponse.raw for provider/tool-specific fields, fields in outputSchema that are not declared getters, and debugging.",
+      rawToolResponse: "Use toolExecutionResult.toolResponse.raw for provider/tool-specific scalar fields, fields in outputSchema that are not declared getters, and debugging. For declared row/list outputs, use extractedLists.<name>.get(); raw row arrays may be inline previews.",
       invalidGetterHint: "If TypeScript says an extractedValues/extractedLists property does not exist, that field is not a declared Deepline getter.",
       observeActualShape: observedOutputCommand,
       observedOutput: observedOutputCommand,
@@ -24098,9 +24101,9 @@ function usageGuidanceWithAccessDefaults(usageGuidance) {
       },
       rawToolResponse: {
         expression: "toolExecutionResult.toolResponse.raw",
-        meaning: "Raw tool response for provider/tool-specific fields and debugging."
+        meaning: "Raw tool response for provider/tool-specific scalar fields and bounded debugging. Declared row/list outputs should use extractedLists.<name>.get(); raw row arrays may be inline previews."
       },
-      invalidGetterHint: "If TypeScript says an extractedValues/extractedLists property does not exist, that field is not a declared Deepline getter; use toolResponse.raw for provider/tool-specific fields.",
+      invalidGetterHint: "If TypeScript says an extractedValues/extractedLists property does not exist, that field is not a declared Deepline getter; use toolResponse.raw for provider/tool-specific scalar fields, and extractedLists.<name>.get() for declared row/list outputs.",
       ...existingAccess
     }
   };

package/dist/index.d.mts

@@ -1088,7 +1088,8 @@ type EnrichCompiledConfig = {
 
 type ExecuteToolRawOptions = {
     includeToolMetadata?: boolean;
-    responseIntent?: 'raw' | 'row_artifact';
+    responseIntent?: 'dataset' | 'raw' | 'row_artifact';
+    metadata?: Record<string, unknown>;
     timeout?: number;
     maxRetries?: number;
 };

package/dist/index.d.ts

@@ -1088,7 +1088,8 @@ type EnrichCompiledConfig = {
 
 type ExecuteToolRawOptions = {
     includeToolMetadata?: boolean;
-    responseIntent?: 'raw' | 'row_artifact';
+    responseIntent?: 'dataset' | 'raw' | 'row_artifact';
+    metadata?: Record<string, unknown>;
     timeout?: number;
     maxRetries?: number;
 };