deepline 0.1.33 → 0.1.36

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';
+      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. */

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.36";
+export const SDK_API_CONTRACT = "2026-05-v2-tool-response";

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,
+  };
+}

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

@@ -38,6 +38,64 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
 
+export type V2ToolExecuteOutput = {
+  raw: unknown;
+  meta?: Record<string, unknown>;
+};
+
+export function parseV2ToolExecuteOutput(
+  data: Record<string, unknown>,
+): V2ToolExecuteOutput | null {
+  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(
+  data: Record<string, unknown>,
+): { output?: V2ToolExecuteOutput; result: unknown } {
+  const output = parseV2ToolExecuteOutput(data);
+  if (!output) {
+    return { result: data.result ?? data };
+  }
+  return {
+    output,
+    result: {
+      data: output.raw,
+      ...(output.meta ? { meta: output.meta } : {}),
+    },
+  };
+}
+
+export function toV2RawToolOutputPath(path: string): string {
+  const normalized = String(path || '')
+    .trim()
+    .replace(/^\./, '');
+  if (!normalized) return 'toolResponse.raw';
+  if (
+    normalized === 'toolResponse.raw' ||
+    normalized.startsWith('toolResponse.raw.')
+  ) {
+    return normalized;
+  }
+  const rawPath = normalized
+    .replace(/^result\.data\.?/, '')
+    .replace(/^result\.?/, '')
+    .replace(/^data\.?/, '')
+    .replace(/^\./, '');
+  return rawPath
+    ? `toolResponse.raw.${rawPath}`
+    : 'toolResponse.raw';
+}
+
 function isMeaningfulValue(value: unknown): boolean {
   if (value == null) return false;
   if (typeof value === 'string') return value.trim().length > 0;
@@ -123,7 +181,37 @@ function normalizeResultPath(path: string): string {
     .trim()
     .replace(/^\./, '');
   if (!trimmed) return '';
-  return trimmed.startsWith('result.') ? trimmed : `result.${trimmed}`;
+  return toV2RawToolOutputPath(trimmed);
+}
+
+function toV2RawToolOutputPathPreservingProviderData(path: string): string {
+  const normalized = String(path || '')
+    .trim()
+    .replace(/^\./, '');
+  if (!normalized) return 'toolResponse.raw';
+  if (
+    normalized === 'toolResponse.raw' ||
+    normalized.startsWith('toolResponse.raw.')
+  ) {
+    return normalized;
+  }
+  const rawPath = normalized
+    .replace(/^result\.?/, '')
+    .replace(/^\./, '');
+  return rawPath
+    ? `toolResponse.raw.${rawPath}`
+    : 'toolResponse.raw';
+}
+
+function candidateResultPaths(path: string): string[] {
+  const candidates = [
+    normalizeResultPath(path),
+    toV2RawToolOutputPathPreservingProviderData(path),
+  ];
+  return candidates.filter(
+    (candidate, index, all) =>
+      candidate.length > 0 && all.indexOf(candidate) === index,
+  );
 }
 
 function normalizeRelativePath(path: string): string {
@@ -184,10 +272,10 @@ function findFirstTargetByPath(
   paths: readonly string[] | undefined,
 ): ToolResultTargetMetadata | null {
   for (const path of paths ?? []) {
-    const normalizedPath = normalizeResultPath(path);
-    if (!normalizedPath) continue;
-    const match = getFirstMeaningfulValueAtPath(result, normalizedPath);
-    if (match) return match;
+    for (const candidate of candidateResultPaths(path)) {
+      const match = getFirstMeaningfulValueAtPath(result, candidate);
+      if (match) return match;
+    }
   }
   return null;
 }
@@ -244,8 +332,7 @@ function resolveListRows(
     const path = normalizeResultPath(rawPath);
     if (!path) continue;
     const candidates = [
-      path,
-      path.replace(/^result\./, 'result.data.'),
+      ...candidateResultPaths(rawPath),
     ].filter(
       (candidate, index, all) =>
         candidate && all.indexOf(candidate) === index,
@@ -303,29 +390,31 @@ function deriveListKeys(input: {
         .trim()
         .replace(/^\./, '');
       if (!path) continue;
-      const resultPath = normalizeResultPath(path);
-      const directPrefix = `${listPrefix}.`;
-      if (resultPath.startsWith(directPrefix)) {
-        keys[target] = resultPath
-          .slice(directPrefix.length)
-          .replace(/^\[\d+\]\.?/, '');
-        break;
-      }
-      const indexedPrefix = `${listPrefix}[0].`;
-      if (resultPath.startsWith(indexedPrefix)) {
-        keys[target] = resultPath.slice(indexedPrefix.length);
-        break;
-      }
-      const wildcardPrefix = `${listPrefix}[*].`;
-      if (resultPath.startsWith(wildcardPrefix)) {
-        keys[target] = resultPath.slice(wildcardPrefix.length);
-        break;
-      }
-      const dottedIndexPrefix = `${listPrefix}.0.`;
-      if (resultPath.startsWith(dottedIndexPrefix)) {
-        keys[target] = resultPath.slice(dottedIndexPrefix.length);
-        break;
+      for (const resultPath of candidateResultPaths(path)) {
+        const directPrefix = `${listPrefix}.`;
+        if (resultPath.startsWith(directPrefix)) {
+          keys[target] = resultPath
+            .slice(directPrefix.length)
+            .replace(/^\[\d+\]\.?/, '');
+          break;
+        }
+        const indexedPrefix = `${listPrefix}[0].`;
+        if (resultPath.startsWith(indexedPrefix)) {
+          keys[target] = resultPath.slice(indexedPrefix.length);
+          break;
+        }
+        const wildcardPrefix = `${listPrefix}[*].`;
+        if (resultPath.startsWith(wildcardPrefix)) {
+          keys[target] = resultPath.slice(wildcardPrefix.length);
+          break;
+        }
+        const dottedIndexPrefix = `${listPrefix}.0.`;
+        if (resultPath.startsWith(dottedIndexPrefix)) {
+          keys[target] = resultPath.slice(dottedIndexPrefix.length);
+          break;
+        }
       }
+      if (keys[target]) break;
     }
   }
   if (Object.keys(keys).length === 0 && input.rows[0]) {
@@ -433,12 +522,19 @@ 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 = { result };
+  const resultRoot = {
+    toolResponse: {
+      raw: result.data,
+      ...(result.meta ? { meta: result.meta } : {}),
+    },
+  };
   const targets = buildTargets(
     resultRoot,
     input.metadata.resultIdentityGetters,
@@ -450,12 +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,
-    result,
-    extracted: buildExtractedAccessors(targets),
-    lists: buildListAccessors(resultRoot, lists),
+    ...(input.jobId ? { job_id: input.jobId } : {}),
+    ...(input.meta ? { meta: input.meta } : {}),
+    toolResponse,
+    extractedValues,
+    extractedLists,
   } as ToolExecuteResult<TResult>;
+  Object.defineProperties(wrapper, {
+    toolOutput: {
+      value: toolResponse,
+      enumerable: false,
+    },
+  });
   Object.defineProperty(wrapper, '_metadata', {
     value: metadata,
     enumerable: false,
@@ -471,7 +581,8 @@ export function isToolExecuteResult(
     typeof value.status === 'string' &&
     '_metadata' in value &&
     isRecord(value._metadata) &&
-    'result' in value
+    'toolResponse' in value &&
+    'toolOutput' in value
   );
 }
 
@@ -481,7 +592,14 @@ export function cloneToolExecuteResultWithExecution<TResult>(
 ): ToolExecuteResult<TResult> {
   return createToolExecuteResult<TResult>({
     status: value.status,
-    result: value.result as TResult,
+    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.toolResponse.raw,
+      ...(value.toolResponse.meta ? { meta: value.toolResponse.meta } : {}),
+    } as TResult,
     metadata: {
       toolId: value._metadata.toolId,
       resultIdentityGetters: Object.fromEntries(
@@ -500,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.33",
+  "version": "0.1.36",
   "description": "Deepline SDK + CLI — B2B data enrichment powered by durable cloud execution",
   "license": "MIT",
   "repository": {