deepline 0.1.301 → 0.1.303

package/dist/index.js

@@ -52,10 +52,13 @@ __export(src_exports, {
   PLAY_BOOTSTRAP_STAGE_KINDS: () => PLAY_BOOTSTRAP_STAGE_KINDS,
   PLAY_BOOTSTRAP_TEMPLATES: () => PLAY_BOOTSTRAP_TEMPLATES,
   PROD_URL: () => PROD_URL,
+  ProviderTransientError: () => ProviderTransientError,
   RateLimitError: () => RateLimitError,
   RunObserveTransportUnavailableError: () => RunObserveTransportUnavailableError,
   SDK_API_CONTRACT: () => SDK_API_CONTRACT,
   SDK_VERSION: () => SDK_VERSION,
+  ToolExecutionError: () => ToolExecutionError,
+  ToolRateLimitError: () => ToolRateLimitError,
   defineInput: () => defineInput,
   defineMonitor: () => defineMonitor,
   definePlay: () => definePlay,
@@ -82,20 +85,291 @@ var import_node_fs = require("fs");
 var import_node_os = require("os");
 var import_node_path = require("path");
 
-// src/errors.ts
-var DeeplineError = class extends Error {
+// ../shared_libs/tool-execution-error.ts
+var DEEPLINE_ERROR_BRAND = /* @__PURE__ */ Symbol.for("deepline.error.v1");
+var TOOL_EXECUTION_ERROR_BRAND = /* @__PURE__ */ Symbol.for(
+  "deepline.tool-execution-error.v1"
+);
+var PROVIDER_TRANSIENT_ERROR_BRAND = /* @__PURE__ */ Symbol.for(
+  "deepline.provider-transient-error.v1"
+);
+var LEGACY_TOOL_EXECUTION_ERROR_SCHEMA_VERSION = 0;
+var TOOL_EXECUTION_ERROR_SCHEMA_VERSION = 1;
+var TOOL_EXECUTION_ERROR_SCHEMA_HEADER = "x-deepline-tool-error-schema";
+var MAX_IDENTIFIER_LENGTH = 200;
+var MAX_CODE_LENGTH = 160;
+function nativeInstanceOf(constructor, value) {
+  return Reflect.apply(Function.prototype[Symbol.hasInstance], constructor, [
+    value
+  ]);
+}
+function hasBrand(value, brand) {
+  return typeof value === "object" && value !== null && value[brand] === true;
+}
+function applyBrand(value, brand) {
+  if (hasBrand(value, brand)) return;
+  Object.defineProperty(value, brand, {
+    configurable: false,
+    enumerable: false,
+    writable: false,
+    value: true
+  });
+}
+var DeeplineError = class _DeeplineError extends Error {
+  /** HTTP status when the failure crossed an HTTP boundary. */
+  statusCode;
+  /** Stable machine-readable error code when one exists. */
+  code;
+  /** Local diagnostic context; not a portable error contract. */
+  details;
+  /**
+   * Construct a Deepline error.
+   *
+   * SDK and runtime code construct these errors. Application and Play code
+   * normally catches the public subclasses instead.
+   *
+   * @param message Human-readable failure summary.
+   * @param statusCode HTTP status when one exists.
+   * @param code Stable machine-readable code when one exists.
+   * @param details Local diagnostic context; never a portable error contract.
+   */
   constructor(message, statusCode, code, details) {
     super(message);
+    this.name = "DeeplineError";
     this.statusCode = statusCode;
     this.code = code;
     this.details = details;
-    this.name = "DeeplineError";
+    applyBrand(this, DEEPLINE_ERROR_BRAND);
+  }
+  static [Symbol.hasInstance](value) {
+    if (this !== _DeeplineError) return nativeInstanceOf(this, value);
+    return hasBrand(value, DEEPLINE_ERROR_BRAND);
+  }
+};
+var ToolExecutionError = class _ToolExecutionError extends DeeplineError {
+  /** Public tool id passed to `tools.execute`. */
+  toolId;
+  /** Provider responsible for the operation, or `null` when unattributed. */
+  provider;
+  /** Provider operation name, or `null` when unavailable. */
+  operation;
+  /** Boundary responsible for the failure. */
+  origin;
+  /** Stable reason family for policy and diagnostics. */
+  category;
+  /**
+   * Whether repeating the same semantic call is delivery-safe.
+   *
+   * This does not mean the error may be ignored. Waterfall fallthrough is
+   * represented by `ProviderTransientError`.
+   */
+  retryable;
+  /** Provider or Deepline request id, or `null` when unavailable. */
+  requestId;
+  /** Suggested same-call retry delay in milliseconds, or `null`. */
+  retryAfterMs;
+  /** Network failure kind, or `null` for non-network failures. */
+  networkKind;
+  /** Network boundary that failed, or `null` for non-network failures. */
+  networkScope;
+  /**
+   * Construct a structured tool error.
+   *
+   * Deepline constructs this from the versioned `tool_error` payload.
+   * Application and Play code should catch it rather than create it.
+   */
+  constructor(message, options) {
+    super(
+      message,
+      options.statusCode ?? void 0,
+      options.code ?? void 0,
+      options.details
+    );
+    this.name = "ToolExecutionError";
+    this.toolId = options.toolId;
+    this.provider = options.provider;
+    this.operation = options.operation;
+    this.origin = options.origin;
+    this.category = options.category;
+    this.retryable = options.retryable;
+    this.requestId = options.requestId;
+    this.retryAfterMs = options.retryAfterMs;
+    this.networkKind = options.networkKind;
+    this.networkScope = options.networkScope;
+    applyBrand(this, TOOL_EXECUTION_ERROR_BRAND);
+    if (isProviderTransientFailure(options)) {
+      applyBrand(this, PROVIDER_TRANSIENT_ERROR_BRAND);
+    }
+  }
+  static [Symbol.hasInstance](value) {
+    if (this !== _ToolExecutionError) return nativeInstanceOf(this, value);
+    return hasBrand(value, TOOL_EXECUTION_ERROR_BRAND);
+  }
+};
+function brandAsToolExecutionError(value) {
+  applyBrand(value, TOOL_EXECUTION_ERROR_BRAND);
+}
+function isProviderTransientFailure(input) {
+  return input.origin === "provider" && (input.category === "rate_limit" || input.category === "network" || input.category === "upstream");
+}
+var ProviderTransientError = class _ProviderTransientError extends ToolExecutionError {
+  /** Provider attribution is guaranteed for this subtype. */
+  origin = "provider";
+  /** Constructed by Deepline when a provider-owned transient failure arrives. */
+  constructor(message, options) {
+    super(message, {
+      ...options,
+      origin: "provider",
+      category: options.category
+    });
+    this.name = "ProviderTransientError";
+    this.category = options.category;
+    applyBrand(this, PROVIDER_TRANSIENT_ERROR_BRAND);
+  }
+  static [Symbol.hasInstance](value) {
+    if (this !== _ProviderTransientError) return nativeInstanceOf(this, value);
+    return hasBrand(value, PROVIDER_TRANSIENT_ERROR_BRAND);
   }
-  statusCode;
-  code;
-  details;
 };
+function brandAsProviderTransientError(value) {
+  applyBrand(value, PROVIDER_TRANSIENT_ERROR_BRAND);
+}
+function boundedString(value, maxLength = MAX_IDENTIFIER_LENGTH) {
+  if (typeof value !== "string") return null;
+  const normalized = value.trim();
+  return normalized ? normalized.slice(0, maxLength) : null;
+}
+function finiteNonNegativeInteger(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 && Number.isInteger(value) ? value : null;
+}
+function normalizeToolExecutionOrigin(value, input) {
+  const normalized = boundedString(value)?.toLowerCase();
+  if (normalized === "caller") return "caller";
+  if (normalized === "provider" || normalized === "provider_network") {
+    return "provider";
+  }
+  if (normalized === "upstream" && boundedString(input?.provider) && boundedString(input?.operation)) {
+    return "provider";
+  }
+  if (normalized === "deepline" || normalized === "deepline_billing" || normalized === "deepline_rate_limit" || normalized === "internal" || normalized === "server") {
+    return "deepline";
+  }
+  if (normalized === "provider_account") return "provider";
+  return "unknown";
+}
+function normalizeToolExecutionCategory(value) {
+  switch (boundedString(value)?.toLowerCase()) {
+    case "validation":
+    case "authorization":
+    case "rate_limit":
+    case "network":
+    case "upstream":
+    case "billing":
+    case "conflict":
+    case "internal":
+      return boundedString(value).toLowerCase();
+    case "authentication":
+    case "provider_auth":
+    case "provider_account":
+      return "authentication";
+    case "execution":
+    case "parse":
+    case "stub":
+    case "internal_native_search_performance":
+      return "internal";
+    default:
+      return "unknown";
+  }
+}
+function normalizeNetworkKind(value) {
+  switch (boundedString(value)?.toLowerCase()) {
+    case "timeout":
+    case "dns":
+    case "connect":
+    case "reset":
+    case "unavailable":
+    case "unknown":
+      return boundedString(value).toLowerCase();
+    default:
+      return null;
+  }
+}
+function normalizeNetworkScope(value) {
+  switch (boundedString(value)?.toLowerCase()) {
+    case "client_to_deepline":
+    case "runtime_to_deepline":
+    case "deepline_to_provider":
+      return boundedString(value).toLowerCase();
+    default:
+      return null;
+  }
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeToolExecutionFailure(value) {
+  if (!isRecord(value) || value.schemaVersion !== TOOL_EXECUTION_ERROR_SCHEMA_VERSION) {
+    return null;
+  }
+  const toolId = boundedString(value.toolId);
+  if (!toolId) return null;
+  const provider = boundedString(value.provider);
+  const operation = boundedString(value.operation);
+  const origin = normalizeToolExecutionOrigin(value.origin, {
+    provider,
+    operation
+  });
+  const category = normalizeToolExecutionCategory(value.category);
+  const trustworthy = origin !== "unknown" && category !== "unknown" && typeof value.retryable === "boolean";
+  return {
+    schemaVersion: TOOL_EXECUTION_ERROR_SCHEMA_VERSION,
+    toolId,
+    provider,
+    operation,
+    code: boundedString(value.code, MAX_CODE_LENGTH),
+    origin,
+    category,
+    retryable: trustworthy ? value.retryable === true : false,
+    statusCode: finiteNonNegativeInteger(value.statusCode),
+    requestId: boundedString(value.requestId),
+    retryAfterMs: finiteNonNegativeInteger(value.retryAfterMs),
+    networkKind: normalizeNetworkKind(value.networkKind),
+    networkScope: normalizeNetworkScope(value.networkScope)
+  };
+}
+function serializeToolExecutionFailure(error) {
+  if (!(error instanceof ToolExecutionError)) return null;
+  return normalizeToolExecutionFailure({
+    schemaVersion: TOOL_EXECUTION_ERROR_SCHEMA_VERSION,
+    toolId: error.toolId,
+    provider: error.provider,
+    operation: error.operation,
+    code: error.code ?? null,
+    origin: error.origin,
+    category: error.category,
+    retryable: error.retryable,
+    statusCode: error.statusCode ?? null,
+    requestId: error.requestId,
+    retryAfterMs: error.retryAfterMs,
+    networkKind: error.networkKind,
+    networkScope: error.networkScope
+  });
+}
+function deserializeToolExecutionFailure(message, value, acceptedSchemaVersion) {
+  if (acceptedSchemaVersion === LEGACY_TOOL_EXECUTION_ERROR_SCHEMA_VERSION) {
+    return null;
+  }
+  const failure = normalizeToolExecutionFailure(value);
+  if (!failure) return null;
+  if (isProviderTransientFailure(failure)) {
+    return new ProviderTransientError(message, failure);
+  }
+  return new ToolExecutionError(message, failure);
+}
+
+// src/errors.ts
 var AuthError = class extends DeeplineError {
+  /** Constructed by the SDK when Deepline rejects the caller's credentials. */
   constructor(message = "Authentication failed. Check your DEEPLINE_API_KEY.") {
     super(message, 401, "AUTH_ERROR");
     this.name = "AuthError";
@@ -104,6 +378,7 @@ var AuthError = class extends DeeplineError {
 var RateLimitError = class extends DeeplineError {
   /** Milliseconds to wait before retrying, from the `Retry-After` response header. Defaults to 5000. */
   retryAfterMs;
+  /** Constructed by the SDK after exhausting HTTP-level rate-limit retries. */
   constructor(retryAfterMs = 5e3, message) {
     super(
       message ?? `Rate limited. Retry after ${retryAfterMs}ms.`,
@@ -114,7 +389,51 @@ var RateLimitError = class extends DeeplineError {
     this.retryAfterMs = retryAfterMs;
   }
 };
+var ToolRateLimitError = class extends RateLimitError {
+  /** Public tool id passed to `tools.execute`. */
+  toolId;
+  /** Provider responsible for the operation, or `null`. */
+  provider;
+  /** Provider operation name, or `null`. */
+  operation;
+  /** Stable machine-readable failure code when one exists. */
+  code;
+  /** Boundary responsible for the failure. */
+  origin;
+  /** Stable reason family for policy and diagnostics. */
+  category;
+  /** Whether repeating the same semantic call is delivery-safe. */
+  retryable;
+  /** Provider or Deepline request id, or `null`. */
+  requestId;
+  /** Network failure kind, or `null` for non-network failures. */
+  networkKind;
+  /** Network boundary that failed, or `null` for non-network failures. */
+  networkScope;
+  /** Constructed by the SDK after a structured tool HTTP 429. */
+  constructor(message, options) {
+    super(options.retryAfterMs ?? 5e3, message);
+    this.name = "ToolRateLimitError";
+    this.statusCode = options.statusCode ?? 429;
+    this.code = options.code ?? void 0;
+    this.toolId = options.toolId;
+    this.provider = options.provider;
+    this.operation = options.operation;
+    this.origin = options.origin;
+    this.category = options.category;
+    this.retryable = options.retryable;
+    this.requestId = options.requestId;
+    this.networkKind = options.networkKind;
+    this.networkScope = options.networkScope;
+    this.details = options.details;
+    brandAsToolExecutionError(this);
+    if (isProviderTransientFailure(this)) {
+      brandAsProviderTransientError(this);
+    }
+  }
+};
 var ConfigError = class extends DeeplineError {
+  /** Construct a local SDK configuration failure. */
   constructor(message) {
     super(message, void 0, "CONFIG_ERROR");
     this.name = "ConfigError";
@@ -399,6 +718,9 @@ var import_node_fs2 = require("fs");
 var import_node_os3 = require("os");
 var import_node_path2 = require("path");
 
+// ../shared_libs/plays/artifact-contract-version.ts
+var CURRENT_PLAY_ARTIFACT_CONTRACT_VERSION = 2;
+
 // src/release.ts
 var SDK_RELEASE = {
   // 0.1.94 is claimed by PR #1527 — this watch-render fix ships as 0.1.95.
@@ -438,7 +760,7 @@ var SDK_RELEASE = {
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
   // 0.1.254 removes the internal operations tree from the published SDK CLI.
   // Operators use the checkout-local deepline-admin binary instead.
-  version: "0.1.301",
+  version: "0.1.303",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -454,8 +776,8 @@ var SDK_RELEASE = {
     },
     playArtifact: {
       name: "play-artifact-runtime",
-      currentVersion: 2,
-      supportedVersions: [1, 2]
+      currentVersion: CURRENT_PLAY_ARTIFACT_CONTRACT_VERSION,
+      supportedVersions: [1, CURRENT_PLAY_ARTIFACT_CONTRACT_VERSION]
     },
     release: {
       name: "production-sdk-release",
@@ -687,6 +1009,9 @@ function providerLabelFromToolId(toolId) {
   const provider = normalized.split(/[_:./-]+/)[0];
   return provider || normalized || "provider";
 }
+function isRecord2(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
 var HttpClient = class {
   constructor(config) {
     this.config = config;
@@ -822,6 +1147,29 @@ var HttpClient = class {
             signal: controller.signal
           });
           clearTimeout(timeoutId);
+          const body = await response.text();
+          const parsed = parseResponseBody(body);
+          const structuredToolError = options?.toolId && !response.ok ? deserializeToolExecutionFailure(
+            apiErrorMessage(parsed, response.status),
+            isRecord2(parsed) ? parsed.tool_error : null,
+            TOOL_EXECUTION_ERROR_SCHEMA_VERSION
+          ) : null;
+          if (structuredToolError) {
+            if (response.status === 429) {
+              const retryAfter = parseRetryAfter(response);
+              const failure = serializeToolExecutionFailure(structuredToolError);
+              lastError = failure === null ? structuredToolError : new ToolRateLimitError(structuredToolError.message, {
+                ...failure,
+                retryAfterMs: failure.retryAfterMs ?? Math.max(0, retryAfter)
+              });
+              if (attempt < maxRetries) {
+                retryAfterDelayMs = retryAfter;
+                break;
+              }
+              throw lastError;
+            }
+            throw structuredToolError;
+          }
           if (response.status === 429) {
             const retryAfter = parseRetryAfter(response);
             lastError = new RateLimitError(retryAfter);
@@ -831,8 +1179,6 @@ var HttpClient = class {
             }
             throw lastError;
           }
-          const body = await response.text();
-          const parsed = parseResponseBody(body);
           if (response.status === 401 && !isProviderOriginatedHttpError(parsed) || response.status === 403 && !options?.forbiddenAsApiError) {
             throw new AuthError();
           }
@@ -897,6 +1243,29 @@ var HttpClient = class {
       lastError,
       describeRequestTarget(path)
     );
+    if (options?.toolId) {
+      const code = mappedNetworkError.code;
+      throw new ToolExecutionError(
+        withCoworkNetworkHint(mappedNetworkError.message),
+        {
+          toolId: options.toolId,
+          provider: providerLabelFromToolId(options.toolId),
+          operation: options.toolId,
+          code,
+          origin: "deepline",
+          category: "network",
+          // A direct client timeout has ambiguous delivery. Fail closed unless
+          // the server returns the authoritative action delivery contract.
+          retryable: false,
+          statusCode: null,
+          requestId: null,
+          retryAfterMs: null,
+          networkKind: code === "NETWORK_TIMEOUT" ? "timeout" : code === "NETWORK_ABORTED" ? "unknown" : "unavailable",
+          networkScope: "client_to_deepline",
+          details: mappedNetworkError.details
+        }
+      );
+    }
     throw new DeeplineError(
       withCoworkNetworkHint(mappedNetworkError.message),
       void 0,
@@ -1338,11 +1707,11 @@ var RUNNER_POST_TERMINAL_DIAGNOSTIC_MAX_BYTES = 64 * 1024;
 var ledgerIngressRedactor = createSecretRedactionContext();
 
 // ../shared_libs/play-runtime/activity-observation.ts
-function isRecord(value) {
+function isRecord3(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 function isPlayActivityObservation(value) {
-  if (!isRecord(value) || value.schemaVersion !== 1 || typeof value.activityId !== "string" || !value.activityId.trim() || typeof value.observedAt !== "number" || !Number.isFinite(value.observedAt) || !isRecord(value.target) || !isRecord(value.state)) {
+  if (!isRecord3(value) || value.schemaVersion !== 1 || typeof value.activityId !== "string" || !value.activityId.trim() || typeof value.observedAt !== "number" || !Number.isFinite(value.observedAt) || !isRecord3(value.target) || !isRecord3(value.state)) {
     return false;
   }
   const targetKinds = /* @__PURE__ */ new Set([
@@ -1607,7 +1976,7 @@ function projectPlayRunActivity(input) {
 
 // ../shared_libs/play-runtime/run-ledger.ts
 var LOG_TAIL_LIMIT = 100;
-function isRecord2(value) {
+function isRecord4(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 function finiteNumber(value) {
@@ -1703,21 +2072,21 @@ function createEmptyPlayRunLedgerSnapshot(input) {
   };
 }
 function normalizePlayRunLedgerSnapshot(value, fallback) {
-  if (!isRecord2(value)) {
+  if (!isRecord4(value)) {
     return createEmptyPlayRunLedgerSnapshot(fallback);
   }
   const orderedStepIds = Array.isArray(value.orderedStepIds) ? value.orderedStepIds.filter(
     (entry) => typeof entry === "string" && Boolean(entry.trim())
   ) : [];
-  const rawSteps = isRecord2(value.stepsById) ? value.stepsById : {};
+  const rawSteps = isRecord4(value.stepsById) ? value.stepsById : {};
   const stepsById = {};
   for (const [stepId, rawStep] of Object.entries(rawSteps)) {
-    if (!stepId.trim() || !isRecord2(rawStep)) continue;
+    if (!stepId.trim() || !isRecord4(rawStep)) continue;
     const rawStatus = normalizeStepStatus(rawStep.status);
     if (!rawStatus) continue;
     const completedAt = finiteNumber(rawStep.completedAt);
     const status = rawStatus === "running" && completedAt !== null ? "completed" : rawStatus;
-    const rawProgress = isRecord2(rawStep.progress) ? rawStep.progress : null;
+    const rawProgress = isRecord4(rawStep.progress) ? rawStep.progress : null;
     stepsById[stepId] = {
       stepId,
       label: optionalString(rawStep.label),
@@ -1733,10 +2102,10 @@ function normalizePlayRunLedgerSnapshot(value, fallback) {
       progress: rawProgress ? normalizeStepProgress(rawProgress) : null
     };
   }
-  const rawDatasets = isRecord2(value.datasetsById) ? value.datasetsById : {};
+  const rawDatasets = isRecord4(value.datasetsById) ? value.datasetsById : {};
   const datasetsById = {};
   for (const [datasetId, rawDataset] of Object.entries(rawDatasets)) {
-    if (!datasetId.trim() || !isRecord2(rawDataset)) continue;
+    if (!datasetId.trim() || !isRecord4(rawDataset)) continue;
     const phase = rawDataset.phase === "available" || rawDataset.phase === "failed" ? rawDataset.phase : "registered";
     datasetsById[datasetId] = {
       datasetId,
@@ -1750,7 +2119,7 @@ function normalizePlayRunLedgerSnapshot(value, fallback) {
       updatedAt: finiteNumber(rawDataset.updatedAt) ?? 0
     };
   }
-  const rawActivities = isRecord2(value.activitiesById) ? value.activitiesById : {};
+  const rawActivities = isRecord4(value.activitiesById) ? value.activitiesById : {};
   const activitiesById = {};
   for (const [activityId, rawActivity] of Object.entries(rawActivities)) {
     if (activityId.trim() && isPlayActivityObservation(rawActivity) && rawActivity.activityId === activityId) {
@@ -1899,18 +2268,18 @@ function normalizePlayRunLiveStatus(value) {
 function isTerminalPlayRunLiveStatus(status) {
   return isTerminalPlayRunLifecycleStatus(status);
 }
-function isRecord3(value) {
+function isRecord5(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 function finiteNumber2(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
 function extractTerminalRunLogTail(result) {
-  if (!isRecord3(result) || !isRecord3(result._metadata)) {
+  if (!isRecord5(result) || !isRecord5(result._metadata)) {
     return null;
   }
   const runLogTail = result._metadata.runLogTail;
-  if (!isRecord3(runLogTail) || !Array.isArray(runLogTail.tail)) {
+  if (!isRecord5(runLogTail) || !Array.isArray(runLogTail.tail)) {
     return null;
   }
   const logTail = runLogTail.tail.filter(
@@ -2804,7 +3173,7 @@ function resolveToolExecuteTimeoutMs(toolId, input) {
 }
 var RUNS_FAILED_LOG_LIMIT = 20;
 var RUN_LOGS_PAGE_LIMIT = 1e3;
-function isRecord4(value) {
+function isRecord6(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 function isPrebuiltPlayDescription(play) {
@@ -2967,7 +3336,7 @@ function updatePlayLiveStatusState(state, event) {
   }
   const runId = typeof payload.runId === "string" && payload.runId ? payload.runId : isPlayRunPackage(payload) ? payload.run.id : state.runId;
   const status = normalizeLiveStatus(payload.status) ?? (isPlayRunPackage(payload) ? normalizeLiveStatus(payload.run.status) : null) ?? state.status;
-  const progressPayload = isRecord4(payload.progress) ? payload.progress : {};
+  const progressPayload = isRecord6(payload.progress) ? payload.progress : {};
   if (event.type === "play.run.final_status" && state.logs.length === 0 && state.lastLogSeq === 0) {
     const payloadLogs = readStringArray(payload.logs);
     const progressLogs = readStringArray(progressPayload.logs);
@@ -3101,9 +3470,9 @@ var DeeplineClient = class {
     return fields.length > 0 ? { fields } : schema;
   }
   schemaMetadata(schema, key) {
-    if (!isRecord4(schema)) return null;
+    if (!isRecord6(schema)) return null;
     const value = schema[key];
-    return isRecord4(value) ? value : null;
+    return isRecord6(value) ? value : null;
   }
   playRunCommand(play, options) {
     const target = play.reference || play.name;
@@ -3152,7 +3521,7 @@ var DeeplineClient = class {
       aliases,
       inputSchema: options?.compact ? this.compactSchema(play.inputSchema) : play.inputSchema ?? null,
       outputSchema: options?.compact ? this.compactSchema(play.outputSchema) : play.outputSchema ?? null,
-      staticPipeline: isRecord4(play.staticPipeline) ? play.staticPipeline : isRecord4(play.currentRevision?.staticPipeline) ? play.currentRevision.staticPipeline : isRecord4(play.liveRevision?.staticPipeline) ? play.liveRevision.staticPipeline : null,
+      staticPipeline: isRecord6(play.staticPipeline) ? play.staticPipeline : isRecord6(play.currentRevision?.staticPipeline) ? play.currentRevision.staticPipeline : isRecord6(play.liveRevision?.staticPipeline) ? play.liveRevision.staticPipeline : null,
       ...csvInput ? { csvInput } : {},
       ...rowOutputSchema ? { rowOutputSchema } : {},
       runCommand,
@@ -3323,6 +3692,9 @@ var DeeplineClient = class {
   async executeTool(toolId, input, options) {
     const headers = {
       [EXECUTE_RESPONSE_CONTRACT_HEADER]: V2_EXECUTE_RESPONSE_CONTRACT,
+      [TOOL_EXECUTION_ERROR_SCHEMA_HEADER]: String(
+        TOOL_EXECUTION_ERROR_SCHEMA_VERSION
+      ),
       ...options?.includeToolMetadata ? { [INCLUDE_TOOL_METADATA_HEADER]: "true" } : {},
       [EXECUTE_RESPONSE_INTENT_HEADER]: options?.responseIntent ?? "raw"
     };
@@ -3337,7 +3709,8 @@ var DeeplineClient = class {
         forbiddenAsApiError: true,
         timeout: options?.timeout ?? resolveToolExecuteTimeoutMs(toolId, input),
         maxRetries: options?.maxRetries ?? 0,
-        exactUrlOnly: true
+        exactUrlOnly: true,
+        toolId
       }
     );
   }
@@ -5832,6 +6205,11 @@ function normalizeTableNamespace(value) {
   );
 }
 
+// ../shared_libs/play-runtime/tool-result-paths.ts
+function listNameFromDeclaredPath(path) {
+  return String(path || "").split(".").filter(Boolean).at(-1)?.replace(/[^A-Za-z0-9_$]/g, "") || null;
+}
+
 // ../shared_libs/play-runtime/tool-result.ts
 var TARGET_FALLBACK_KEYS = {
   email: [/^email$/i, /^address$/i, /email/i],
@@ -5844,7 +6222,7 @@ var TARGET_FALLBACK_KEYS = {
   status: [/^email_status$/i, /^status$/i],
   email_status: [/^email_status$/i, /^status$/i]
 };
-function isRecord5(value) {
+function isRecord7(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function toV2RawToolOutputPath(path) {
@@ -5904,7 +6282,7 @@ function valuesAtSegments(current, segments, path = []) {
     if (!Array.isArray(current)) return [];
     return valuesAtSegments(current[segment], rest, [...path, segment]);
   }
-  if (!isRecord5(current)) return [];
+  if (!isRecord7(current)) return [];
   const directMatches = valuesAtSegments(current[segment], rest, [
     ...path,
     segment
@@ -5934,7 +6312,7 @@ function getValuesAtPath(root, path) {
   return valuesAtSegments(root, parsePath(path)).map((entry) => entry.value);
 }
 function toResultEnvelope(value) {
-  if (isRecord5(value) && "data" in value) {
+  if (isRecord7(value) && "data" in value) {
     const envelope = { data: value.data };
     if ("meta" in value) envelope.meta = value.meta;
     return envelope;
@@ -5987,7 +6365,7 @@ function getAtPath(root, path) {
       current = current[segment];
       continue;
     }
-    if (!isRecord5(current)) return void 0;
+    if (!isRecord7(current)) return void 0;
     current = current[segment];
   }
   return current;
@@ -6004,7 +6382,7 @@ function normalizeString(value) {
 }
 function normalizeRows(value) {
   if (!Array.isArray(value)) return null;
-  return value.map((entry) => isRecord5(entry) ? entry : { value: entry });
+  return value.map((entry) => isRecord7(entry) ? entry : { value: entry });
 }
 function findFirstTargetByPath(result, paths) {
   for (const path of paths ?? []) {
@@ -6063,7 +6441,7 @@ function findFirstTargetByKey(result, target, depth = 0, path = []) {
     }
     return null;
   }
-  if (!isRecord5(result)) return null;
+  if (!isRecord7(result)) return null;
   const patterns = TARGET_FALLBACK_KEYS[target] ?? [
     new RegExp(`^${target}$`, "i")
   ];
@@ -6123,7 +6501,7 @@ function normalizeJobChangeStatus(value) {
 function firstExperienceDate(value) {
   if (!Array.isArray(value)) return null;
   for (const entry of value) {
-    if (!isRecord5(entry)) continue;
+    if (!isRecord7(entry)) continue;
     const date = normalizeString(
       entry.start_date ?? entry.started_at ?? entry.startDate
     );
@@ -6132,10 +6510,10 @@ function firstExperienceDate(value) {
   return null;
 }
 function normalizeJobChange(value) {
-  const record = isRecord5(value) ? value : {};
-  const nested = isRecord5(record.job_change) ? record.job_change : record;
-  const output = isRecord5(nested.output) ? nested.output : nested;
-  const person = isRecord5(output.person) ? output.person : {};
+  const record = isRecord7(value) ? value : {};
+  const nested = isRecord7(record.job_change) ? record.job_change : record;
+  const output = isRecord7(nested.output) ? nested.output : nested;
+  const person = isRecord7(output.person) ? output.person : {};
   const status = normalizeJobChangeStatus(
     output.status ?? output.job_change_status ?? output.job_changed ?? output.changed
   );
@@ -6172,38 +6550,33 @@ function coerceToEnum(value, descriptor) {
 function resolveListRows(result, listExtractorPaths) {
   const lists = {};
   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 = null;
-    let rows = null;
+    let resolved = null;
     let emptyMatch = 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 };
+      emptyMatch ??= { path: candidate, rows: candidateRows };
     }
-    if (!rows && emptyMatch) {
-      resolvedPath = emptyMatch.path;
-      rows = emptyMatch.rows;
-    }
-    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;
 }
@@ -6437,6 +6810,7 @@ function createToolExecuteResult(input) {
     toolId: input.metadata.toolId,
     execution: input.execution,
     targets,
+    listExtractorPaths: [...input.metadata.listExtractorPaths ?? []],
     ...input.metadata.extractors ? { extractors: input.metadata.extractors } : {},
     lists
   };
@@ -6478,6 +6852,19 @@ function attachToolResultListDataset(result, input) {
     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,
@@ -6500,7 +6887,7 @@ function attachToolResultListDataset(result, input) {
     root = replaceAtPath(root, candidate, serialized.preview);
     break;
   }
-  if (isRecord5(root) && isRecord5(root.toolResponse) && Object.prototype.hasOwnProperty.call(root.toolResponse, "raw")) {
+  if (isRecord7(root) && isRecord7(root.toolResponse) && Object.prototype.hasOwnProperty.call(root.toolResponse, "raw")) {
     result.toolResponse.raw = root.toolResponse.raw;
     result.toolOutput.raw = root.toolResponse.raw;
   }
@@ -6518,7 +6905,7 @@ function replaceAtPath(root, path, replacement) {
       copy[segment] = replace(copy[segment], index + 1);
       return copy;
     }
-    if (!isRecord5(current)) return current;
+    if (!isRecord7(current)) return current;
     return {
       ...current,
       [segment]: replace(current[segment], index + 1)
@@ -6839,11 +7226,11 @@ var Deepline = class {
     return new DeeplineContext(options);
   }
 };
-function isRecord6(value) {
+function isRecord8(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function stringArrayRecord(value) {
-  if (!isRecord6(value)) return {};
+  if (!isRecord8(value)) return {};
   return Object.fromEntries(
     Object.entries(value).map(([key, paths]) => [
       key,
@@ -6855,7 +7242,7 @@ function stringArray(value) {
   return Array.isArray(value) ? value.map(String) : [];
 }
 function emailStatusExtractorConfig(value) {
-  if (!isRecord6(value)) return void 0;
+  if (!isRecord8(value)) return void 0;
   const readPaths = (key) => {
     const paths = stringArray(value[key]).map((path) => path.trim()).filter(Boolean);
     return paths.length > 0 ? paths : void 0;
@@ -6882,7 +7269,7 @@ function emailStatusExtractorConfig(value) {
     const paths = readPaths(key);
     if (paths) config[key] = paths;
   }
-  if (isRecord6(value.statusMap)) {
+  if (isRecord8(value.statusMap)) {
     config.statusMap = value.statusMap;
   }
   if (Array.isArray(value.rules)) {
@@ -6891,10 +7278,10 @@ function emailStatusExtractorConfig(value) {
   return config;
 }
 function extractorDescriptorRecord(value) {
-  if (!isRecord6(value)) return {};
+  if (!isRecord8(value)) return {};
   return Object.fromEntries(
     Object.entries(value).flatMap(([key, descriptor]) => {
-      if (!isRecord6(descriptor)) return [];
+      if (!isRecord8(descriptor)) return [];
       const paths = stringArray(descriptor.paths).map((path) => path.trim()).filter(Boolean);
       if (paths.length === 0) return [];
       const transforms = stringArray(descriptor.transforms).map((transform) => transform.trim()).filter(Boolean);
@@ -6916,16 +7303,16 @@ function extractorDescriptorRecord(value) {
 }
 function rowsFromUnknown(value) {
   if (!Array.isArray(value)) return [];
-  return value.map((row) => isRecord6(row) ? row : { value: row });
+  return value.map((row) => isRecord8(row) ? row : { value: row });
 }
-function finiteNonNegativeInteger(value) {
+function finiteNonNegativeInteger2(value) {
   if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
     return null;
   }
   return Math.floor(value);
 }
 function finitePositiveInteger(value) {
-  const integer = finiteNonNegativeInteger(value);
+  const integer = finiteNonNegativeInteger2(value);
   return integer !== null && integer > 0 ? integer : null;
 }
 function stableHash(value) {
@@ -6938,9 +7325,9 @@ function stableHash(value) {
 }
 function attachSdkQueryResultDatasetResult(toolId, result, options) {
   if (!options || !isQueryResultDatasetTool(toolId)) return result;
-  const raw = isRecord6(result.toolResponse.raw) ? result.toolResponse.raw : null;
-  const dataset = isRecord6(raw?.dataset) ? raw.dataset : null;
-  const totalRows = finiteNonNegativeInteger(dataset?.total_rows);
+  const raw = isRecord8(result.toolResponse.raw) ? result.toolResponse.raw : null;
+  const dataset = isRecord8(raw?.dataset) ? raw.dataset : null;
+  const totalRows = finiteNonNegativeInteger2(dataset?.total_rows);
   const sql = typeof options.input.sql === "string" ? options.input.sql : typeof options.input.query === "string" ? options.input.query : typeof raw?.sql === "string" ? raw.sql : null;
   if (!dataset || totalRows === null || !sql) {
     return result;
@@ -6969,7 +7356,7 @@ function attachSdkQueryResultDatasetResult(toolId, result, options) {
         } : {}
       }
     });
-    const pageRaw = isRecord6(response.toolResponse?.raw) ? response.toolResponse.raw : null;
+    const pageRaw = isRecord8(response.toolResponse?.raw) ? response.toolResponse.raw : null;
     return rowsFromUnknown(pageRaw?.rows);
   };
   const collectRows = async (limit) => {
@@ -7022,8 +7409,8 @@ function attachSdkQueryResultDatasetResult(toolId, result, options) {
 function toolExecutionEnvelopeToResult(fallbackToolId, response, options) {
   const raw = response.toolResponse?.raw ?? null;
   const meta = response.toolResponse?.meta;
-  const metadata = isRecord6(response._metadata) ? response._metadata.tool : null;
-  const toolMetadata = isRecord6(metadata) ? metadata : {};
+  const metadata = isRecord8(response._metadata) ? response._metadata.tool : null;
+  const toolMetadata = isRecord8(metadata) ? metadata : {};
   return attachSdkQueryResultDatasetResult(
     fallbackToolId,
     createToolExecuteResult({
@@ -7031,7 +7418,7 @@ function toolExecutionEnvelopeToResult(fallbackToolId, response, options) {
       jobId: typeof response.job_id === "string" ? response.job_id : void 0,
       result: {
         data: raw,
-        ...isRecord6(meta) ? { meta } : {}
+        ...isRecord8(meta) ? { meta } : {}
       },
       metadata: {
         toolId: typeof toolMetadata.toolId === "string" ? toolMetadata.toolId : fallbackToolId,
@@ -7047,7 +7434,7 @@ function toolExecutionEnvelopeToResult(fallbackToolId, response, options) {
         cached: false,
         source: "live"
       },
-      meta: isRecord6(response.meta) ? response.meta : void 0
+      meta: isRecord8(response.meta) ? response.meta : void 0
     }),
     options
   );
@@ -7067,14 +7454,16 @@ function definePlay(nameOrConfig, maybeFn, maybeBindings) {
     bindings: maybeBindings,
     description: maybeBindings?.description,
     inputSchema: void 0,
-    billing: maybeBindings?.billing
+    billing: maybeBindings?.billing,
+    compatibility: maybeBindings?.compatibility
   } : {
     name: nameOrConfig.id,
     fn: nameOrConfig.run,
     bindings: nameOrConfig.bindings,
     description: nameOrConfig.description,
     inputSchema: nameOrConfig.input.schema,
-    billing: nameOrConfig.billing
+    billing: nameOrConfig.billing,
+    compatibility: nameOrConfig.compatibility ?? nameOrConfig.bindings?.compatibility
   };
   const name = config.name;
   const fn = config.fn;
@@ -7082,6 +7471,7 @@ function definePlay(nameOrConfig, maybeFn, maybeBindings) {
   const description = config.description?.trim();
   const billing = config.billing;
   const inputSchema = config.inputSchema;
+  const compatibility = config.compatibility;
   if (typeof fn !== "function") {
     throw new Error("definePlay(...) requires an async run function.");
   }
@@ -7106,7 +7496,8 @@ function definePlay(nameOrConfig, maybeFn, maybeBindings) {
     ...description ? { description } : {},
     ...bindings ? { bindings } : {},
     ...inputSchema ? { inputSchema } : {},
-    ...billing ? { billing } : {}
+    ...billing ? { billing } : {},
+    ...compatibility ? { compatibility } : {}
   };
   const play = fn;
   Object.defineProperty(play, PLAY_METADATA_SYMBOL, {
@@ -7127,6 +7518,12 @@ function definePlay(nameOrConfig, maybeFn, maybeBindings) {
     configurable: false,
     writable: false
   });
+  Object.defineProperty(play, "compatibility", {
+    value: compatibility,
+    enumerable: true,
+    configurable: false,
+    writable: false
+  });
   const handle = createNamedPlayHandle(
     () => new DeeplineClient(),
     name
@@ -7373,10 +7770,13 @@ function extractSummaryFields(payload) {
   PLAY_BOOTSTRAP_STAGE_KINDS,
   PLAY_BOOTSTRAP_TEMPLATES,
   PROD_URL,
+  ProviderTransientError,
   RateLimitError,
   RunObserveTransportUnavailableError,
   SDK_API_CONTRACT,
   SDK_VERSION,
+  ToolExecutionError,
+  ToolRateLimitError,
   defineInput,
   defineMonitor,
   definePlay,