deepline 0.1.33 → 0.1.36

package/dist/repo/sdk/src/client.ts

@@ -67,6 +67,8 @@ import type { PlayCompilerManifest } from '../../shared_libs/plays/compiler-mani
 
 const TERMINAL_PLAY_STATUSES = new Set(['completed', 'failed', 'cancelled']);
 const INCLUDE_TOOL_METADATA_HEADER = 'x-deepline-include-tool-metadata';
+const EXECUTE_RESPONSE_CONTRACT_HEADER = 'x-deepline-execute-response-contract';
+const V2_EXECUTE_RESPONSE_CONTRACT = 'v2-tool-response';
 const COMPILE_MANIFEST_RETRY_DELAYS_MS = [250, 1_000];
 
 function sleep(ms: number): Promise<void> {
@@ -95,10 +97,13 @@ type ExecuteToolRawOptions = {
 export type ToolExecution<TData = unknown, TMeta = Record<string, unknown>> = {
   status: string;
   job_id?: string;
-  result: {
-    data: TData;
+  meta?: Record<string, unknown>;
+  toolResponse: {
+    raw: TData;
     meta?: TMeta;
   };
+  extractedLists?: Record<string, unknown>;
+  extractedValues?: Record<string, unknown>;
   billing?: Record<string, unknown>;
   [key: string]: unknown;
 };
@@ -552,19 +557,22 @@ export class DeeplineClient {
   /**
    * Execute a tool and return the standard execution envelope.
    *
-   * The `result.data` field contains the provider payload. `result.meta`
-   * contains provider/upstream metadata such as HTTP status or paging details.
+   * The `toolResponse.raw` field contains the raw tool response.
+   * `toolResponse.meta` contains tool/provider metadata.
    * Top-level fields such as `status`, `job_id`, and `billing` describe the
-   * Deepline execution.
+   * Deepline execution envelope.
    */
   async executeTool<TData = unknown, TMeta = Record<string, unknown>>(
     toolId: string,
     input: Record<string, unknown>,
     options?: ExecuteToolRawOptions,
   ): Promise<ToolExecution<TData, TMeta>> {
-    const headers = options?.includeToolMetadata
-      ? { [INCLUDE_TOOL_METADATA_HEADER]: 'true' }
-      : undefined;
+    const headers = {
+      [EXECUTE_RESPONSE_CONTRACT_HEADER]: V2_EXECUTE_RESPONSE_CONTRACT,
+      ...(options?.includeToolMetadata
+        ? { [INCLUDE_TOOL_METADATA_HEADER]: 'true' }
+        : {}),
+    };
     return this.http.post<ToolExecution<TData, TMeta>>(
       `/api/v2/integrations/${encodeURIComponent(toolId)}/execute`,
       { payload: input },
@@ -1029,34 +1037,37 @@ export class DeeplineClient {
       bytes: number;
     }>,
   ): Promise<PlayStagedFileRef[]> {
-    const formData = new FormData();
-    formData.set(
-      'metadata',
-      JSON.stringify({
-        files: files.map((file, index) => ({
-          index,
-          logicalPath: file.logicalPath,
-          contentHash: file.contentHash,
-          contentType: file.contentType,
-          bytes: file.bytes,
-        })),
-      }),
-    );
-    for (const [index, file] of files.entries()) {
-      const bytes = decodeBase64Bytes(file.contentBase64);
-      const body = bytes.buffer.slice(
-        bytes.byteOffset,
-        bytes.byteOffset + bytes.byteLength,
-      ) as ArrayBuffer;
+    const buildFormData = () => {
+      const formData = new FormData();
       formData.set(
-        `file:${index}`,
-        new Blob([body], { type: file.contentType }),
-        file.logicalPath,
+        'metadata',
+        JSON.stringify({
+          files: files.map((file, index) => ({
+            index,
+            logicalPath: file.logicalPath,
+            contentHash: file.contentHash,
+            contentType: file.contentType,
+            bytes: file.bytes,
+          })),
+        }),
       );
-    }
+      for (const [index, file] of files.entries()) {
+        const bytes = decodeBase64Bytes(file.contentBase64);
+        const body = bytes.buffer.slice(
+          bytes.byteOffset,
+          bytes.byteOffset + bytes.byteLength,
+        ) as ArrayBuffer;
+        formData.set(
+          `file:${index}`,
+          new Blob([body], { type: file.contentType }),
+          file.logicalPath,
+        );
+      }
+      return formData;
+    };
     const response = await this.http.postFormData<{ files: PlayStagedFileRef[] }>(
       '/api/v2/plays/files/stage',
-      formData,
+      buildFormData,
     );
     return response.files;
   }

package/dist/repo/sdk/src/http.ts

@@ -31,7 +31,7 @@ import {
 interface RequestOptions {
   method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
   body?: unknown;
-  formData?: FormData;
+  formData?: FormData | (() => FormData);
   headers?: Record<string, string>;
   /** Per-request timeout override in milliseconds. */
   timeout?: number;
@@ -153,7 +153,9 @@ export class HttpClient {
             headers,
             body:
               options?.formData !== undefined
-                ? options.formData
+                ? typeof options.formData === 'function'
+                  ? options.formData()
+                  : options.formData
                 : options?.body !== undefined
                   ? JSON.stringify(options.body)
                   : undefined,
@@ -277,10 +279,13 @@ export class HttpClient {
           throw new AuthError();
         }
         if (!response.ok) {
+          const body = await response.text();
+          const parsed = parseResponseBody(body);
           throw new DeeplineError(
-            `HTTP ${response.status}`,
+            apiErrorMessage(parsed, response.status),
             response.status,
             'API_ERROR',
+            { response: parsed },
           );
         }
         if (!response.body) {
@@ -325,7 +330,7 @@ export class HttpClient {
 
   async postFormData<T = unknown>(
     path: string,
-    formData: FormData,
+    formData: FormData | (() => FormData),
     headers?: Record<string, string>,
   ): Promise<T> {
     return this.request<T>(path, {
@@ -346,6 +351,41 @@ export class HttpClient {
   }
 }
 
+function parseResponseBody(body: string): unknown {
+  try {
+    return JSON.parse(body);
+  } catch {
+    return body;
+  }
+}
+
+function apiErrorMessage(parsed: unknown, status: number): string {
+  const errorValue =
+    typeof parsed === 'object' && parsed && 'error' in parsed
+      ? (parsed as Record<string, unknown>).error
+      : undefined;
+  if (typeof errorValue === 'string') {
+    return errorValue;
+  }
+  if (
+    errorValue &&
+    typeof errorValue === 'object' &&
+    'message' in errorValue &&
+    typeof (errorValue as Record<string, unknown>).message === 'string'
+  ) {
+    return (errorValue as Record<string, string>).message;
+  }
+  if (
+    typeof parsed === 'object' &&
+    parsed &&
+    'message' in parsed &&
+    typeof (parsed as Record<string, unknown>).message === 'string'
+  ) {
+    return (parsed as Record<string, string>).message;
+  }
+  return `HTTP ${status}`;
+}
+
 /** Parse the `Retry-After` header as milliseconds. Falls back to 5000ms. */
 function parseRetryAfter(response: Response): number {
   const header = response.headers.get('retry-after');

package/dist/repo/sdk/src/index.ts

@@ -7,14 +7,14 @@
  * import { Deepline, definePlay } from 'deepline';
  *
  * // Connect (auto-resolves API key from env / CLI config)
- * const ctx = await Deepline.connect();
+ * const deepline = await Deepline.connect();
  *
  * // Execute a tool
- * const result = await ctx.tools.execute('test_company_search', { domain: 'stripe.com' });
- * const company = result.result.data;
+ * const result = await deepline.tools.execute('test_company_search', { domain: 'stripe.com' });
+ * const company = result.toolResponse.raw;
  *
  * // Run a named play
- * const job = await ctx.play('email-waterfall').run({ domain: 'stripe.com' });
+ * const job = await deepline.play('email-waterfall').run({ domain: 'stripe.com' });
  * const result = await job.get();
  * ```
  *
@@ -25,7 +25,10 @@
  *
  * export default definePlay('my-play', async (ctx, input: { domain: string }) => {
  *   ctx.log(`Looking up ${input.domain}`);
- *   const company = await ctx.tools.execute('company_search', 'test_company_search', { domain: input.domain }, {
+ *   const company = await ctx.tools.execute({
+ *     id: 'company_search',
+ *     tool: 'test_company_search',
+ *     input: { domain: input.domain },
  *     description: 'Look up company details by domain.',
  *   });
  *   return company;

package/dist/repo/sdk/src/play.ts

@@ -28,7 +28,10 @@
  *
  * export default definePlay('my-play', async (ctx, input: { domain: string }) => {
  *   ctx.log(`Looking up ${input.domain}`);
- *   const company = await ctx.tools.execute('company_search', 'test_company_search', { domain: input.domain }, {
+ *   const company = await ctx.tools.execute({
+ *     id: 'company_search',
+ *     tool: 'test_company_search',
+ *     input: { domain: input.domain },
  *     description: 'Look up company details by domain.',
  *   });
  *   return company;
@@ -42,8 +45,8 @@
  * ```typescript
  * import { Deepline } from 'deepline';
  *
- * const ctx = await Deepline.connect();
- * const job = await ctx.play('my-play').run({ domain: 'stripe.com' });
+ * const deepline = await Deepline.connect();
+ * const job = await deepline.play('my-play').run({ domain: 'stripe.com' });
  * const result = await job.get(); // Polls until complete
  * ```
  *
@@ -53,7 +56,10 @@
  * import { definePlay } from 'deepline';
  *
  * export default definePlay('daily-sync', async (ctx) => {
- *   const data = await ctx.tools.execute('crm_export', 'crm_export', {}, {
+ *   const data = await ctx.tools.execute({
+ *     id: 'crm_export',
+ *     tool: 'crm_export',
+ *     input: {},
  *     description: 'Export CRM records for the daily sync.',
  *   });
  *   return data;
@@ -66,6 +72,7 @@
  */
 import { DeeplineClient } from './client.js';
 import { DeeplineError } from './errors.js';
+import { createToolExecuteResult } from '../../shared_libs/play-runtime/tool-result.js';
 import type {
   PlayDataset,
   PlayDatasetInput,
@@ -83,6 +90,7 @@ import type {
   ToolDefinition,
   ToolMetadata,
 } from './types.js';
+import type { ToolExecution } from './client.js';
 
 /**
  * Optional trigger bindings for a play.
@@ -275,7 +283,10 @@ export type CsvOptions = {
  * ```typescript
  * definePlay('example', async (ctx, input: { domain: string }) => {
  *   // Call a tool
- *   const company = await ctx.tools.execute('company_search', 'test_company_search', { domain: input.domain }, {
+ *   const company = await ctx.tools.execute({
+ *     id: 'company_search',
+ *     tool: 'test_company_search',
+ *     input: { domain: input.domain },
  *     description: 'Look up company details by domain.',
  *   });
  *
@@ -348,24 +359,30 @@ export interface DeeplinePlayRuntimeContext {
    *
    * @example Single tool per row
    * ```typescript
-   * const results = await ctx
-   *   .map('companies', leads)
-   *   .step('company', (row, ctx) =>
-   *     ctx.tools.execute('company_search', 'test_company_search', { domain: row.domain }, {
-   *       description: 'Look up company details by domain.',
-   *     }))
+ * const results = await ctx
+ *   .map('companies', leads)
+ *   .step('company', (row, ctx) =>
+ *     ctx.tools.execute({
+ *       id: 'company_search',
+ *       tool: 'test_company_search',
+ *       input: { domain: row.domain },
+ *       description: 'Look up company details by domain.',
+ *     }))
    *   .run({ description: 'Look up companies.' });
    * // [{ domain: 'stripe.com', company: { name: 'Stripe', ... } }, ...]
    * ```
    *
    * @example Multiple columns with pre/post logic
    * ```typescript
-   * const results = await ctx
-   *   .map('leads', leads)
-   *   .step('company', (row, ctx) =>
-   *     ctx.tools.execute('company_search', 'test_company_search', { domain: row.domain }, {
-   *       description: 'Look up company details by domain.',
-   *     }))
+ * const results = await ctx
+ *   .map('leads', leads)
+ *   .step('company', (row, ctx) =>
+ *     ctx.tools.execute({
+ *       id: 'company_search',
+ *       tool: 'test_company_search',
+ *       input: { domain: row.domain },
+ *       description: 'Look up company details by domain.',
+ *     }))
    *   .step('score', (row) =>
    *     row.company?.employeeCount > 100 ? 'enterprise' : 'smb')
    *   .run({ description: 'Enrich leads.' });
@@ -379,22 +396,16 @@ export interface DeeplinePlayRuntimeContext {
   /** Tool execution namespace. */
   tools: {
     /**
-     * Execute a single tool by stable step key and tool ID.
+     * Execute a single tool with a keyword-style request object.
      *
-     * @param key - Stable step key for idempotent execution
-     * @param toolId - Tool identifier (e.g. `'test_company_search'`)
-     * @param input - Tool-specific input parameters
+     * @param request.id - Stable step key for idempotent execution
+     * @param request.tool - Tool identifier (e.g. `'test_company_search'`)
+     * @param request.input - Tool-specific input parameters
      * @returns The tool's output
      */
     execute<TOutput = LoosePlayObject>(
       request: ToolExecutionRequest,
     ): Promise<ToolExecuteResult<TOutput>>;
-    execute<TOutput = LoosePlayObject>(
-      key: string,
-      toolId: string,
-      input: Record<string, unknown>,
-      options?: { description?: string },
-    ): Promise<ToolExecuteResult<TOutput>>;
   };
   /**
    * Execute a single tool by stable step key and tool ID.
@@ -736,7 +747,10 @@ export function when<Row, Value>(
  * import { definePlay } from 'deepline';
  *
  * const myPlay = definePlay('my-play', async (ctx, input: { domain: string }) => {
- *   return await ctx.tools.execute('company_search', 'test_company_search', { domain: input.domain }, {
+ *   return await ctx.tools.execute({
+ *     id: 'company_search',
+ *     tool: 'test_company_search',
+ *     input: { domain: input.domain },
  *     description: 'Look up company details by domain.',
  *   });
  * });
@@ -886,14 +900,14 @@ function createNamedPlayHandle<
  *
  * @example
  * ```typescript
- * const ctx = await Deepline.connect();
+ * const deepline = await Deepline.connect();
  *
  * // Tools
- * const tools = await ctx.tools.list();
- * const result = await ctx.tools.execute('test_company_search', { domain: 'stripe.com' });
+ * const tools = await deepline.tools.list();
+ * const result = await deepline.tools.execute('test_company_search', { domain: 'stripe.com' });
  *
  * // Plays
- * const job = await ctx.play('email-waterfall').run({ domain: 'stripe.com' });
+ * const job = await deepline.play('email-waterfall').run({ domain: 'stripe.com' });
  * const output = await job.get();
  * ```
  */
@@ -909,10 +923,10 @@ export class DeeplineContext {
    *
    * @example
    * ```typescript
-   * const tools = await ctx.tools.list();
-   * const meta = await ctx.tools.get('apollo_people_search');
-   * const companyLookup = await ctx.tools.execute('test_company_search', { domain: 'stripe.com' });
-   * const company = companyLookup.result.data;
+   * const tools = await deepline.tools.list();
+   * const meta = await deepline.tools.get('apollo_people_search');
+   * const companyLookup = await deepline.tools.execute('test_company_search', { domain: 'stripe.com' });
+   * const company = companyLookup.toolResponse.raw;
    * ```
    */
   get tools() {
@@ -926,12 +940,14 @@ export class DeeplineContext {
       execute: async (
         toolId: string,
         input: Record<string, unknown>,
-      ): Promise<ToolExecuteResult> =>
-        this.client.executeTool(
+      ): Promise<ToolExecuteResult> => {
+        const response = await this.client.executeTool(
           toolId,
           input,
           { includeToolMetadata: true },
-        ) as unknown as Promise<ToolExecuteResult>,
+        );
+        return toolExecutionEnvelopeToResult(toolId, response);
+      },
     };
   }
 
@@ -1023,9 +1039,9 @@ export class DeeplineContext {
  * ```typescript
  * import { Deepline } from 'deepline';
  *
- * const ctx = await Deepline.connect();
- * const tools = await ctx.tools.list();
- * const result = await ctx.tools.execute('test_company_search', { domain: 'stripe.com' });
+ * const deepline = await Deepline.connect();
+ * const tools = await deepline.tools.list();
+ * const result = await deepline.tools.execute('test_company_search', { domain: 'stripe.com' });
  * ```
  */
 export class Deepline {
@@ -1058,6 +1074,62 @@ export class Deepline {
   }
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function stringArrayRecord(value: unknown): Record<string, string[]> {
+  if (!isRecord(value)) return {};
+  return Object.fromEntries(
+    Object.entries(value).map(([key, paths]) => [
+      key,
+      Array.isArray(paths) ? paths.map(String) : [],
+    ]),
+  );
+}
+
+function stringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.map(String) : [];
+}
+
+function toolExecutionEnvelopeToResult(
+  fallbackToolId: string,
+  response: ToolExecution,
+): ToolExecuteResult {
+  const raw = response.toolResponse?.raw ?? null;
+  const meta = response.toolResponse?.meta;
+  const metadata = isRecord(response._metadata)
+    ? response._metadata.tool
+    : null;
+  const toolMetadata = isRecord(metadata) ? metadata : {};
+
+  return createToolExecuteResult({
+    status: typeof response.status === 'string' ? response.status : 'completed',
+    jobId: typeof response.job_id === 'string' ? response.job_id : undefined,
+    result: {
+      data: raw,
+      ...(isRecord(meta) ? { meta } : {}),
+    },
+    metadata: {
+      toolId:
+        typeof toolMetadata.toolId === 'string'
+          ? toolMetadata.toolId
+          : fallbackToolId,
+      resultIdentityGetters: stringArrayRecord(
+        toolMetadata.resultIdentityGetters,
+      ),
+      listExtractorPaths: stringArray(toolMetadata.listExtractorPaths),
+      listIdentityGetters: stringArrayRecord(toolMetadata.listIdentityGetters),
+    },
+    execution: {
+      idempotent: true,
+      cached: false,
+      source: 'live',
+    },
+    meta: isRecord(response.meta) ? response.meta : undefined,
+  });
+}
+
 export function defineInput<TInput>(
   schema: Record<string, unknown>,
 ): PlayInputContract<TInput> {
@@ -1092,7 +1164,10 @@ export function defineInput<TInput>(
  *
  * export default definePlay('company-lookup', async (ctx, input: { domain: string }) => {
  *   ctx.log(`Searching for ${input.domain}`);
- *   const company = await ctx.tools.execute('company_search', 'test_company_search', { domain: input.domain }, {
+ *   const company = await ctx.tools.execute({
+ *     id: 'company_search',
+ *     tool: 'test_company_search',
+ *     input: { domain: input.domain },
  *     description: 'Look up company details by domain.',
  *   });
  *   return company;
@@ -1107,7 +1182,10 @@ export function defineInput<TInput>(
  *   const results = await ctx
  *     .map('companies', leads)
  *     .step('company', (row, ctx) =>
- *       ctx.tools.execute('company_search', 'test_company_search', { domain: row.domain }, {
+ *       ctx.tools.execute({
+ *         id: 'company_search',
+ *         tool: 'test_company_search',
+ *         input: { domain: row.domain },
  *         description: 'Look up company details by domain.',
  *       }))
  *     .run({ description: 'Enrich lead companies.' });
@@ -1118,7 +1196,10 @@ export function defineInput<TInput>(
  * @example With cron binding
  * ```typescript
  * export default definePlay('daily-report', async (ctx) => {
- *   const data = await ctx.tools.execute('crm_export', 'crm_export', { since: 'yesterday' }, {
+ *   const data = await ctx.tools.execute({
+ *     id: 'crm_export',
+ *     tool: 'crm_export',
+ *     input: { since: 'yesterday' },
  *     description: 'Export yesterday CRM records.',
  *   });
  *   return data;

package/dist/repo/sdk/src/plays/harness-stub.ts

@@ -155,6 +155,7 @@ export async function harnessPrewarmPostgresSessions(input: {
 export async function harnessStartSheetDataset(input: {
   baseUrl: string;
   executorToken: string;
+  preloadedDbSessions?: PreloadedRuntimeDbSessionInput[] | null;
   playName: string;
   tableNamespace: string;
   sheetContract: unknown;
@@ -162,7 +163,6 @@ export async function harnessStartSheetDataset(input: {
   runId: string;
   inputOffset?: number;
   userEmail?: string | null;
-  preloadedDbSessions?: PreloadedRuntimeDbSessionInput[] | null;
 }): Promise<{
   inserted: number;
   skipped: number;
@@ -181,6 +181,7 @@ export async function harnessStartSheetDataset(input: {
 export async function harnessPersistCompletedSheetRows(input: {
   baseUrl: string;
   executorToken: string;
+  preloadedDbSessions?: PreloadedRuntimeDbSessionInput[] | null;
   playName: string;
   tableNamespace: string;
   sheetContract: unknown;
@@ -188,7 +189,6 @@ export async function harnessPersistCompletedSheetRows(input: {
   outputFields: string[];
   runId: string;
   userEmail?: string | null;
-  preloadedDbSessions?: PreloadedRuntimeDbSessionInput[] | null;
 }): Promise<{ ok: true; rowsWritten: number; tableNamespace: string }> {
   return requireBinding().persistCompletedMapRows(input);
 }

package/dist/repo/sdk/src/tool-output.ts

@@ -2,7 +2,7 @@
  * Tool output processing utilities.
  *
  * Tools return data in varied shapes — some return flat objects, others
- * wrap results in `{ result: { data: [...] } }` envelopes, and list
+ * wrap results in `{ output: { body: [...] } }` envelopes, and list
  * responses can be nested at different depths. This module provides
  * utilities to normalize, extract, and persist tool outputs.
  *
@@ -33,7 +33,7 @@ import { join } from 'node:path';
  * @example
  * ```typescript
  * const conversion = tryConvertToList(toolResponse, {
- *   listExtractorPaths: ['people', 'result.data'],
+ *   listExtractorPaths: ['people', 'output.body'],
  * });
  * if (conversion) {
  *   console.log(`Found ${conversion.rows.length} rows via ${conversion.strategy}`);
@@ -50,7 +50,7 @@ export type ListConversionResult = {
    * - `'auto_detected'` — found via recursive DFS (longest array wins)
    */
   strategy: 'configured_paths' | 'auto_detected';
-  /** Dotted path to where the list was found (e.g. `"result.data"`, `"people"`). */
+  /** Dotted path to where the list was found (e.g. `"output.body"`, `"people"`). */
   sourcePath: string | null;
 };
 
@@ -75,7 +75,7 @@ function normalizeScalarString(value: unknown): string | null {
  * Traverse a nested object by a dotted path string.
  *
  * @param root - Object to traverse
- * @param dottedPath - Path like `"result.data.items"`
+ * @param dottedPath - Path like `"output.body.items"`
  * @returns Value at the path, or `null` if not found
  *
  * @example
@@ -109,10 +109,25 @@ function normalizeRows(value: unknown): Array<Record<string, unknown>> | null {
 
 /**
  * Generate candidate root objects to search for lists.
- * Tries: raw payload → payload.result → payload.result.data.
+ * Tries: raw payload → V2 toolResponse.raw → legacy payload.output.body → legacy payload.result → legacy payload.result.data.
  */
 function candidateRoots(payload: unknown): Array<{ path: string | null; value: unknown }> {
   const roots: Array<{ path: string | null; value: unknown }> = [{ path: null, value: payload }];
+  if (isPlainObject(payload) && isPlainObject(payload.toolResponse)) {
+    roots.push({ path: 'toolResponse', value: payload.toolResponse });
+    if (Object.prototype.hasOwnProperty.call(payload.toolResponse, 'raw')) {
+      roots.push({
+        path: 'toolResponse.raw',
+        value: payload.toolResponse.raw,
+      });
+    }
+  }
+  if (isPlainObject(payload) && isPlainObject(payload.output)) {
+    roots.push({ path: 'output', value: payload.output });
+    if (Object.prototype.hasOwnProperty.call(payload.output, 'body')) {
+      roots.push({ path: 'output.body', value: payload.output.body });
+    }
+  }
   if (isPlainObject(payload) && isPlainObject(payload.result)) {
     roots.push({ path: 'result', value: payload.result });
     if (isPlainObject(payload.result.data)) {
@@ -167,7 +182,7 @@ function findBestArrayCandidate(
  * ## Extraction strategy
  *
  * 1. **Configured paths** — If `listExtractorPaths` is provided, each path is
- *    tried against multiple candidate roots (raw payload, `.result`, `.result.data`).
+ *    tried against multiple candidate roots (raw payload, `.output.body`, legacy `.result`, legacy `.result.data`).
  *    First match wins.
  *
  * 2. **Auto-detection** — If no configured path matches, recursively searches
@@ -344,7 +359,7 @@ export function writeCsvOutputFile(
 /**
  * Extract scalar (non-nested) fields from a tool response for summary display.
  *
- * Searches through candidate roots (raw → `.result` → `.result.data`) and
+ * Searches through candidate roots (raw → `.output.body` → legacy `.result` → legacy `.result.data`) and
  * returns the first set of scalar fields found. Useful for displaying a
  * quick summary of single-record responses.
  *