deepline 0.1.33 → 0.1.35

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.toolOutput.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,60 @@ 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.toolExecutionResult?.toolOutput?.raw ?? null;
+  const meta = response.toolExecutionResult?.toolOutput?.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',
+    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',
+    },
+  });
+}
+
 export function defineInput<TInput>(
   schema: Record<string, unknown>,
 ): PlayInputContract<TInput> {
@@ -1092,7 +1162,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 +1180,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 +1194,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,29 @@ 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 toolExecutionResult.toolOutput.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.toolExecutionResult)) {
+    roots.push({ path: 'toolExecutionResult', value: payload.toolExecutionResult });
+    const toolOutput = payload.toolExecutionResult.toolOutput;
+    if (isPlainObject(toolOutput)) {
+      roots.push({ path: 'toolExecutionResult.toolOutput', value: toolOutput });
+      if (Object.prototype.hasOwnProperty.call(toolOutput, 'raw')) {
+        roots.push({
+          path: 'toolExecutionResult.toolOutput.raw',
+          value: toolOutput.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 +186,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 +363,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.
  *

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

@@ -103,17 +103,51 @@ export 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';
+      toolOutput?: {
+        raw?: string | { path?: string; schema?: Record<string, unknown> };
+        meta?: string | { path?: string; schema?: Record<string, unknown> };
+      };
+      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. */

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

@@ -1,2 +1,2 @@
-export const SDK_VERSION = "0.1.33";
-export const SDK_API_CONTRACT = "2026-05-host-env-generic-play-input-flags";
+export const SDK_VERSION = "0.1.35";
+export const SDK_API_CONTRACT = "2026-05-v2-tool-result-contract";

package/dist/repo/shared_libs/play-runtime/run-failure.ts

@@ -0,0 +1,49 @@
+export const CLOUDFLARE_DURABLE_OBJECT_CODE_UPDATED_ERROR =
+  'Durable Object reset because its code was updated.';
+
+export const PLATFORM_DEPLOY_INTERRUPTED_MESSAGE =
+  'Run interrupted by a platform deploy and was not retried automatically. Re-run the same command; the input is unchanged.';
+
+export type PlayRunFailureDetails = {
+  code: string;
+  phase: string;
+  message: string;
+  retryable: boolean | null;
+  cause?: string;
+};
+
+function toErrorText(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+
+export function isCloudflareDurableObjectCodeUpdatedError(
+  error: unknown,
+): boolean {
+  return toErrorText(error).includes(
+    CLOUDFLARE_DURABLE_OBJECT_CODE_UPDATED_ERROR,
+  );
+}
+
+export function normalizePlayRunFailure(
+  error: unknown,
+): PlayRunFailureDetails {
+  const cause = toErrorText(error);
+  if (isCloudflareDurableObjectCodeUpdatedError(cause)) {
+    return {
+      code: 'PLATFORM_DEPLOY_INTERRUPTED',
+      phase: 'runtime',
+      message: PLATFORM_DEPLOY_INTERRUPTED_MESSAGE,
+      retryable: true,
+      cause: CLOUDFLARE_DURABLE_OBJECT_CODE_UPDATED_ERROR,
+    };
+  }
+  return {
+    code: 'RUN_FAILED',
+    phase: 'runtime',
+    message: cause,
+    retryable: null,
+  };
+}