deepline 0.1.11 → 0.1.19

package/dist/index.d.mts

@@ -264,6 +264,25 @@ interface ToolDefinition {
     resultIdentityGetters?: Record<string, string[]>;
     /** Whether the output is a direct object or wrapped in a `result` envelope. */
     rowContextShape?: 'direct' | 'result_envelope';
+    /** Search relevance score returned by ranked tool search. */
+    search_score?: number;
+    /** Search match snippets returned by ranked tool search. */
+    search_matches?: Array<{
+        field: string;
+        value: string;
+        term?: string;
+    }>;
+}
+interface ToolSearchOptions {
+    query?: string;
+    categories?: string;
+    searchTerms?: string;
+    searchMode?: 'v1' | 'v2';
+    includeSearchDebug?: boolean;
+}
+interface ToolSearchResult {
+    tools: ToolDefinition[];
+    search_fallback_to_category?: boolean;
 }
 /**
  * Extended tool metadata including pricing, samples, and failure modes.
@@ -344,6 +363,8 @@ interface PlayProgressStatus {
     totalRows?: number;
     /** Accumulated log lines from `ctx.log()`. Grows monotonically. */
     logs: string[];
+    /** Zero-based offset of the first returned log line when a tail cursor is used. */
+    logOffset?: number;
     /** Error message if the play has failed. */
     error?: string;
 }
@@ -603,6 +624,8 @@ interface PlayDescription {
     aliases: string[];
     inputSchema?: Record<string, unknown> | null;
     outputSchema?: Record<string, unknown> | null;
+    csvInput?: Record<string, unknown> | null;
+    rowOutputSchema?: Record<string, unknown> | null;
     runCommand: string;
     examples: string[];
     currentPublishedVersion?: number | null;
@@ -722,6 +745,8 @@ interface StartPlayRunRequest {
     artifactStorageKey?: string;
     /** Source snapshot already validated while registering this artifact. */
     sourceCode?: string;
+    /** Source graph snapshots for local helper files included in cloud preflight. */
+    sourceFiles?: Record<string, string>;
     /** Static pipeline already produced while registering this artifact. */
     staticPipeline?: unknown;
     /** Artifact content hash already validated while registering this artifact. */
@@ -793,6 +818,52 @@ interface PlayStagedFileRef {
     bytes: number;
 }
 
+type ExecuteToolRawOptions = {
+    includeToolMetadata?: boolean;
+};
+type ToolExecution<TData = unknown, TMeta = Record<string, unknown>> = {
+    status: string;
+    job_id?: string;
+    result: {
+        data: TData;
+        meta?: TMeta;
+    };
+    billing?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+type RunsListOptions = {
+    play: string;
+    status?: string;
+};
+type RunsTailOptions = {
+    cursor?: string | number;
+    afterLogIndex?: number;
+    waitMs?: number;
+    terminalOnly?: boolean;
+    compact?: boolean;
+};
+type RunsLogsOptions = {
+    limit?: number;
+};
+type RunsLogsResult = {
+    runId: string;
+    totalCount: number;
+    returnedCount: number;
+    firstSequence: number | null;
+    lastSequence: number | null;
+    truncated: boolean;
+    hasMore: boolean;
+    entries: string[];
+};
+type RunsNamespace = {
+    get: (runId: string) => Promise<PlayStatus>;
+    list: (options: RunsListOptions) => Promise<PlayRunListItem[]>;
+    tail: (runId: string, options?: RunsTailOptions) => Promise<PlayStatus>;
+    logs: (runId: string, options?: RunsLogsOptions) => Promise<RunsLogsResult>;
+    stop: (runId: string, options?: {
+        reason?: string;
+    }) => Promise<StopPlayRunResult>;
+};
 /**
  * Low-level client for the Deepline REST API.
  *
@@ -816,6 +887,7 @@ interface PlayStagedFileRef {
 declare class DeeplineClient {
     private readonly http;
     private readonly config;
+    readonly runs: RunsNamespace;
     /**
      * @param options - Optional overrides for API key, base URL, timeout, and retries.
      * @throws {@link ConfigError} if no API key can be resolved from any source.
@@ -824,6 +896,7 @@ declare class DeeplineClient {
     /** The resolved base URL this client is targeting (e.g. `"http://localhost:3000"`). */
     get baseUrl(): string;
     private compactSchema;
+    private schemaMetadata;
     private playRunCommand;
     private summarizePlayListItem;
     private summarizePlayDetail;
@@ -843,6 +916,13 @@ declare class DeeplineClient {
      * ```
      */
     listTools(): Promise<ToolDefinition[]>;
+    /**
+     * Search available tools using Deepline's ranked backend search.
+     *
+     * This is the same discovery surface used by the legacy CLI: it ranks across
+     * tool metadata, categories, agent guidance, and input schema fields.
+     */
+    searchTools(options?: ToolSearchOptions): Promise<ToolSearchResult>;
     /**
      * Get detailed metadata for a single tool.
      *
@@ -861,44 +941,15 @@ declare class DeeplineClient {
      */
     getTool(toolId: string): Promise<ToolMetadata>;
     /**
-     * Execute a tool and return the extracted result.
-     *
-     * Sends the input payload to the tool and returns the `.result` field from the
-     * response. For the full response envelope (including job_id, credits, etc.),
-     * use {@link executeToolRaw}.
-     *
-     * @param toolId - Tool identifier (e.g. `"test_company_search"`)
-     * @param input - Tool-specific input parameters
-     * @returns The tool's output (shape varies by tool)
-     * @throws {@link DeeplineError} if the tool execution fails
-     *
-     * @example
-     * ```typescript
-     * const company = await client.executeTool('test_company_search', {
-     *   domain: 'stripe.com',
-     * });
-     * console.log(company); // { name: "Stripe", industry: "Financial Services", ... }
-     * ```
-     */
-    executeTool(toolId: string, input: Record<string, unknown>): Promise<unknown>;
-    /**
-     * Execute a tool and return the full response envelope.
-     *
-     * Unlike {@link executeTool}, this returns the complete API response including
-     * `job_id`, `status`, `credits`, and the raw `result` object.
-     *
-     * @param toolId - Tool identifier
-     * @param input - Tool-specific input parameters
-     * @returns Full response with job metadata and result
+     * Execute a tool and return the standard execution envelope.
      *
-     * @example
-     * ```typescript
-     * const raw = await client.executeToolRaw('test_company_search', { domain: 'stripe.com' });
-     * console.log(`Job: ${raw.job_id}, Credits: ${raw.credits}`);
-     * console.log(`Result:`, raw.result);
-     * ```
+     * The `result.data` field contains the provider payload. `result.meta`
+     * contains provider/upstream metadata such as HTTP status or paging details.
+     * Top-level fields such as `status`, `job_id`, and `billing` describe the
+     * Deepline execution.
      */
-    executeToolRaw(toolId: string, input: Record<string, unknown>): Promise<Record<string, unknown>>;
+    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>>;
     queryCustomerDb(input: {
         sql: string;
         maxRows?: number;
@@ -949,6 +1000,7 @@ declare class DeeplineClient {
     registerPlayArtifact(input: {
         name: string;
         sourceCode: string;
+        sourceFiles?: Record<string, string>;
         artifact: Record<string, unknown>;
         compilerManifest?: PlayCompilerManifest;
         publish?: boolean;
@@ -971,6 +1023,7 @@ declare class DeeplineClient {
     registerPlayArtifacts(artifacts: Array<{
         name: string;
         sourceCode: string;
+        sourceFiles?: Record<string, string>;
         artifact: Record<string, unknown>;
         compilerManifest?: PlayCompilerManifest;
         publish?: boolean;
@@ -996,6 +1049,7 @@ declare class DeeplineClient {
     compilePlayManifest(input: {
         name: string;
         sourceCode: string;
+        sourceFiles?: Record<string, string>;
         artifact: Record<string, unknown>;
         importedPlayDependencies?: PlayCompilerManifest[];
     }): Promise<PlayCompilerManifest>;
@@ -1009,11 +1063,13 @@ declare class DeeplineClient {
     checkPlayArtifact(input: {
         name?: string;
         sourceCode: string;
+        sourceFiles?: Record<string, string>;
         artifact: Record<string, unknown>;
     }): Promise<PlayCheckResult>;
     startPlayRunFromBundle(input: {
         name: string;
         sourceCode: string;
+        sourceFiles?: Record<string, string>;
         artifact: Record<string, unknown>;
         compilerManifest?: PlayCompilerManifest;
         input?: Record<string, unknown>;
@@ -1047,6 +1103,7 @@ declare class DeeplineClient {
      */
     submitPlay(code: string, csvPath: string | null, name?: string, options?: {
         sourceCode?: string;
+        sourceFiles?: Record<string, string>;
         artifact?: Record<string, unknown>;
         compilerManifest?: PlayCompilerManifest;
         input?: Record<string, unknown>;
@@ -1181,6 +1238,58 @@ declare class DeeplineClient {
      * ```
      */
     listPlayRuns(playName: string): Promise<PlayRunListItem[]>;
+    /**
+     * Get a run by id using the public runs resource model.
+     *
+     * This is the SDK equivalent of:
+     *
+     * ```bash
+     * deepline runs get <run-id> --json
+     * ```
+     */
+    getRunStatus(runId: string): Promise<PlayStatus>;
+    /**
+     * List play runs using the public runs resource model.
+     *
+     * This is the SDK equivalent of:
+     *
+     * ```bash
+     * deepline runs list --play <play-name> --status failed --json
+     * ```
+     */
+    listRuns(options: RunsListOptions): Promise<PlayRunListItem[]>;
+    /**
+     * Fetch the lightweight tail status for a run using the public runs resource model.
+     *
+     * This is the SDK equivalent of:
+     *
+     * ```bash
+     * deepline runs tail <run-id> --json
+     * ```
+     */
+    tailRun(runId: string, options?: RunsTailOptions): Promise<PlayStatus>;
+    /**
+     * Fetch persisted logs for a run using the public runs resource model.
+     *
+     * This is the SDK equivalent of:
+     *
+     * ```bash
+     * deepline runs logs <run-id> --limit 200 --json
+     * ```
+     */
+    getRunLogs(runId: string, options?: RunsLogsOptions): Promise<RunsLogsResult>;
+    /**
+     * Stop a run by id using the public runs resource model.
+     *
+     * This is the SDK equivalent of:
+     *
+     * ```bash
+     * deepline runs stop <run-id> --reason "stale lock" --json
+     * ```
+     */
+    stopRun(runId: string, options?: {
+        reason?: string;
+    }): Promise<StopPlayRunResult>;
     listPlays(): Promise<PlayListItem[]>;
     searchPlays(options: {
         query: string;
@@ -1325,8 +1434,8 @@ declare class DeeplineClient {
     }>;
 }
 
-declare const SDK_VERSION = "0.1.11";
-declare const SDK_API_CONTRACT = "2026-04-plays-v1";
+declare const SDK_VERSION = "0.1.19";
+declare const SDK_API_CONTRACT = "2026-05-runs-v2";
 
 /**
  * Base error class for all Deepline SDK errors.
@@ -1468,164 +1577,6 @@ declare const PROD_URL = "https://code.deepline.com";
  */
 declare function resolveConfig(options?: DeeplineClientOptions): ResolvedConfig;
 
-/**
- * Result of converting a tool response to a list of records.
- *
- * @example
- * ```typescript
- * const conversion = tryConvertToList(toolResponse, {
- *   listExtractorPaths: ['people', 'result.data'],
- * });
- * if (conversion) {
- *   console.log(`Found ${conversion.rows.length} rows via ${conversion.strategy}`);
- *   console.log(`Source path: ${conversion.sourcePath}`);
- * }
- * ```
- */
-type ListConversionResult = {
-    /** Normalized array of record objects. Scalars are wrapped as `{ value: <scalar> }`. */
-    rows: Array<Record<string, unknown>>;
-    /**
-     * How the list was found:
-     * - `'configured_paths'` — matched one of the `listExtractorPaths`
-     * - `'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"`). */
-    sourcePath: string | null;
-};
-type Scalar = string | number | boolean | null;
-/** Ergonomic wrapper returned by high-level SDK tool execution. */
-type ToolCallResult = {
-    /** Raw tool response. Use this when a provider-specific shape matters. */
-    readonly value: unknown;
-    /** Best-effort email extraction from common response shapes. */
-    getEmail(): string | null;
-    /** Best-effort phone extraction from common response shapes. */
-    getPhone(): string | null;
-    /** Best-effort list extraction. Returns rows only; use `tryConvertToList` for metadata. */
-    tryList(options?: {
-        listExtractorPaths?: string[];
-    }): Array<Record<string, unknown>> | null;
-};
-/** Wrap a raw tool response with the high-level SDK result API. */
-declare function createToolCallResult(value: unknown, options?: {
-    listExtractorPaths?: string[];
-}): ToolCallResult;
-/**
- * Extract a list of records from a tool response.
- *
- * Handles the common problem of tools returning data in varied shapes.
- * First tries configured `listExtractorPaths` (from tool metadata), then
- * falls back to automatic detection via recursive DFS.
- *
- * ## Extraction strategy
- *
- * 1. **Configured paths** — If `listExtractorPaths` is provided, each path is
- *    tried against multiple candidate roots (raw payload, `.result`, `.result.data`).
- *    First match wins.
- *
- * 2. **Auto-detection** — If no configured path matches, recursively searches
- *    the response for the largest array of objects (up to depth 5).
- *
- * @param payload - Raw tool response
- * @param options - Optional extraction configuration
- * @returns Extracted list with metadata, or `null` if no list found
- *
- * @example Using configured paths (from tool metadata)
- * ```typescript
- * const meta = await client.getTool('apollo_people_search');
- * const result = await client.executeTool('apollo_people_search', { query: 'cto' });
- *
- * const list = tryConvertToList(result, {
- *   listExtractorPaths: meta.listExtractorPaths,
- * });
- * if (list) {
- *   console.log(`${list.rows.length} people found via ${list.strategy}`);
- *   // Write to CSV
- *   const csv = writeCsvOutputFile(list.rows, 'apollo-people');
- *   console.log(`Saved to ${csv.path}`);
- * }
- * ```
- *
- * @example Auto-detection (no configured paths)
- * ```typescript
- * const result = await client.executeTool('some_tool', { query: 'test' });
- * const list = tryConvertToList(result);
- * // Finds the largest array of objects anywhere in the response
- * ```
- */
-declare function tryConvertToList(payload: unknown, options?: {
-    listExtractorPaths?: string[];
-}): ListConversionResult | null;
-/**
- * Write a JSON payload to a timestamped file.
- *
- * Output location: `~/.local/share/deepline/data/{stem}_{timestamp}.json`
- *
- * @param payload - Any JSON-serializable value
- * @param stem - Filename prefix (e.g. tool ID or play name)
- * @returns Absolute path to the written file
- *
- * @example
- * ```typescript
- * const result = await client.executeTool('test_company_search', { domain: 'stripe.com' });
- * const path = writeJsonOutputFile(result, 'test_company_search');
- * console.log(`Saved to ${path}`);
- * // ~/.local/share/deepline/data/test_company_search_1713456789000.json
- * ```
- */
-declare function writeJsonOutputFile(payload: unknown, stem: string): string;
-/**
- * Write an array of records to a CSV file.
- *
- * Columns are ordered by first appearance across all rows. Cells containing
- * commas, quotes, or newlines are properly escaped. Objects and arrays are
- * JSON-serialized.
- *
- * Output location: `~/.local/share/deepline/data/{stem}_{timestamp}.csv`
- *
- * @param rows - Array of record objects
- * @param stem - Filename prefix
- * @returns File metadata including path, row count, columns, and a 5×5 preview
- *
- * @example
- * ```typescript
- * const list = tryConvertToList(toolResponse);
- * if (list) {
- *   const csv = writeCsvOutputFile(list.rows, 'search-results');
- *   console.log(`Wrote ${csv.rowCount} rows, ${csv.columns.length} columns`);
- *   console.log(`File: ${csv.path}`);
- *   console.log(`Preview:\n${csv.preview}`);
- * }
- * ```
- */
-declare function writeCsvOutputFile(rows: Array<Record<string, unknown>>, stem: string): {
-    path: string;
-    rowCount: number;
-    columns: string[];
-    preview: string;
-};
-/**
- * Extract scalar (non-nested) fields from a tool response for summary display.
- *
- * Searches through candidate roots (raw → `.result` → `.result.data`) and
- * returns the first set of scalar fields found. Useful for displaying a
- * quick summary of single-record responses.
- *
- * @param payload - Raw tool response
- * @returns Object containing only scalar fields (string, number, boolean, null)
- *
- * @example
- * ```typescript
- * const result = await client.executeTool('test_company_search', { domain: 'stripe.com' });
- * const summary = extractSummaryFields(result);
- * // { name: "Stripe", industry: "Financial Services", employeeCount: 8000 }
- * // (nested objects and arrays are excluded)
- * ```
- */
-declare function extractSummaryFields(payload: unknown): Record<string, Scalar>;
-
 interface PlayR2FileRef {
     storageKind: 'r2';
     storageKey: string;
@@ -1649,6 +1600,20 @@ type PlayDatasetBacking = {
     storage: 'r2_file';
     file: PlayExecutionFileRef;
 };
+type PlayDatasetWorkProgressSummary = {
+    total: number;
+    executed: number;
+    reused: number;
+    skipped: number;
+    pending: number;
+    failed: number;
+    degraded?: boolean;
+    duplicates?: {
+        exact?: number;
+        semantic?: number;
+        rejected?: number;
+    };
+};
 type PlayDatasetInput<T> = ReadonlyArray<T> | Iterable<T> | AsyncIterable<T> | PlayDataset<T>;
 interface PlayDataset<T> extends AsyncIterable<T> {
     readonly [PLAY_DATASET_BRAND]: true;
@@ -1674,10 +1639,65 @@ interface PlayDataset<T> extends AsyncIterable<T> {
         sourceLabel?: string | null;
         tableNamespace?: string | null;
         columns?: string[];
+        _metadata?: {
+            workProgress?: PlayDatasetWorkProgressSummary;
+        };
         preview: T[];
     };
 }
 
+type ToolResultExecutionMetadata = {
+    idempotent: true;
+    cached: boolean;
+    source: 'live' | 'checkpoint' | 'cache';
+    cacheKey?: string;
+};
+type ToolResultTargetMetadata = {
+    value: unknown;
+    path: string;
+};
+type ToolResultListMetadata = {
+    path: string;
+    count: number | null;
+    keys: Record<string, string>;
+};
+type ToolResultTargetAccessor<T = unknown> = ToolResultTargetMetadata & {
+    get(): T | null;
+};
+type ToolResultListAccessor<T = Record<string, unknown>> = ToolResultListMetadata & {
+    get(): T[];
+};
+type ToolResultEnvelope<TData = unknown, TMeta = Record<string, unknown>> = {
+    data: TData;
+    meta?: TMeta;
+};
+type ToolExecuteResultBase<TResult = unknown, TMeta = Record<string, unknown>> = {
+    status: string;
+    result: ToolResultEnvelope<TResult, TMeta>;
+    _metadata: {
+        toolId: string;
+        execution: ToolResultExecutionMetadata;
+        targets: Record<string, {
+            value: unknown;
+            path: string;
+        }>;
+        lists: Record<string, {
+            path: string;
+            count: number | null;
+            keys: Record<string, string>;
+        }>;
+    };
+};
+type ToolExecuteResultAccessors<TExtracted extends Record<string, unknown> = Record<string, unknown>, TLists extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>> = {
+    extracted: {
+        [K in keyof TExtracted]: ToolResultTargetAccessor<TExtracted[K]>;
+    };
+    lists: {
+        [K in keyof TLists]: ToolResultListAccessor<TLists[K]>;
+    };
+};
+type ToolExecuteResult<TResult = unknown, TMeta = Record<string, unknown>, TExtracted extends Record<string, unknown> = Record<string, unknown>, TLists extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>> = ToolExecuteResultBase<TResult, TMeta> & ToolExecuteResultAccessors<TExtracted, TLists>;
+
 /**
  * Optional trigger bindings for a play.
  *
@@ -1733,45 +1753,13 @@ type PlayBindings = {
 type LoosePlayObject = {
     [key: string]: LoosePlayObject;
 };
+
 type ToolExecutionRequest = {
     id: string;
     tool: string;
     input: Record<string, unknown>;
     description?: string;
 };
-type SdkToolExecutionRequest = {
-    tool: string;
-    input: Record<string, unknown>;
-};
-type ToolExecuteResult<TResult = unknown> = {
-    status: string;
-    result: TResult;
-    _metadata: {
-        toolId: string;
-        execution: {
-            idempotent: true;
-            cached: boolean;
-            source: 'live' | 'checkpoint' | 'cache';
-            cacheKey?: string;
-        };
-        targets: Record<string, {
-            value: unknown;
-            path: string;
-        }>;
-        lists: Record<string, {
-            path: string;
-            count: number | null;
-            keys: Record<string, string>;
-        }>;
-    };
-    get<T = unknown>(target: string): T | null;
-    getEmail(): string | null;
-    getPhone(): string | null;
-    getLinkedin(): string | null;
-    list<T = Record<string, unknown>>(name?: string): T[] | null;
-    listPick<const TKeys extends readonly string[]>(keys: TKeys, name?: string): Array<Record<TKeys[number], unknown>> | null;
-    listKeys(name?: string): Record<string, string>;
-};
 type StepResolver<Row, Value> = (row: Row, ctx: DeeplinePlayRuntimeContext, index: number) => Value | Promise<Value>;
 type ConditionalStepResolver<Row, Value, Else = null> = {
     readonly kind: 'conditional';
@@ -1799,17 +1787,39 @@ type PlayStepProgramStep = {
     readonly resolver: StepResolver<Record<string, unknown>, unknown> | ConditionalStepResolver<Record<string, unknown>, unknown> | StepProgramResolver<Record<string, unknown>, unknown>;
 };
 type MapStepResolver<Row, Value> = StepResolver<Row, Value> | ConditionalStepResolver<Row, Value> | StepProgramResolver<Row, Value>;
-type MapRowKey<InputRow extends object> = (keyof InputRow & string) | readonly (keyof InputRow & string)[] | ((row: InputRow, index: number) => string | number | readonly unknown[]);
-type MapDefinitionOptions<InputRow extends object> = {
-    staleAfterSeconds?: number;
-    key?: MapRowKey<InputRow>;
-};
-type MapRunOptions = {
-    description?: string;
-};
 type MapStepBuilder<InputRow extends object, OutputRow extends object> = {
     step<Name extends string, Value>(name: Name, resolver: MapStepResolver<OutputRow, Value>): MapStepBuilder<InputRow, OutputRow & Record<Name, Value>>;
-    run(options?: MapRunOptions): Promise<PlayDataset<OutputRow>>;
+    run(options?: {
+        description?: string;
+        staleAfterSeconds?: number;
+        key?: (keyof InputRow & string) | readonly (keyof InputRow & string)[] | ((row: InputRow, index: number) => string | number | readonly unknown[]);
+    }): Promise<PlayDataset<OutputRow>>;
+};
+type CsvRenameMap = Record<string, string | readonly string[]>;
+/**
+ * Runtime file-like input. At runtime this is the staged file path/reference
+ * string. The type parameter carries static metadata for describe/CLI tooling.
+ */
+type FileInput<TMetadata = unknown> = string & {
+    readonly __deeplineFileInputMetadata?: TMetadata;
+};
+/**
+ * CSV file input whose rows are described by `TRow`.
+ *
+ * The CLI should expose this as the field name from the play input object,
+ * stage local paths passed to that flag, and use `TRow` for row-contract
+ * discovery.
+ */
+type CsvInput<TRow extends object = Record<string, unknown>> = FileInput<{
+    readonly kind: 'csv';
+    readonly row: TRow;
+}>;
+type ColumnMap<TRow extends object> = Partial<Record<Extract<keyof TRow, string>, string | readonly string[]>>;
+type CsvOptions = {
+    description?: string;
+    columns?: CsvRenameMap;
+    rename?: CsvRenameMap;
+    required?: readonly string[];
 };
 /**
  * Runtime context available inside a play function.
@@ -1821,21 +1831,15 @@ type MapStepBuilder<InputRow extends object, OutputRow extends object> = {
  * ```typescript
  * definePlay('example', async (ctx, input: { domain: string }) => {
  *   // Call a tool
- *   const company = await ctx.tools.execute({
- *     id: 'company_search',
- *     tool: 'test_company_search',
- *     input: { domain: input.domain },
+ *   const company = await ctx.tools.execute('company_search', 'test_company_search', { domain: input.domain }, {
  *     description: 'Look up company details by domain.',
  *   });
  *
  *   // Fan-out: process items with named steps
  *   const enriched = await ctx
- *     .map('companies', [{ domain: 'a.com' }, { domain: 'b.com' }], { key: 'domain' })
+ *     .map('companies', [{ domain: 'a.com' }, { domain: 'b.com' }])
  *     .step('company', (row, rowCtx) =>
- *       rowCtx.tool({
- *         id: 'company_search',
- *         tool: 'test_company_search',
- *         input: { domain: row.domain },
+ *       rowCtx.tool('company_search', 'test_company_search', { domain: row.domain }, {
  *         description: 'Look up company details by domain.',
  *       }))
  *     .run({ description: 'Look up company details.' });
@@ -1870,9 +1874,7 @@ interface DeeplinePlayRuntimeContext {
      *
      * @returns Parsed dataset rows
      */
-    csv<T = Record<string, unknown>>(path: string, options?: {
-        description?: string;
-    }): Promise<PlayDataset<T>>;
+    csv<T = Record<string, unknown>>(path: string, options?: CsvOptions): Promise<PlayDataset<T>>;
     /**
      * Fan-out: process each item through one or more named columns.
      *
@@ -1881,9 +1883,8 @@ interface DeeplinePlayRuntimeContext {
      * play context — call tools, run waterfalls, do arbitrary logic.
      *
      * Items are processed in parallel (paced by the rate-limit scheduler).
-     * The first argument identifies the logical map/table namespace. Use
-     * `options.key` to pin durable row identity to stable input fields instead of
-     * hashing the full input row.
+     * `key` identifies the logical output dataset/table. Row identity is derived
+     * automatically from item content unless advanced run options override it.
      * `options.staleAfterSeconds` intentionally partitions the durable cache on a
      * relative time window. Use `86400` for daily reruns; retries inside the same
      * window still replay safely.
@@ -1893,19 +1894,16 @@ interface DeeplinePlayRuntimeContext {
      * play dataset handle.
      *
      * @typeParam T - Row type
-     * @param key - Logical map key used to isolate row identities (e.g. `'main_table'`, `'email_lookup'`)
+     * @param key - Logical output dataset/table name (e.g. `'companies'`, `'email_lookup'`)
      * @param items - Input rows or dataset handle
      * @returns Dataset of rows merged with the computed column values
      *
      * @example Single tool per row
      * ```typescript
      * const results = await ctx
-     *   .map('leads', leads, { key: 'domain' })
+     *   .map('companies', leads)
      *   .step('company', (row, ctx) =>
-     *     ctx.tools.execute({
-     *       id: 'company_search',
-     *       tool: 'test_company_search',
-     *       input: { domain: row.domain },
+     *     ctx.tools.execute('company_search', 'test_company_search', { domain: row.domain }, {
      *       description: 'Look up company details by domain.',
      *     }))
      *   .run({ description: 'Look up companies.' });
@@ -1915,12 +1913,9 @@ interface DeeplinePlayRuntimeContext {
      * @example Multiple columns with pre/post logic
      * ```typescript
      * const results = await ctx
-     *   .map('leads', leads, { key: 'lead_id' })
+     *   .map('leads', leads)
      *   .step('company', (row, ctx) =>
-     *     ctx.tools.execute({
-     *       id: 'company_search',
-     *       tool: 'test_company_search',
-     *       input: { domain: row.domain },
+     *     ctx.tools.execute('company_search', 'test_company_search', { domain: row.domain }, {
      *       description: 'Look up company details by domain.',
      *     }))
      *   .step('score', (row) =>
@@ -1928,25 +1923,31 @@ interface DeeplinePlayRuntimeContext {
      *   .run({ description: 'Enrich leads.' });
      * ```
      */
-    map<TItem extends object>(key: string, items: PlayDatasetInput<TItem>, options?: MapDefinitionOptions<TItem>): MapStepBuilder<TItem, TItem>;
+    map<TItem extends object>(key: string, items: PlayDatasetInput<TItem>): MapStepBuilder<TItem, TItem>;
     /** Tool execution namespace. */
     tools: {
         /**
-         * Execute a single tool by stable durable execution id and tool ID.
+         * Execute a single tool by stable step key and tool ID.
          *
-         * @param request - Tool execution request. `id` is the durable execution id;
-         *   omit it in row/map steps when the surrounding step id is the execution id.
+         * @param key - Stable step key for idempotent execution
+         * @param toolId - Tool identifier (e.g. `'test_company_search'`)
+         * @param 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 durable execution id and tool ID.
+     * Execute a single tool by stable step key and tool ID.
      *
-     * Shorthand for `ctx.tools.execute({ id, tool, input })`; this is the
-     * preferred spelling in row-level step programs.
+     * Shorthand for `ctx.tools.execute(...)`; this is the preferred spelling in
+     * row-level step programs.
      */
-    tool<TOutput = LoosePlayObject>(request: ToolExecutionRequest): Promise<ToolExecuteResult<TOutput>>;
+    tool<TOutput = LoosePlayObject>(key: string, toolId: string, input: Record<string, unknown>, options?: {
+        description?: string;
+    }): Promise<ToolExecuteResult<TOutput>>;
     step<T>(id: string, run: () => T | Promise<T>): Promise<T>;
     fetch(key: string, url: string | URL, init?: RequestInit): Promise<{
         ok: boolean;
@@ -2164,13 +2165,9 @@ 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 }) => {
- *   const company = await ctx.tools.execute({
- *     id: 'company_search',
- *     tool: 'test_company_search',
- *     input: { domain: input.domain },
+ *   return await ctx.tools.execute('company_search', 'test_company_search', { domain: input.domain }, {
  *     description: 'Look up company details by domain.',
  *   });
- *   return { company: company.result };
  * });
  *
  * // Type is: DefinedPlay<{ domain: string }, unknown>
@@ -2208,10 +2205,7 @@ type PlayMetadata = {
  *
  * // Tools
  * const tools = await ctx.tools.list();
- * const result = await ctx.tools.execute({
- *   tool: 'test_company_search',
- *   input: { domain: 'stripe.com' },
- * });
+ * const result = await ctx.tools.execute('test_company_search', { domain: 'stripe.com' });
  *
  * // Plays
  * const job = await ctx.play('email-waterfall').run({ domain: 'stripe.com' });
@@ -2228,12 +2222,8 @@ declare class DeeplineContext {
      * ```typescript
      * const tools = await ctx.tools.list();
      * const meta = await ctx.tools.get('apollo_people_search');
-     * const result = await ctx.tools.execute({
-     *   tool: 'test_company_search',
-     *   input: { domain: 'stripe.com' },
-     * });
-     * const rows = result.tryList({ listExtractorPaths: ['people'] });
-     * const email = result.getEmail();
+     * const companyLookup = await ctx.tools.execute('test_company_search', { domain: 'stripe.com' });
+     * const company = companyLookup.result.data;
      * ```
      */
     get tools(): {
@@ -2241,8 +2231,8 @@ declare class DeeplineContext {
         list: () => Promise<ToolDefinition[]>;
         /** Get detailed metadata for a tool. */
         get: (toolId: string) => Promise<ToolMetadata>;
-        /** Execute a tool and return an ergonomic result wrapper. */
-        execute: (request: SdkToolExecutionRequest) => Promise<ToolCallResult>;
+        /** Execute a tool and return the standard execution envelope. */
+        execute: (toolId: string, input: Record<string, unknown>) => Promise<ToolExecuteResult>;
     };
     get plays(): {
         list: () => Promise<PlayListItem[]>;
@@ -2276,10 +2266,7 @@ declare class DeeplineContext {
  *
  * const ctx = await Deepline.connect();
  * const tools = await ctx.tools.list();
- * const result = await ctx.tools.execute({
- *   tool: 'test_company_search',
- *   input: { domain: 'stripe.com' },
- * });
+ * const result = await ctx.tools.execute('test_company_search', { domain: 'stripe.com' });
  * ```
  */
 declare class Deepline {
@@ -2331,13 +2318,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({
- *     id: 'company_search',
- *     tool: 'test_company_search',
- *     input: { domain: input.domain },
+ *   const company = await ctx.tools.execute('company_search', 'test_company_search', { domain: input.domain }, {
  *     description: 'Look up company details by domain.',
  *   });
- *   return { company: company.result };
+ *   return company;
  * });
  * ```
  *
@@ -2347,12 +2331,9 @@ declare function defineInput<TInput>(schema: Record<string, unknown>): PlayInput
  *   const leads = await ctx.csv('leads.csv');
  *   ctx.log(`Processing ${leads.length} rows`);
  *   const results = await ctx
- *     .map('domain', leads)
+ *     .map('companies', leads)
  *     .step('company', (row, ctx) =>
- *       ctx.tools.execute({
- *         id: 'company_search',
- *         tool: 'test_company_search',
- *         input: { domain: row.domain },
+ *       ctx.tools.execute('company_search', 'test_company_search', { domain: row.domain }, {
  *         description: 'Look up company details by domain.',
  *       }))
  *     .run({ description: 'Enrich lead companies.' });
@@ -2363,10 +2344,7 @@ 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({
- *     id: 'crm_export',
- *     tool: 'crm_export',
- *     input: { since: 'yesterday' },
+ *   const data = await ctx.tools.execute('crm_export', 'crm_export', { since: 'yesterday' }, {
  *     description: 'Export yesterday CRM records.',
  *   });
  *   return data;
@@ -2421,4 +2399,145 @@ declare const defineWorkflow: typeof definePlay;
  */
 declare function getDefinedPlayMetadata(value: unknown): PlayMetadata | null;
 
-export { AuthError, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ConditionalStepResolver, ConfigError, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, DeeplineError, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DefinePlayConfig, type DefinedPlay, type LiveEventEnvelope, type MapDefinitionOptions, type MapRowKey, type MapRunOptions, type MapStepBuilder, type MapStepResolver, PROD_URL, type PlayBindings, type PlayDataset, type PlayDatasetInput, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunResult, type PlayRunStart, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, SDK_API_CONTRACT, SDK_VERSION, type StartPlayRunRequest, type StepProgram, type StepProgramResolver, type StepResolver, type ToolCallResult, type ToolDefinition, type ToolExecuteResult, type ToolMetadata, createToolCallResult, defineInput, definePlay, defineWorkflow, extractSummaryFields, getDefinedPlayMetadata, resolveConfig, steps, tryConvertToList, when, writeCsvOutputFile, writeJsonOutputFile };
+/**
+ * Result of converting a tool response to a list of records.
+ *
+ * @example
+ * ```typescript
+ * const conversion = tryConvertToList(toolResponse, {
+ *   listExtractorPaths: ['people', 'result.data'],
+ * });
+ * if (conversion) {
+ *   console.log(`Found ${conversion.rows.length} rows via ${conversion.strategy}`);
+ *   console.log(`Source path: ${conversion.sourcePath}`);
+ * }
+ * ```
+ */
+type ListConversionResult = {
+    /** Normalized array of record objects. Scalars are wrapped as `{ value: <scalar> }`. */
+    rows: Array<Record<string, unknown>>;
+    /**
+     * How the list was found:
+     * - `'configured_paths'` — matched one of the `listExtractorPaths`
+     * - `'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"`). */
+    sourcePath: string | null;
+};
+type Scalar = string | number | boolean | null;
+/**
+ * Extract a list of records from a tool response.
+ *
+ * Handles the common problem of tools returning data in varied shapes.
+ * First tries configured `listExtractorPaths` (from tool metadata), then
+ * falls back to automatic detection via recursive DFS.
+ *
+ * ## Extraction strategy
+ *
+ * 1. **Configured paths** — If `listExtractorPaths` is provided, each path is
+ *    tried against multiple candidate roots (raw payload, `.result`, `.result.data`).
+ *    First match wins.
+ *
+ * 2. **Auto-detection** — If no configured path matches, recursively searches
+ *    the response for the largest array of objects (up to depth 5).
+ *
+ * @param payload - Raw tool response
+ * @param options - Optional extraction configuration
+ * @returns Extracted list with metadata, or `null` if no list found
+ *
+ * @example Using configured paths (from tool metadata)
+ * ```typescript
+ * const meta = await client.getTool('apollo_people_search');
+ * const result = await client.executeTool('apollo_people_search', { query: 'cto' });
+ *
+ * const list = tryConvertToList(result, {
+ *   listExtractorPaths: meta.listExtractorPaths,
+ * });
+ * if (list) {
+ *   console.log(`${list.rows.length} people found via ${list.strategy}`);
+ *   // Write to CSV
+ *   const csv = writeCsvOutputFile(list.rows, 'apollo-people');
+ *   console.log(`Saved to ${csv.path}`);
+ * }
+ * ```
+ *
+ * @example Auto-detection (no configured paths)
+ * ```typescript
+ * const result = await client.executeTool('some_tool', { query: 'test' });
+ * const list = tryConvertToList(result);
+ * // Finds the largest array of objects anywhere in the response
+ * ```
+ */
+declare function tryConvertToList(payload: unknown, options?: {
+    listExtractorPaths?: string[];
+}): ListConversionResult | null;
+/**
+ * Write a JSON payload to a timestamped file.
+ *
+ * Output location: `~/.local/share/deepline/data/{stem}_{timestamp}.json`
+ *
+ * @param payload - Any JSON-serializable value
+ * @param stem - Filename prefix (e.g. tool ID or play name)
+ * @returns Absolute path to the written file
+ *
+ * @example
+ * ```typescript
+ * const result = await client.executeTool('test_company_search', { domain: 'stripe.com' });
+ * const path = writeJsonOutputFile(result, 'test_company_search');
+ * console.log(`Saved to ${path}`);
+ * // ~/.local/share/deepline/data/test_company_search_1713456789000.json
+ * ```
+ */
+declare function writeJsonOutputFile(payload: unknown, stem: string): string;
+/**
+ * Write an array of records to a CSV file.
+ *
+ * Columns are ordered by first appearance across all rows. Cells containing
+ * commas, quotes, or newlines are properly escaped. Objects and arrays are
+ * JSON-serialized.
+ *
+ * Output location: `~/.local/share/deepline/data/{stem}_{timestamp}.csv`
+ *
+ * @param rows - Array of record objects
+ * @param stem - Filename prefix
+ * @returns File metadata including path, row count, columns, and a 5×5 preview
+ *
+ * @example
+ * ```typescript
+ * const list = tryConvertToList(toolResponse);
+ * if (list) {
+ *   const csv = writeCsvOutputFile(list.rows, 'search-results');
+ *   console.log(`Wrote ${csv.rowCount} rows, ${csv.columns.length} columns`);
+ *   console.log(`File: ${csv.path}`);
+ *   console.log(`Preview:\n${csv.preview}`);
+ * }
+ * ```
+ */
+declare function writeCsvOutputFile(rows: Array<Record<string, unknown>>, stem: string): {
+    path: string;
+    rowCount: number;
+    columns: string[];
+    preview: string;
+};
+/**
+ * Extract scalar (non-nested) fields from a tool response for summary display.
+ *
+ * Searches through candidate roots (raw → `.result` → `.result.data`) and
+ * returns the first set of scalar fields found. Useful for displaying a
+ * quick summary of single-record responses.
+ *
+ * @param payload - Raw tool response
+ * @returns Object containing only scalar fields (string, number, boolean, null)
+ *
+ * @example
+ * ```typescript
+ * const result = await client.executeTool('test_company_search', { domain: 'stripe.com' });
+ * const summary = extractSummaryFields(result);
+ * // { name: "Stripe", industry: "Financial Services", employeeCount: 8000 }
+ * // (nested objects and arrays are excluded)
+ * ```
+ */
+declare function extractSummaryFields(payload: unknown): Record<string, Scalar>;
+
+export { AuthError, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ConditionalStepResolver, ConfigError, type CsvInput, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, DeeplineError, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DefinePlayConfig, type DefinedPlay, type FileInput, type LiveEventEnvelope, type MapStepBuilder, type MapStepResolver, PROD_URL, type PlayBindings, type PlayDataset, type PlayDatasetInput, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunResult, type PlayRunStart, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, SDK_API_CONTRACT, SDK_VERSION, type StartPlayRunRequest, type StepProgram, type StepProgramResolver, type StepResolver, type ToolDefinition, type ToolExecuteResult, type ToolExecution, type ToolMetadata, defineInput, definePlay, defineWorkflow, extractSummaryFields, getDefinedPlayMetadata, resolveConfig, steps, tryConvertToList, when, writeCsvOutputFile, writeJsonOutputFile };