deepline 0.1.301 → 0.1.303

package/dist/bundling-sources/shared_libs/play-runtime/tool-execute-retry-policy.ts

@@ -3,6 +3,7 @@ import {
   normalizeToolHttpErrorMessage,
   type ToolHttpError,
 } from './tool-http-errors';
+import type { ToolExecutionErrorSchemaVersion } from '../tool-execution-error';
 
 export const TOOL_EXECUTE_TRANSIENT_HTTP_MAX_ATTEMPTS = 2;
 // A provider may need to finish the original request before it can replay the
@@ -296,6 +297,7 @@ export function classifyToolExecuteHttpFailure(input: {
   status: number;
   attempt: number;
   bodyText: string;
+  schemaVersion?: ToolExecutionErrorSchemaVersion;
   retryAfterHeader?: string | null;
   transientHttpRetrySafe?: boolean;
   providerLatencyMs?: number;
@@ -318,12 +320,20 @@ export function classifyToolExecuteHttpFailure(input: {
     hasRetryAfterHeader,
     transientHttpRetrySafe,
   });
+  const retryAfterMs = parseToolExecuteRetryAfterMs(
+    input.retryAfterHeader,
+    input.nowMs,
+  );
   const error = normalizeToolHttpErrorMessage({
     toolId: input.toolId,
     status: input.status,
     attempt: input.attempt,
     maxAttempts: initialRetryDecision.attemptCap,
     bodyText: input.bodyText,
+    schemaVersion: input.schemaVersion,
+    retryable: initialRetryDecision.retryable,
+    retryAfterMs:
+      input.status === 429 && hasRetryAfterHeader ? retryAfterMs : null,
   });
   if (
     typeof input.providerLatencyMs === 'number' &&
@@ -355,10 +365,6 @@ export function classifyToolExecuteHttpFailure(input: {
   ) {
     error.receiptFailureKind = 'repairable';
   }
-  const retryAfterMs = parseToolExecuteRetryAfterMs(
-    input.retryAfterHeader,
-    input.nowMs,
-  );
   const retryDelayMs =
     input.status === 429
       ? Math.min(
@@ -369,14 +375,14 @@ export function classifyToolExecuteHttpFailure(input: {
           ),
         )
       : retryDecision.reason === 'idempotency_in_progress' &&
-            !hasRetryAfterHeader
-        ? idempotencyInProgressRetryDelayMs(input.attempt)
-        : retryDecision.reason === 'gateway_invocation_in_progress' &&
           !hasRetryAfterHeader
         ? idempotencyInProgressRetryDelayMs(input.attempt)
-        : retryAfterMs > 0
-          ? Math.min(TOOL_EXECUTE_RETRY_DELAY_MAX_MS, retryAfterMs)
-          : TOOL_EXECUTE_RETRY_DELAY_FALLBACK_MS;
+        : retryDecision.reason === 'gateway_invocation_in_progress' &&
+            !hasRetryAfterHeader
+          ? idempotencyInProgressRetryDelayMs(input.attempt)
+          : retryAfterMs > 0
+            ? Math.min(TOOL_EXECUTE_RETRY_DELAY_MAX_MS, retryAfterMs)
+            : TOOL_EXECUTE_RETRY_DELAY_FALLBACK_MS;
   return {
     ...retryDecision,
     error,
@@ -395,7 +401,6 @@ export function classifyToolExecuteHttpFailure(input: {
           : TOOL_EXECUTE_BARE_RATE_LIMIT_BACKPRESSURE_MS
         : null,
     chargeRetryBudget:
-      shouldRetry &&
-      retryDecision.reason !== 'gateway_invocation_in_progress',
+      shouldRetry && retryDecision.reason !== 'gateway_invocation_in_progress',
   };
 }

package/dist/bundling-sources/shared_libs/play-runtime/tool-http-errors.ts

@@ -1,5 +1,50 @@
 import type { WorkReceiptFailureKind } from './work-receipts';
+import {
+  LEGACY_TOOL_EXECUTION_ERROR_SCHEMA_VERSION,
+  ToolExecutionError,
+  deserializeToolExecutionFailure,
+  isProviderTransientFailure,
+  normalizeToolExecutionCategory,
+  normalizeToolExecutionOrigin,
+  type ToolExecutionErrorSchemaVersion,
+  type ToolExecutionErrorOptions,
+} from '../tool-execution-error';
 
+const TOOL_HTTP_ERROR_BRAND = Symbol.for('deepline.tool-http-error.v1');
+
+type ToolHttpErrorConstructorInput = {
+  message: string;
+  billing: Record<string, unknown> | null;
+  status: number;
+  receiptFailureKind: WorkReceiptFailureKind;
+  options: Partial<ToolExecutionErrorOptions>;
+};
+
+function applyToolHttpErrorFields(
+  error: {
+    name: string;
+    billing: Record<string, unknown> | null;
+    status: number;
+    receiptFailureKind: WorkReceiptFailureKind;
+  },
+  input: ToolHttpErrorConstructorInput,
+): void {
+  error.name = 'ToolHttpError';
+  error.billing = input.billing;
+  error.status = input.status;
+  error.receiptFailureKind = input.receiptFailureKind;
+  Object.defineProperty(error, TOOL_HTTP_ERROR_BRAND, {
+    configurable: false,
+    enumerable: false,
+    writable: false,
+    value: true,
+  });
+}
+
+/**
+ * Historical play-runtime HTTP error. Existing artifacts must keep this exact
+ * Error prototype; typed errors are an explicit artifact-contract opt-in.
+ */
 export class ToolHttpError extends Error {
   readonly billing: Record<string, unknown> | null;
   /** HTTP status of the failed tool-execute response (e.g. 429, 502). */
@@ -11,15 +56,89 @@ export class ToolHttpError extends Error {
     billing: Record<string, unknown> | null,
     status: number,
     receiptFailureKind: WorkReceiptFailureKind = 'terminal',
+    _options: Partial<ToolExecutionErrorOptions> = {},
   ) {
     super(message);
-    this.name = 'ToolHttpError';
     this.billing = billing;
     this.status = status;
     this.receiptFailureKind = receiptFailureKind;
+    applyToolHttpErrorFields(this, {
+      message,
+      billing,
+      status,
+      receiptFailureKind,
+      options: _options,
+    });
+  }
+
+  static [Symbol.hasInstance](value: unknown): boolean {
+    return Boolean(
+      value &&
+      typeof value === 'object' &&
+      (value as Record<symbol, unknown>)[TOOL_HTTP_ERROR_BRAND] === true,
+    );
   }
 }
 
+class StructuredToolHttpError extends ToolExecutionError {
+  readonly billing: Record<string, unknown> | null;
+  readonly status: number;
+  receiptFailureKind: WorkReceiptFailureKind;
+
+  constructor(input: ToolHttpErrorConstructorInput) {
+    super(input.message, {
+      toolId: input.options.toolId ?? 'unknown_tool',
+      provider: input.options.provider ?? null,
+      operation: input.options.operation ?? null,
+      code: input.options.code ?? null,
+      origin: input.options.origin ?? 'unknown',
+      category: input.options.category ?? 'unknown',
+      retryable: input.options.retryable === true,
+      statusCode:
+        input.options.statusCode === undefined
+          ? input.status
+          : input.options.statusCode,
+      requestId: input.options.requestId ?? null,
+      retryAfterMs: input.options.retryAfterMs ?? null,
+      networkKind: input.options.networkKind ?? null,
+      networkScope: input.options.networkScope ?? null,
+    });
+    this.billing = input.billing;
+    this.status = input.status;
+    this.receiptFailureKind = input.receiptFailureKind;
+    applyToolHttpErrorFields(this, input);
+    this.name = isProviderTransientFailure(this)
+      ? 'ProviderTransientError'
+      : 'ToolExecutionError';
+  }
+}
+
+export function createToolHttpError(
+  schemaVersion: ToolExecutionErrorSchemaVersion,
+  message: string,
+  billing: Record<string, unknown> | null,
+  status: number,
+  receiptFailureKind: WorkReceiptFailureKind = 'terminal',
+  options: Partial<ToolExecutionErrorOptions> = {},
+): ToolHttpError {
+  if (schemaVersion === LEGACY_TOOL_EXECUTION_ERROR_SCHEMA_VERSION) {
+    return new ToolHttpError(
+      message,
+      billing,
+      status,
+      receiptFailureKind,
+      options,
+    );
+  }
+  return new StructuredToolHttpError({
+    message,
+    billing,
+    status,
+    receiptFailureKind,
+    options,
+  }) as ToolHttpError;
+}
+
 function formatCreditAmount(value: unknown): string {
   if (typeof value !== 'number' || !Number.isFinite(value)) {
     return String(value ?? '-');
@@ -222,7 +341,12 @@ export function normalizeToolHttpErrorMessage(input: {
   attempt: number;
   maxAttempts: number;
   bodyText: string;
+  retryable?: boolean;
+  retryAfterMs?: number | null;
+  schemaVersion?: ToolExecutionErrorSchemaVersion;
 }): ToolHttpError {
+  const schemaVersion =
+    input.schemaVersion ?? LEGACY_TOOL_EXECUTION_ERROR_SCHEMA_VERSION;
   let parsed: Record<string, unknown> | null = null;
   try {
     const candidate = JSON.parse(input.bodyText);
@@ -230,9 +354,64 @@ export function normalizeToolHttpErrorMessage(input: {
   } catch {
     parsed = null;
   }
+  const serializedFailure = parsed?.tool_error;
+  const hydratedFailure = deserializeToolExecutionFailure(
+    '',
+    serializedFailure,
+    schemaVersion,
+  );
+  const provider =
+    getStringField(parsed, 'provider') ??
+    hydratedFailure?.provider ??
+    input.toolId.split(/[._:./-]+/)[0]?.trim() ??
+    null;
+  const operation =
+    getStringField(parsed, 'operation') ??
+    hydratedFailure?.operation ??
+    input.toolId;
+  const code = getStringField(parsed, 'code') ?? hydratedFailure?.code ?? null;
+  const rawOrigin =
+    getStringField(parsed, 'failure_origin') ?? hydratedFailure?.origin;
+  const rawCategory =
+    getStringField(parsed, 'error_category') ?? hydratedFailure?.category;
+  const origin = normalizeToolExecutionOrigin(rawOrigin, {
+    provider,
+    operation,
+  });
+  const category = normalizeToolExecutionCategory(rawCategory);
+  const trustworthy = origin !== 'unknown' && category !== 'unknown';
+  const publicOptions: Partial<ToolExecutionErrorOptions> = {
+    toolId: input.toolId,
+    provider,
+    operation,
+    code,
+    origin,
+    category,
+    retryable: trustworthy
+      ? (hydratedFailure?.retryable ?? input.retryable === true)
+      : false,
+    statusCode: input.status,
+    requestId:
+      getStringField(parsed, 'request_id') ??
+      getStringField(parsed, 'requestId') ??
+      hydratedFailure?.requestId ??
+      null,
+    retryAfterMs: hydratedFailure?.retryAfterMs ?? input.retryAfterMs ?? null,
+    networkKind:
+      hydratedFailure?.networkKind ??
+      (category === 'network' && code?.toUpperCase().includes('TIMEOUT')
+        ? 'timeout'
+        : null),
+    networkScope:
+      hydratedFailure?.networkScope ??
+      (origin === 'provider' && category === 'network'
+        ? 'deepline_to_provider'
+        : null),
+  };
   const billing = getObjectField(parsed, 'billing');
   if (isInsufficientCreditsBilling(billing)) {
-    return new ToolHttpError(
+    return createToolHttpError(
+      schemaVersion,
       `tool ${input.toolId} ${input.status} attempt ${input.attempt}/${input.maxAttempts}: ${formatInsufficientCreditsMessage(
         {
           billing,
@@ -241,6 +420,14 @@ export function normalizeToolHttpErrorMessage(input: {
       )}`,
       billing,
       input.status,
+      'terminal',
+      {
+        ...publicOptions,
+        origin: 'deepline',
+        category: 'billing',
+        code: publicOptions.code ?? 'INSUFFICIENT_CREDITS',
+        retryable: false,
+      },
     );
   }
   const hardBillingPayload = isHardBillingFailurePayload(billing)
@@ -249,7 +436,8 @@ export function normalizeToolHttpErrorMessage(input: {
       ? normalizeHardBillingPayload(parsed)
       : null;
   if (hardBillingPayload) {
-    return new ToolHttpError(
+    return createToolHttpError(
+      schemaVersion,
       formatHardBillingFailureMessage({
         billing: hardBillingPayload,
         toolId: input.toolId,
@@ -259,9 +447,17 @@ export function normalizeToolHttpErrorMessage(input: {
       }),
       hardBillingPayload,
       input.status,
+      'terminal',
+      {
+        ...publicOptions,
+        origin: 'deepline',
+        category: 'billing',
+        retryable: false,
+      },
     );
   }
-  return new ToolHttpError(
+  return createToolHttpError(
+    schemaVersion,
     `tool ${input.toolId} ${input.status} attempt ${input.attempt}/${input.maxAttempts}: ${formatPublicToolErrorPayload(
       {
         parsed,
@@ -271,6 +467,7 @@ export function normalizeToolHttpErrorMessage(input: {
     billing,
     input.status,
     receiptFailureKindForToolErrorPayload(parsed),
+    publicOptions,
   );
 }
 
@@ -281,10 +478,18 @@ export function extractErrorBilling(
 }
 
 export function isHardBillingToolHttpError(error: unknown): boolean {
-  return (
+  if (
     error instanceof ToolHttpError &&
     (isInsufficientCreditsBilling(error.billing) ||
       isHardBillingFailurePayload(error.billing))
+  ) {
+    return true;
+  }
+  return (
+    error instanceof ToolExecutionError &&
+    error.origin === 'deepline' &&
+    error.category === 'billing' &&
+    error.code !== 'BILLING_UNAVAILABLE'
   );
 }
 

package/dist/bundling-sources/shared_libs/play-runtime/tool-result-paths.ts

@@ -0,0 +1,15 @@
+/**
+ * Derive the public semantic accessor name from a declared list path.
+ *
+ * Keep this independent from path normalization: `result.data` may resolve to
+ * `toolResponse.raw`, but its public getter remains `extractedLists.data`.
+ */
+export function listNameFromDeclaredPath(path: string): string | null {
+  return (
+    String(path || '')
+      .split('.')
+      .filter(Boolean)
+      .at(-1)
+      ?.replace(/[^A-Za-z0-9_$]/g, '') || null
+  );
+}

package/dist/bundling-sources/shared_libs/play-runtime/tool-result-types.ts

@@ -42,6 +42,8 @@ export type ToolResultMetadata = {
   execution: ToolResultExecutionMetadata;
   targets: Record<string, ToolResultTargetMetadata>;
   lists: Record<string, ToolResultListMetadata>;
+  /** Original declarations preserve semantic accessor names across replay. */
+  listExtractorPaths?: readonly string[];
   extractors?: Record<string, ToolResultExtractorDescriptor>;
 };
 
@@ -130,6 +132,8 @@ export type ToolExecuteResultBase<
         keys: Record<string, string>;
       }
     >;
+    /** Original declarations preserve semantic accessor names across replay. */
+    listExtractorPaths?: readonly string[];
   };
 };
 

package/dist/bundling-sources/shared_libs/play-runtime/tool-result.ts

@@ -47,6 +47,7 @@ import {
   type SerializedPlayDataset,
 } from '../plays/dataset';
 import { normalizeTableNamespace, sha256Hex } from '../plays/row-identity';
+import { listNameFromDeclaredPath } from './tool-result-paths';
 
 type PathSegment = string | number | '*';
 
@@ -744,43 +745,35 @@ function resolveListRows(
     { path: string; rows: Record<string, unknown>[] }
   > = {};
   for (const rawPath of listExtractorPaths ?? []) {
+    const listName = listNameFromDeclaredPath(rawPath);
+    if (!listName) continue;
     const path = normalizeResultPath(rawPath);
     if (!path) continue;
     const candidates = [...candidateResultPaths(rawPath)].filter(
       (candidate, index, all) => candidate && all.indexOf(candidate) === index,
     );
-    let resolvedPath: string | null = null;
-    let rows: Record<string, unknown>[] | null = null;
+    let resolved: { path: string; rows: Record<string, unknown>[] } | null =
+      null;
     let emptyMatch: { path: string; rows: Record<string, unknown>[] } | null =
       null;
     for (const candidate of candidates) {
-      rows = normalizeRows(getAtPath(result, candidate));
-      if (!rows) {
+      const candidateRows = normalizeRows(getAtPath(result, candidate));
+      if (!candidateRows) {
         continue;
       }
-      if (rows.length > 0) {
-        resolvedPath = candidate;
+      if (candidateRows.length > 0) {
+        resolved = { path: candidate, rows: candidateRows };
         break;
       }
-      emptyMatch ??= { path: candidate, rows };
-    }
-    if (!rows && emptyMatch) {
-      resolvedPath = emptyMatch.path;
-      rows = emptyMatch.rows;
+      emptyMatch ??= { path: candidate, rows: candidateRows };
     }
-    if (!rows) continue;
-    const storedPath = resolvedPath ?? path;
-    const name = storedPath
-      .split('.')
-      .filter(Boolean)
-      .at(-1)
-      ?.replace(/\[\d+\]$/, '');
-    const listName = name || storedPath;
+    resolved ??= emptyMatch;
+    if (!resolved) continue;
     const existing = lists[listName];
-    if (existing?.rows.length && rows.length === 0) {
+    if (existing?.rows.length && resolved.rows.length === 0) {
       continue;
     }
-    lists[listName] = { path: storedPath, rows };
+    lists[listName] = resolved;
   }
   return lists;
 }
@@ -1084,6 +1077,7 @@ export function createToolExecuteResult<TResult = unknown>(input: {
     toolId: input.metadata.toolId,
     execution: input.execution,
     targets,
+    listExtractorPaths: [...(input.metadata.listExtractorPaths ?? [])],
     ...(input.metadata.extractors
       ? { extractors: input.metadata.extractors }
       : {}),
@@ -1208,6 +1202,21 @@ export function attachToolResultListDataset<T extends Record<string, unknown>>(
     count: input.count,
     keys: input.keys ?? existing?.keys ?? {},
   };
+  const declaredPaths = result._metadata.listExtractorPaths ?? [];
+  const inputCandidates = new Set(candidateResultPaths(input.path));
+  const equivalentDeclaration = declaredPaths.find((path) =>
+    candidateResultPaths(path).some((candidate) =>
+      inputCandidates.has(candidate),
+    ),
+  );
+  result._metadata.listExtractorPaths = equivalentDeclaration
+    ? [...declaredPaths]
+    : [
+        ...declaredPaths.filter(
+          (path) => listNameFromDeclaredPath(path) !== input.name,
+        ),
+        input.path,
+      ];
   const accessor = {
     path: input.path,
     count: input.count,
@@ -1585,9 +1594,9 @@ function metadataInputFromToolExecuteResult(
         [info.path],
       ]),
     ),
-    listExtractorPaths: Object.values(value._metadata.lists).map(
-      (list) => list.path,
-    ),
+    listExtractorPaths:
+      value._metadata.listExtractorPaths ??
+      Object.values(value._metadata.lists).map((list) => list.path),
     listIdentityGetters: Object.fromEntries(
       Object.values(value._metadata.lists)
         .flatMap((list) => Object.entries(list.keys))

package/dist/bundling-sources/shared_libs/play-runtime/work-receipts.ts

@@ -1,4 +1,5 @@
 import { isReusableWorkReceiptState } from './work-receipt-state-machine';
+import type { ToolExecutionFailureV1 } from '../tool-execution-error';
 
 export type WorkReceiptFailureKind = 'terminal' | 'repairable';
 
@@ -37,6 +38,7 @@ export type WorkReceipt = {
   status: WorkReceiptStatus;
   output?: unknown;
   error?: string | null;
+  errorPayload?: ToolExecutionFailureV1 | null;
   failureKind?: WorkReceiptFailureKind | null;
   runId?: string | null;
   leaseId?: string | null;
@@ -89,6 +91,7 @@ export type WorkReceiptBatchFailCommand = {
     runId: string;
     key: string;
     error: string;
+    errorPayload?: ToolExecutionFailureV1 | null;
     failureKind?: WorkReceiptFailureKind | null;
     leaseId?: string | null;
     runAttempt?: number | null;
@@ -161,6 +164,7 @@ export type WorkReceiptStore = {
   failReceipt(
     input: WorkReceiptCommand & {
       error: string;
+      errorPayload?: ToolExecutionFailureV1 | null;
       failureKind?: WorkReceiptFailureKind | null;
     },
   ): Promise<WorkReceipt | null>;

package/dist/bundling-sources/shared_libs/plays/artifact-contract-version.ts

@@ -0,0 +1,6 @@
+/**
+ * Immutable Play artifact ABI version shared by bundling and SDK release
+ * policy. Keep this module dependency-free: shared Play code must not import
+ * the SDK release manifest or create a package cycle.
+ */
+export const CURRENT_PLAY_ARTIFACT_CONTRACT_VERSION = 2 as const;

package/dist/bundling-sources/shared_libs/plays/artifact-types.ts

@@ -1,3 +1,5 @@
+import type { ToolExecutionErrorSchemaVersion } from '../tool-execution-error';
+
 export type PlayPackageImport = {
   name: string;
   version: string | null;
@@ -21,6 +23,8 @@ export type PlayArtifactCompatibility = {
   minRunnerVersion: number;
   runtimeFeatures: PlayRuntimeFeature[];
   runtimeBackend?: string | null;
+  /** Missing preserves the legacy schema used before this field existed. */
+  toolErrorSchemaVersion?: ToolExecutionErrorSchemaVersion;
 };
 
 /** The only executable Play artifact contract. */