deepline 0.1.35 → 0.1.36

package/dist/repo/apps/play-runner-workers/src/runtime/receipts.ts

@@ -0,0 +1,138 @@
+export type RuntimeReceiptStatus =
+  | 'pending'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'skipped';
+
+export type WorkerRuntimeReceipt = {
+  key: string;
+  status: RuntimeReceiptStatus;
+  output?: unknown;
+  error?: string;
+  runId?: string | null;
+};
+
+export type WorkerRuntimeReceiptResponse = {
+  receipt?: WorkerRuntimeReceipt | null;
+};
+
+export type WorkerRuntimeReceiptAction =
+  | {
+      action: 'get_runtime_step_receipt';
+      playName: string;
+      runId: string;
+      key: string;
+    }
+  | {
+      action: 'claim_runtime_step_receipt';
+      playName: string;
+      runId: string;
+      key: string;
+    }
+  | {
+      action: 'complete_runtime_step_receipt';
+      playName: string;
+      runId: string;
+      key: string;
+      output: unknown;
+    }
+  | {
+      action: 'fail_runtime_step_receipt';
+      playName: string;
+      runId: string;
+      key: string;
+      error: string;
+    };
+
+type RuntimeReceiptContext = {
+  baseUrl: string;
+  executorToken: string;
+  playName: string;
+  runId: string;
+  key: string;
+  postRuntimeApi: (
+    baseUrl: string,
+    executorToken: string,
+    body: WorkerRuntimeReceiptAction,
+  ) => Promise<WorkerRuntimeReceiptResponse>;
+};
+
+function scopedReceiptKey(input: {
+  playName: string;
+  runId: string;
+  key: string;
+}): string {
+  return `run:${input.runId}:play:${input.playName}:${input.key}`;
+}
+
+function receiptOutput<T>(receipt: WorkerRuntimeReceipt): T {
+  return receipt.output as T;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export async function runWorkerRuntimeReceiptBoundary<T>(
+  input: RuntimeReceiptContext & {
+    execute: () => Promise<T> | T;
+  },
+): Promise<T> {
+  const key = scopedReceiptKey(input);
+  const existing = await input.postRuntimeApi(input.baseUrl, input.executorToken, {
+    action: 'get_runtime_step_receipt',
+    playName: input.playName,
+    runId: input.runId,
+    key,
+  });
+  if (
+    existing.receipt?.status === 'completed' ||
+    existing.receipt?.status === 'skipped'
+  ) {
+    return receiptOutput<T>(existing.receipt);
+  }
+
+  const claimed = await input.postRuntimeApi(input.baseUrl, input.executorToken, {
+    action: 'claim_runtime_step_receipt',
+    playName: input.playName,
+    runId: input.runId,
+    key,
+  });
+  if (!claimed.receipt) {
+    if (
+      existing.receipt?.status === 'running' &&
+      existing.receipt.runId !== input.runId
+    ) {
+      throw new Error(
+        `Runtime receipt ${key} is already running for run ${existing.receipt.runId ?? 'unknown'}.`,
+      );
+    }
+    if (existing.receipt?.status === 'failed') {
+      throw new Error(
+        `Runtime receipt ${key} is failed and could not be claimed: ${existing.receipt.error ?? 'unknown error'}`,
+      );
+    }
+  }
+
+  try {
+    const output = await input.execute();
+    await input.postRuntimeApi(input.baseUrl, input.executorToken, {
+      action: 'complete_runtime_step_receipt',
+      playName: input.playName,
+      runId: input.runId,
+      key,
+      output,
+    });
+    return output;
+  } catch (error) {
+    await input.postRuntimeApi(input.baseUrl, input.executorToken, {
+      action: 'fail_runtime_step_receipt',
+      playName: input.playName,
+      runId: input.runId,
+      key,
+      error: errorMessage(error),
+    });
+    throw error;
+  }
+}

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

@@ -68,7 +68,7 @@ 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-execution-result';
+const V2_EXECUTE_RESPONSE_CONTRACT = 'v2-tool-response';
 const COMPILE_MANIFEST_RETRY_DELAYS_MS = [250, 1_000];
 
 function sleep(ms: number): Promise<void> {
@@ -97,15 +97,13 @@ type ExecuteToolRawOptions = {
 export type ToolExecution<TData = unknown, TMeta = Record<string, unknown>> = {
   status: string;
   job_id?: string;
-  toolExecutionResult: {
-    toolOutput: {
-      raw: TData;
-      meta?: TMeta;
-    };
-    extractedLists?: Record<string, unknown>;
-    extractedValues?: Record<string, unknown>;
-    meta?: Record<string, unknown>;
+  meta?: Record<string, unknown>;
+  toolResponse: {
+    raw: TData;
+    meta?: TMeta;
   };
+  extractedLists?: Record<string, unknown>;
+  extractedValues?: Record<string, unknown>;
   billing?: Record<string, unknown>;
   [key: string]: unknown;
 };
@@ -559,8 +557,8 @@ export class DeeplineClient {
   /**
    * Execute a tool and return the standard execution envelope.
    *
-   * The `toolExecutionResult.toolOutput.raw` field contains the raw tool output.
-   * `toolExecutionResult.toolOutput.meta` contains tool/provider metadata.
+   * 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 envelope.
    */

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

@@ -11,7 +11,7 @@
  *
  * // Execute a tool
  * const result = await deepline.tools.execute('test_company_search', { domain: 'stripe.com' });
- * const company = result.toolOutput.raw;
+ * const company = result.toolResponse.raw;
  *
  * // Run a named play
  * const job = await deepline.play('email-waterfall').run({ domain: 'stripe.com' });

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

@@ -926,7 +926,7 @@ export class DeeplineContext {
    * 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;
+   * const company = companyLookup.toolResponse.raw;
    * ```
    */
   get tools() {
@@ -1096,8 +1096,8 @@ function toolExecutionEnvelopeToResult(
   fallbackToolId: string,
   response: ToolExecution,
 ): ToolExecuteResult {
-  const raw = response.toolExecutionResult?.toolOutput?.raw ?? null;
-  const meta = response.toolExecutionResult?.toolOutput?.meta;
+  const raw = response.toolResponse?.raw ?? null;
+  const meta = response.toolResponse?.meta;
   const metadata = isRecord(response._metadata)
     ? response._metadata.tool
     : null;
@@ -1105,6 +1105,7 @@ function toolExecutionEnvelopeToResult(
 
   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 } : {}),
@@ -1125,6 +1126,7 @@ function toolExecutionEnvelopeToResult(
       cached: false,
       source: 'live',
     },
+    meta: isRecord(response.meta) ? response.meta : undefined,
   });
 }
 

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

@@ -109,21 +109,17 @@ function normalizeRows(value: unknown): Array<Record<string, unknown>> | null {
 
 /**
  * Generate candidate root objects to search for lists.
- * Tries: raw payload → V2 toolExecutionResult.toolOutput.raw → legacy payload.output.body → legacy payload.result → legacy 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.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.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)) {

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

@@ -108,9 +108,9 @@ export interface ToolDefinition {
     execute?: string;
     toolExecutionResult?: {
       type?: 'ToolExecutionResult';
-      toolOutput?: {
-        raw?: string | { path?: string; schema?: Record<string, unknown> };
-        meta?: string | { path?: string; schema?: Record<string, unknown> };
+      toolResponse?: {
+        raw?: string;
+        meta?: string;
       };
       meta?: string;
       extractedLists?: Array<{

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

@@ -1,2 +1,2 @@
-export const SDK_VERSION = "0.1.35";
-export const SDK_API_CONTRACT = "2026-05-v2-tool-result-contract";
+export const SDK_VERSION = "0.1.36";
+export const SDK_API_CONTRACT = "2026-05-v2-tool-response";

package/dist/repo/shared_libs/play-runtime/tool-result.ts

@@ -46,17 +46,17 @@ export type V2ToolExecuteOutput = {
 export function parseV2ToolExecuteOutput(
   data: Record<string, unknown>,
 ): V2ToolExecuteOutput | null {
-  const toolExecutionResult = data.toolExecutionResult;
-  if (!isRecord(toolExecutionResult)) return null;
-  const toolOutput = toolExecutionResult.toolOutput;
-  if (!isRecord(toolOutput)) return null;
-  const meta = isRecord(toolOutput.meta) ? toolOutput.meta : undefined;
-  return {
-    raw: Object.prototype.hasOwnProperty.call(toolOutput, 'raw')
-      ? toolOutput.raw
-      : null,
-    ...(meta ? { meta } : {}),
-  };
+  const toolResponse = data.toolResponse;
+  if (isRecord(toolResponse)) {
+    const meta = isRecord(toolResponse.meta) ? toolResponse.meta : undefined;
+    return {
+      raw: Object.prototype.hasOwnProperty.call(toolResponse, 'raw')
+        ? toolResponse.raw
+        : null,
+      ...(meta ? { meta } : {}),
+    };
+  }
+  return null;
 }
 
 export function adaptV2ExecuteResponseToToolResult(
@@ -79,10 +79,10 @@ export function toV2RawToolOutputPath(path: string): string {
   const normalized = String(path || '')
     .trim()
     .replace(/^\./, '');
-  if (!normalized) return 'toolExecutionResult.toolOutput.raw';
+  if (!normalized) return 'toolResponse.raw';
   if (
-    normalized === 'toolExecutionResult.toolOutput.raw' ||
-    normalized.startsWith('toolExecutionResult.toolOutput.raw.')
+    normalized === 'toolResponse.raw' ||
+    normalized.startsWith('toolResponse.raw.')
   ) {
     return normalized;
   }
@@ -92,8 +92,8 @@ export function toV2RawToolOutputPath(path: string): string {
     .replace(/^data\.?/, '')
     .replace(/^\./, '');
   return rawPath
-    ? `toolExecutionResult.toolOutput.raw.${rawPath}`
-    : 'toolExecutionResult.toolOutput.raw';
+    ? `toolResponse.raw.${rawPath}`
+    : 'toolResponse.raw';
 }
 
 function isMeaningfulValue(value: unknown): boolean {
@@ -188,10 +188,10 @@ function toV2RawToolOutputPathPreservingProviderData(path: string): string {
   const normalized = String(path || '')
     .trim()
     .replace(/^\./, '');
-  if (!normalized) return 'toolExecutionResult.toolOutput.raw';
+  if (!normalized) return 'toolResponse.raw';
   if (
-    normalized === 'toolExecutionResult.toolOutput.raw' ||
-    normalized.startsWith('toolExecutionResult.toolOutput.raw.')
+    normalized === 'toolResponse.raw' ||
+    normalized.startsWith('toolResponse.raw.')
   ) {
     return normalized;
   }
@@ -199,8 +199,8 @@ function toV2RawToolOutputPathPreservingProviderData(path: string): string {
     .replace(/^result\.?/, '')
     .replace(/^\./, '');
   return rawPath
-    ? `toolExecutionResult.toolOutput.raw.${rawPath}`
-    : 'toolExecutionResult.toolOutput.raw';
+    ? `toolResponse.raw.${rawPath}`
+    : 'toolResponse.raw';
 }
 
 function candidateResultPaths(path: string): string[] {
@@ -522,17 +522,17 @@ function buildListAccessors(
 
 export function createToolExecuteResult<TResult = unknown>(input: {
   status: string;
+  jobId?: string;
   result: TResult;
   metadata: ToolResultMetadataInput;
   execution: ToolResultExecutionMetadata;
+  meta?: Record<string, unknown>;
 }): ToolExecuteResult<TResult> {
   const result = toResultEnvelope(input.result);
   const resultRoot = {
-    toolExecutionResult: {
-      toolOutput: {
-        raw: result.data,
-        ...(result.meta ? { meta: result.meta } : {}),
-      },
+    toolResponse: {
+      raw: result.data,
+      ...(result.meta ? { meta: result.meta } : {}),
     },
   };
   const targets = buildTargets(
@@ -546,16 +546,26 @@ export function createToolExecuteResult<TResult = unknown>(input: {
     targets,
     lists,
   };
+  const toolResponse = {
+    raw: result.data,
+    ...(result.meta ? { meta: result.meta } : {}),
+  };
+  const extractedValues = buildExtractedAccessors(targets);
+  const extractedLists = buildListAccessors(resultRoot, lists);
   const wrapper = {
     status: input.status,
+    ...(input.jobId ? { job_id: input.jobId } : {}),
+    ...(input.meta ? { meta: input.meta } : {}),
+    toolResponse,
+    extractedValues,
+    extractedLists,
+  } as ToolExecuteResult<TResult>;
+  Object.defineProperties(wrapper, {
     toolOutput: {
-      raw: result.data,
-      ...(result.meta ? { meta: result.meta } : {}),
+      value: toolResponse,
+      enumerable: false,
     },
-    meta: input.execution,
-    extractedValues: buildExtractedAccessors(targets),
-    extractedLists: buildListAccessors(resultRoot, lists),
-  } as ToolExecuteResult<TResult>;
+  });
   Object.defineProperty(wrapper, '_metadata', {
     value: metadata,
     enumerable: false,
@@ -571,6 +581,7 @@ export function isToolExecuteResult(
     typeof value.status === 'string' &&
     '_metadata' in value &&
     isRecord(value._metadata) &&
+    'toolResponse' in value &&
     'toolOutput' in value
   );
 }
@@ -581,9 +592,13 @@ export function cloneToolExecuteResultWithExecution<TResult>(
 ): ToolExecuteResult<TResult> {
   return createToolExecuteResult<TResult>({
     status: value.status,
+    jobId:
+      typeof (value as unknown as { job_id?: unknown }).job_id === 'string'
+        ? (value as unknown as { job_id: string }).job_id
+        : undefined,
     result: {
-      data: value.toolOutput.raw,
-      ...(value.toolOutput.meta ? { meta: value.toolOutput.meta } : {}),
+      data: value.toolResponse.raw,
+      ...(value.toolResponse.meta ? { meta: value.toolResponse.meta } : {}),
     } as TResult,
     metadata: {
       toolId: value._metadata.toolId,
@@ -603,5 +618,6 @@ export function cloneToolExecuteResultWithExecution<TResult>(
       ),
     },
     execution,
+    meta: isRecord(value.meta) ? value.meta : undefined,
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepline",
-  "version": "0.1.35",
+  "version": "0.1.36",
   "description": "Deepline SDK + CLI — B2B data enrichment powered by durable cloud execution",
   "license": "MIT",
   "repository": {