deepline 0.1.33 → 0.1.36

package/dist/index.d.mts

@@ -255,17 +255,51 @@ interface ToolDefinition {
     inputSchema?: Record<string, unknown>;
     /** JSON Schema describing the tool's output shape. */
     outputSchema?: Record<string, unknown>;
-    /**
-     * Dotted paths for extracting list data from the tool's response.
-     *
-     * Used by {@link tryConvertToList} to automatically find the array of results
-     * in a nested response. Example: `["people", "result.data"]`.
-     */
-    listExtractorPaths?: string[];
-    /** Field mappings for extracting identity fields (email, phone, etc.) from results. */
-    resultIdentityGetters?: Record<string, string[]>;
-    /** Whether the output is a direct object or wrapped in a `result` envelope. */
-    rowContextShape?: 'direct' | 'result_envelope';
+    /** Copyable play-runtime guidance for V2 tool execution results. */
+    usageGuidance?: {
+        execute?: string;
+        toolExecutionResult?: {
+            type?: 'ToolExecutionResult';
+            toolResponse?: {
+                raw?: string;
+                meta?: string;
+            };
+            meta?: string;
+            extractedLists?: Array<{
+                name: string;
+                expression: string;
+                details?: {
+                    strategy?: string;
+                    rawToolOutputPaths?: string[];
+                    candidatePaths?: string[];
+                };
+            }> | Record<string, {
+                expression: string;
+                details?: {
+                    strategy?: string;
+                    rawToolOutputPaths?: string[];
+                    candidatePaths?: string[];
+                };
+            }>;
+            extractedValues?: Array<{
+                name: string;
+                expression: string;
+                details?: {
+                    strategy?: string;
+                    rawToolOutputPaths?: string[];
+                    candidatePaths?: string[];
+                };
+            }> | Record<string, {
+                expression: string;
+                details?: {
+                    strategy?: string;
+                    rawToolOutputPaths?: string[];
+                    candidatePaths?: string[];
+                };
+            }>;
+            [key: string]: unknown;
+        };
+    };
     /** Search relevance score returned by ranked tool search. */
     search_score?: number;
     /** Search match snippets returned by ranked tool search. */
@@ -822,10 +856,13 @@ type ExecuteToolRawOptions = {
 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;
 };
@@ -967,10 +1004,10 @@ declare 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.
      */
     executeTool<TData = unknown, TMeta = Record<string, unknown>>(toolId: string, input: Record<string, unknown>, options?: ExecuteToolRawOptions): Promise<ToolExecution<TData, TMeta>>;
     executeToolRaw<TData = unknown, TMeta = Record<string, unknown>>(toolId: string, input: Record<string, unknown>, options?: ExecuteToolRawOptions): Promise<ToolExecution<TData, TMeta>>;
@@ -1440,8 +1477,8 @@ declare class DeeplineClient {
     }>;
 }
 
-declare const SDK_VERSION = "0.1.33";
-declare const SDK_API_CONTRACT = "2026-05-host-env-generic-play-input-flags";
+declare const SDK_VERSION = "0.1.36";
+declare const SDK_API_CONTRACT = "2026-05-v2-tool-response";
 
 /**
  * Base error class for all Deepline SDK errors.
@@ -1653,13 +1690,20 @@ type ToolResultTargetAccessor<T = unknown> = ToolResultTargetMetadata & {
 type ToolResultListAccessor<T = Record<string, unknown>> = ToolResultListMetadata & {
     get(): T[];
 };
-type ToolResultEnvelope<TData = unknown, TMeta = Record<string, unknown>> = {
-    data: TData;
+type ToolResponseEnvelope<TData = unknown, TMeta = Record<string, unknown>> = {
+    raw: TData;
     meta?: TMeta;
 };
 type ToolExecuteResultBase<TResult = unknown, TMeta = Record<string, unknown>> = {
     status: string;
-    result: ToolResultEnvelope<TResult, TMeta>;
+    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;
@@ -1675,10 +1719,10 @@ type ToolExecuteResultBase<TResult = unknown, TMeta = Record<string, unknown>> =
     };
 };
 type ToolExecuteResultAccessors<TExtracted extends Record<string, unknown> = Record<string, unknown>, TLists extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>> = {
-    extracted: {
+    extractedValues: {
         [K in keyof TExtracted]: ToolResultTargetAccessor<TExtracted[K]>;
     };
-    lists: {
+    extractedLists: {
         [K in keyof TLists]: ToolResultListAccessor<TLists[K]>;
     };
 };
@@ -1817,7 +1861,10 @@ 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.',
  *   });
  *
@@ -1886,24 +1933,30 @@ 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.' });
@@ -1913,17 +1966,14 @@ 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.
@@ -2154,7 +2204,10 @@ declare function when<Row, Value>(predicate: (row: Row, index: number) => boolea
  * 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.',
  *   });
  * });
@@ -2190,14 +2243,14 @@ type PlayMetadata = {
  *
  * @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();
  * ```
  */
@@ -2209,10 +2262,10 @@ declare 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(): {
@@ -2253,9 +2306,9 @@ declare 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' });
  * ```
  */
 declare class Deepline {
@@ -2307,7 +2360,10 @@ declare function defineInput<TInput>(schema: Record<string, unknown>): PlayInput
  *
  * 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;
@@ -2322,7 +2378,10 @@ declare function defineInput<TInput>(schema: Record<string, unknown>): PlayInput
  *   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.' });
@@ -2333,7 +2392,10 @@ declare function defineInput<TInput>(schema: Record<string, unknown>): PlayInput
  * @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;
@@ -2394,7 +2456,7 @@ declare function getDefinedPlayMetadata(value: unknown): PlayMetadata | null;
  * @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}`);
@@ -2411,7 +2473,7 @@ 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;
 };
 type Scalar = string | number | boolean | null;
@@ -2425,7 +2487,7 @@ type Scalar = string | number | boolean | null;
  * ## 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
@@ -2512,7 +2574,7 @@ declare function writeCsvOutputFile(rows: Array<Record<string, unknown>>, stem:
 /**
  * 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.
  *