deepline 0.1.301 → 0.1.303

package/dist/plays/bundle-play-file.d.mts

@@ -1,5 +1,5 @@
-import { P as PlayArtifactKind$1, a as PlayCompilerManifest } from '../compiler-manifest-BjopNIqx.mjs';
-export { b as PLAY_ARTIFACT_KINDS } from '../compiler-manifest-BjopNIqx.mjs';
+import { T as ToolExecutionErrorSchemaVersion, P as PlayArtifactKind$1, a as PlayCompilerManifest } from '../tool-execution-error-YDz7UMl-.mjs';
+export { b as PLAY_ARTIFACT_KINDS } from '../tool-execution-error-YDz7UMl-.mjs';
 
 type PlayPackageImport = {
     name: string;
@@ -17,6 +17,8 @@ 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. */
 type PlayArtifactKind = 'cjs_node20';

package/dist/plays/bundle-play-file.d.ts

@@ -1,5 +1,5 @@
-import { P as PlayArtifactKind$1, a as PlayCompilerManifest } from '../compiler-manifest-BjopNIqx.js';
-export { b as PLAY_ARTIFACT_KINDS } from '../compiler-manifest-BjopNIqx.js';
+import { T as ToolExecutionErrorSchemaVersion, P as PlayArtifactKind$1, a as PlayCompilerManifest } from '../tool-execution-error-YDz7UMl-.js';
+export { b as PLAY_ARTIFACT_KINDS } from '../tool-execution-error-YDz7UMl-.js';
 
 type PlayPackageImport = {
     name: string;
@@ -17,6 +17,8 @@ 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. */
 type PlayArtifactKind = 'cjs_node20';

package/dist/plays/bundle-play-file.mjs

@@ -43,9 +43,15 @@ var PLAY_BACKEND_DESCRIPTORS = {
   }
 };
 
+// ../shared_libs/tool-execution-error.ts
+var TOOL_EXECUTION_ERROR_SCHEMA_VERSION = 1;
+
+// ../shared_libs/plays/artifact-contract-version.ts
+var CURRENT_PLAY_ARTIFACT_CONTRACT_VERSION = 2;
+
 // ../shared_libs/plays/contracts.ts
 var PLAY_PUBLIC_API_VERSION = 1;
-var PLAY_ARTIFACT_VERSION = 1;
+var PLAY_ARTIFACT_VERSION = CURRENT_PLAY_ARTIFACT_CONTRACT_VERSION;
 var PLAY_MIN_RUNNER_VERSION = 1;
 var PLAY_RUNTIME_FEATURES = [
   "artifact_storage",
@@ -59,7 +65,8 @@ function buildPlayContractCompatibility(input) {
     artifactVersion: PLAY_ARTIFACT_VERSION,
     minRunnerVersion: PLAY_MIN_RUNNER_VERSION,
     runtimeFeatures: [...PLAY_RUNTIME_FEATURES],
-    runtimeBackend: input?.runtimeBackend ?? null
+    runtimeBackend: input?.runtimeBackend ?? null,
+    toolErrorSchemaVersion: input?.toolErrorSchemaVersion ?? TOOL_EXECUTION_ERROR_SCHEMA_VERSION
   };
 }
 
@@ -133,7 +140,7 @@ function validatePlaySourceFilesHaveNoInlineSecrets(sourceFiles) {
 var MAX_PLAY_BUNDLE_BYTES = 30 * 1024 * 1024;
 
 // ../shared_libs/plays/bundling/index.ts
-var PLAY_BUNDLE_CACHE_VERSION = 25;
+var PLAY_BUNDLE_CACHE_VERSION = 27;
 var PLAY_ARTIFACT_CACHE_DIR = join(
   tmpdir(),
   `deepline-play-artifacts-v${PLAY_BUNDLE_CACHE_VERSION}`
@@ -283,15 +290,6 @@ function findSourceImportReferences(sourceCode) {
 function extractDefinedPlayName(sourceCode) {
   return extractDefinedPlayMetadata(sourceCode, null)?.name ?? null;
 }
-function extractDefinedPlayNameForExport(sourceCode, exportName) {
-  return extractDefinedPlayMetadata(sourceCode, exportName)?.name ?? null;
-}
-function extractDefinedPlayDescription(sourceCode) {
-  return extractDefinedPlayMetadata(sourceCode, null)?.description ?? null;
-}
-function extractDefinedPlayDescriptionForExport(sourceCode, exportName) {
-  return extractDefinedPlayMetadata(sourceCode, exportName)?.description ?? null;
-}
 var TypeScriptParser = Parser.extend(
   tsPlugin({
     allowSatisfies: true,
@@ -499,9 +497,11 @@ function staticStringFromExpression(node, context, seen = /* @__PURE__ */ new Se
   );
 }
 function propertyNameFromKey(property) {
-  if (property.computed) return null;
   const key = isAstNode(property.key) ? property.key : null;
   if (!key) return null;
+  if (property.computed) {
+    return key.type === "Literal" && typeof key.value === "string" ? key.value : null;
+  }
   if (key.type === "Identifier" && typeof key.name === "string") {
     return key.name;
   }
@@ -523,6 +523,77 @@ function objectExpressionFromNode(node, context, seen = /* @__PURE__ */ new Set(
     seen
   );
 }
+function resolveStaticProperty(node, propertyName, context, ancestors = /* @__PURE__ */ new Set()) {
+  if (!node) return { kind: "absent" };
+  const object = objectExpressionFromNode(node, context);
+  if (!object) return { kind: "unknown" };
+  if (ancestors.has(object)) return { kind: "unknown" };
+  const nextAncestors = new Set(ancestors).add(object);
+  let resolution = { kind: "absent" };
+  for (const property of astArray(object.properties)) {
+    if (property.type === "SpreadElement") {
+      const spreadResolution = resolveStaticProperty(
+        isAstNode(property.argument) ? property.argument : null,
+        propertyName,
+        context,
+        nextAncestors
+      );
+      if (spreadResolution.kind !== "absent") {
+        resolution = spreadResolution;
+      }
+      continue;
+    }
+    if (property.type !== "Property") continue;
+    const resolvedPropertyName = propertyNameFromKey(property);
+    if (resolvedPropertyName !== propertyName) {
+      if (property.computed && resolvedPropertyName === null) {
+        resolution = { kind: "unknown" };
+      }
+      continue;
+    }
+    const propertyValue = property.shorthand ? property.key : property.value;
+    resolution = isAstNode(propertyValue) ? { kind: "found", value: propertyValue } : { kind: "unknown" };
+  }
+  return resolution;
+}
+function staticNumberFromExpression(node, context, seen = /* @__PURE__ */ new Set()) {
+  const expression = unwrapStaticExpression(node);
+  if (!expression) return null;
+  if (expression.type === "Literal" && typeof expression.value === "number") {
+    return expression.value;
+  }
+  const identifier = getIdentifierName(expression);
+  if (!identifier || seen.has(identifier)) return null;
+  seen.add(identifier);
+  return staticNumberFromExpression(
+    context.declarations.get(identifier),
+    context,
+    seen
+  );
+}
+function toolErrorSchemaVersionFromOptions(node, context) {
+  const directCompatibility = resolveStaticProperty(
+    node,
+    "compatibility",
+    context
+  );
+  if (directCompatibility.kind === "unknown") return null;
+  const bindings = resolveStaticProperty(node, "bindings", context);
+  if (bindings.kind === "unknown") return null;
+  const bindingCompatibility = bindings.kind === "found" ? resolveStaticProperty(bindings.value, "compatibility", context) : { kind: "absent" };
+  if (bindingCompatibility.kind === "unknown") return null;
+  const compatibility = directCompatibility.kind === "found" ? directCompatibility : bindingCompatibility;
+  if (compatibility.kind === "absent") return void 0;
+  const schema = resolveStaticProperty(
+    compatibility.value,
+    "toolErrorSchemaVersion",
+    context
+  );
+  if (schema.kind !== "found") return null;
+  const schemaVersion = staticNumberFromExpression(schema.value, context);
+  if (schemaVersion === 0 || schemaVersion === 1) return schemaVersion;
+  return null;
+}
 function stringPropertyFromObjectExpression(node, propertyName, context, seenObjects = /* @__PURE__ */ new Set()) {
   const object = objectExpressionFromNode(node, context);
   if (!object || seenObjects.has(object)) return null;
@@ -568,12 +639,13 @@ function playMetadataFromDefinePlayCall(node, context) {
   }
   const args = astArray(expression.arguments);
   const firstArg = args[0] ?? null;
+  const isObjectForm = args.length === 1 || objectExpressionFromNode(firstArg, context) !== null;
   const objectName = stringPropertyFromObjectExpression(
     firstArg,
     "id",
     context
   );
-  const name = objectName ?? staticStringFromExpression(firstArg, context);
+  const name = isObjectForm ? objectName : staticStringFromExpression(firstArg, context);
   let description = stringPropertyFromObjectExpression(firstArg, "description", context) ?? null;
   for (let index = args.length - 1; !description && index >= 2; index -= 1) {
     description = stringPropertyFromObjectExpression(
@@ -582,8 +654,21 @@ function playMetadataFromDefinePlayCall(node, context) {
       context
     );
   }
-  if (!name && !description) return null;
-  return { name, description };
+  const options = isObjectForm ? firstArg : args[2] ?? null;
+  const toolErrorSchemaVersion = toolErrorSchemaVersionFromOptions(
+    options,
+    context
+  );
+  const toolErrorSchemaVersionUnknown = toolErrorSchemaVersion === null;
+  if (!name && !description && toolErrorSchemaVersion === void 0 && !toolErrorSchemaVersionUnknown) {
+    return null;
+  }
+  return {
+    name,
+    description,
+    toolErrorSchemaVersion: toolErrorSchemaVersion ?? null,
+    toolErrorSchemaVersionUnknown
+  };
 }
 function resolveExportExpression(exportName, context) {
   if (exportName === "default") {
@@ -960,8 +1045,14 @@ async function analyzeSourceGraph(entryFile, adapter, exportName) {
       })).sort((left, right) => left.filePath.localeCompare(right.filePath))
     })
   );
-  const playName = extractDefinedPlayNameForExport(sourceCode, exportName) ?? (exportName === "default" ? extractDefinedPlayName(sourceCode) : null);
-  const playDescription = extractDefinedPlayDescriptionForExport(sourceCode, exportName) ?? (exportName === "default" ? extractDefinedPlayDescription(sourceCode) : null);
+  const metadata = extractDefinedPlayMetadata(sourceCode, exportName) ?? (exportName === "default" ? extractDefinedPlayMetadata(sourceCode, null) : null);
+  if (metadata?.toolErrorSchemaVersionUnknown) {
+    throw new Error(
+      "definePlay compatibility.toolErrorSchemaVersion must be the static literal 0 or 1."
+    );
+  }
+  const playName = metadata?.name ?? null;
+  const playDescription = metadata?.description ?? null;
   return {
     sourceCode,
     sourceFiles: Object.fromEntries(
@@ -978,6 +1069,7 @@ async function analyzeSourceGraph(entryFile, adapter, exportName) {
     },
     playName,
     playDescription,
+    toolErrorSchemaVersion: metadata?.toolErrorSchemaVersion ?? null,
     importedPlayDependencies: [...importedPlayDependencies.values()].sort(
       (left, right) => left.filePath.localeCompare(right.filePath)
     )
@@ -1149,6 +1241,9 @@ entry-export:${exportName}`
           entryFile: absolutePath,
           sourceHash: analysis.sourceHash,
           importPolicy: analysis.importPolicy,
+          compatibility: buildPlayContractCompatibility({
+            toolErrorSchemaVersion: analysis.toolErrorSchemaVersion ?? void 0
+          }),
           cacheHit: true
         },
         sourceCode: analysis.sourceCode,
@@ -1209,7 +1304,9 @@ entry-export:${exportName}`
       bundledCode: executableCode,
       sourceMap: normalizedSourceMap,
       importPolicy: analysis.importPolicy,
-      compatibility: buildPlayContractCompatibility(),
+      compatibility: buildPlayContractCompatibility({
+        toolErrorSchemaVersion: analysis.toolErrorSchemaVersion ?? void 0
+      }),
       generatedAt: Date.now(),
       cacheHit: false
     };

package/dist/tool-execution-error-YDz7UMl-.d.mts

@@ -0,0 +1,440 @@
+/**
+ * The one executable Play artifact contract. Daytona and local-process both
+ * load CommonJS under Node 20.
+ */
+declare const PLAY_ARTIFACT_KINDS: {
+    readonly cjsNode20: "cjs_node20";
+};
+type PlayArtifactKind = (typeof PLAY_ARTIFACT_KINDS)[keyof typeof PLAY_ARTIFACT_KINDS];
+
+/**
+ * A top-level key the play's function literally `return`s. Derived from the
+ * `return { ... }` object literal — NOT from dataset `.withColumn(...)` names —
+ * so the "Returns" graph node mirrors the function's real output shape.
+ * `isDataset` is true when the key's value is a `PlayDataset` handle (a table).
+ */
+interface PlayStaticReturnField {
+    name: string;
+    isDataset: boolean;
+    /**
+     * For a dataset-valued field, the `ctx.dataset(KEY, ...)` key backing it
+     * (e.g. `job_change_checks`) — so the UI can label the return by the dataset
+     * it actually produces instead of the bland object key (`rows`). Undefined
+     * for non-dataset fields, `ctx.csv(...)` (no durable name), or when the key
+     * isn't a static string literal.
+     */
+    datasetName?: string;
+}
+interface PlayStaticPipeline {
+    tableNamespace?: string;
+    inputFields?: string[];
+    rowKeyFields?: string[];
+    csvArg?: string;
+    hasInlineData?: boolean;
+    csvDescription?: string;
+    datasetDescription?: string;
+    fields: string[];
+    /**
+     * Top-level keys of the play's `return { ... }` object literal, in source
+     * order. Undefined when the terminal return isn't a statically-known object
+     * literal (bare value, dataset handle, conditional returns, etc.).
+     */
+    returnFields?: PlayStaticReturnField[];
+    stages?: PlayStaticSubstep[];
+    substeps: PlayStaticSubstep[];
+    sheetContract?: PlaySheetContract | null;
+    sheetContractErrors?: string[];
+}
+type PlaySheetColumnSource = 'input' | 'datasetColumn' | 'waterfallStep' | 'childPlayColumn';
+interface PlaySheetColumnContract {
+    id: string;
+    sqlName: string;
+    source: PlaySheetColumnSource;
+    field?: string;
+    parentField?: string;
+    playId?: string;
+    waterfallId?: string;
+    outputField?: string;
+    outputSqlName?: string;
+    stepId?: string;
+    toolId?: string;
+    isRowKey?: boolean;
+}
+interface PlaySheetContract {
+    tableNamespace: string;
+    columns: PlaySheetColumnContract[];
+}
+type PlayStaticColumnProducerKind = 'tool' | 'waterfall' | 'stepProgram' | 'playCall' | 'controlFlow' | 'transform';
+interface PlayStaticColumnProducer {
+    id: string;
+    kind: PlayStaticColumnProducerKind;
+    field: string;
+    toolId?: string;
+    playId?: string;
+    conditional?: boolean;
+    sourceRange?: PlayStaticSourceRange;
+    steps?: PlayStaticColumnProducer[];
+    substep: PlayStaticSubstep;
+}
+interface PlayStaticDatasetColumn {
+    id: string;
+    source: PlaySheetColumnSource;
+    sqlName?: string;
+    producers: PlayStaticColumnProducer[];
+}
+interface PlayStaticSourceRange {
+    sourcePath?: string;
+    startLine: number;
+    endLine: number;
+    startColumn: number;
+    endColumn: number;
+}
+type PlayStaticSubstepMetadata = {
+    conditional?: boolean;
+    disabled?: boolean;
+};
+/**
+ * One arm of a conditional `control_flow` substep — an `if`/`else if`/`else`
+ * leg, a `switch` case, or a ternary branch. Carries its own steps so the graph
+ * can render the conditional as a real fork instead of a flat strip.
+ */
+type PlayStaticControlFlowBranch = {
+    /** Short arm label, e.g. `if`, `else if`, `else`, `case 'x'`, `default`. */
+    label: string;
+    /** The arm's condition source text, when it has one (omitted for `else`). */
+    condition?: string;
+    /** Static work in this arm. Empty for log/throw/return-only arms. */
+    steps: PlayStaticSubstep[];
+};
+type PlayStaticSubstep = PlayStaticSubstepMetadata & ({
+    type: 'csv';
+    field: string;
+    path?: string;
+    description?: string;
+    sourceRange?: PlayStaticSourceRange;
+    callDepth?: number;
+    callPath?: string[];
+} | {
+    type: 'dataset';
+    field: string;
+    name?: string;
+    tableNamespace?: string;
+    inputFields?: string[];
+    rowKeyFields?: string[];
+    outputFields?: string[];
+    columns?: PlayStaticDatasetColumn[];
+    waterfallIds?: string[];
+    steps?: PlayStaticSubstep[];
+    sheetContract?: PlaySheetContract | null;
+    description?: string;
+    sourceRange?: PlayStaticSourceRange;
+    callDepth?: number;
+    callPath?: string[];
+} | {
+    type: 'tool';
+    toolId: string;
+    field: string;
+    paramsSource?: string;
+    sourceText?: string;
+    description?: string;
+    inLoop?: boolean;
+    isEventWait?: boolean;
+    sourceRange?: PlayStaticSourceRange;
+    callDepth?: number;
+    callPath?: string[];
+} | {
+    type: 'waterfall';
+    tool?: string;
+    field: string;
+    inLoop?: boolean;
+    id?: string;
+    output?: string;
+    minResults?: number;
+    sourceText?: string;
+    steps?: Array<{
+        id: string;
+        kind?: 'tool' | 'code';
+        toolId?: string;
+        paramsSource?: string;
+    }>;
+    description?: string;
+    sourceRange?: PlayStaticSourceRange;
+    callDepth?: number;
+    callPath?: string[];
+} | {
+    type: 'step_suite';
+    field: string;
+    steps: PlayStaticSubstep[];
+    returnSource?: string;
+    description?: string;
+    sourceRange?: PlayStaticSourceRange;
+    callDepth?: number;
+    callPath?: string[];
+} | {
+    type: 'play_call';
+    playId: string;
+    execution?: 'inline' | 'child-workflow';
+    timeoutMs?: number;
+    hasExplicitTimeout?: boolean;
+    field: string;
+    inLoop?: boolean;
+    pipeline?: PlayStaticPipeline | null;
+    cycleDetected?: boolean;
+    resolutionError?: string;
+    description?: string;
+    sourceRange?: PlayStaticSourceRange;
+    callDepth?: number;
+    callPath?: string[];
+} | {
+    type: 'control_flow';
+    kind: 'conditional' | 'loop';
+    field: string;
+    /** Flattened steps across every arm, in source order (back-compat). */
+    steps: PlayStaticSubstep[];
+    /** Discriminant source text (the `if`/ternary test, `switch` subject). */
+    condition?: string;
+    /** Per-arm breakdown for conditionals; omitted for loops. */
+    branches?: PlayStaticControlFlowBranch[];
+    description?: string;
+    sourceRange?: PlayStaticSourceRange;
+    callDepth?: number;
+    callPath?: string[];
+} | {
+    type: 'run_javascript';
+    alias: string;
+    sourceText?: string;
+    description?: string;
+    sourceRange?: PlayStaticSourceRange;
+    callDepth?: number;
+    callPath?: string[];
+} | {
+    type: 'code';
+    field: string;
+    sourceText?: string;
+    description?: string;
+    sourceRange?: PlayStaticSourceRange;
+    callDepth?: number;
+    callPath?: string[];
+});
+
+type PlayCompilerDependencyManifest = {
+    playName: string;
+    /** Original source path for direct imported definePlay dependencies. */
+    filePath?: string;
+    sourceHash: string;
+    graphHash: string;
+    artifactHash: string;
+    staticPipeline: PlayStaticPipeline;
+};
+type PlayCompilerManifest = {
+    compilerVersion: number;
+    playName: string;
+    sourceHash: string;
+    graphHash: string;
+    artifactHash: string;
+    artifactKind?: PlayArtifactKind;
+    staticPipeline: PlayStaticPipeline;
+    importedPlayDependencies: PlayCompilerDependencyManifest[];
+};
+
+declare const TOOL_EXECUTION_ERROR_SCHEMA_VERSION: 1;
+declare const SUPPORTED_TOOL_EXECUTION_ERROR_SCHEMA_VERSIONS: readonly [0, 1];
+type ToolExecutionErrorSchemaVersion = (typeof SUPPORTED_TOOL_EXECUTION_ERROR_SCHEMA_VERSIONS)[number];
+/**
+ * The boundary responsible for a failed tool call.
+ *
+ * Use `provider` to distinguish a provider answer from caller input and
+ * Deepline infrastructure. `unknown` fails closed and must not trigger a
+ * waterfall fallback.
+ *
+ * @sdkReference errors 020
+ */
+type ToolExecutionErrorOrigin = 'caller' | 'provider' | 'deepline' | 'unknown';
+/**
+ * The stable reason family for a failed tool call.
+ *
+ * Branch on this field only after narrowing to `ToolExecutionError`. Catch
+ * `ProviderTransientError` when the policy is simply “try the next read
+ * provider”; it is the safer and shorter waterfall contract.
+ *
+ * @sdkReference errors 030
+ */
+type ToolExecutionErrorCategory = 'validation' | 'authentication' | 'authorization' | 'rate_limit' | 'network' | 'upstream' | 'billing' | 'conflict' | 'internal' | 'unknown';
+/**
+ * The transport failure observed when `category` is `network`.
+ *
+ * This is `null` for failures that are not network failures.
+ *
+ * @sdkReference errors 040
+ */
+type ToolExecutionNetworkKind = 'timeout' | 'dns' | 'connect' | 'reset' | 'unavailable' | 'unknown';
+/**
+ * The request boundary on which a network failure occurred.
+ *
+ * `deepline_to_provider` is provider-side. Client and runtime scopes are
+ * Deepline transport failures and never qualify as provider fallthrough.
+ *
+ * @sdkReference errors 050
+ */
+type ToolExecutionNetworkScope = 'client_to_deepline' | 'runtime_to_deepline' | 'deepline_to_provider';
+/**
+ * Portable version-1 `tool_error` payload.
+ *
+ * This allowlisted shape crosses the API, runtime, and SDK boundaries.
+ * `message` remains on the Error object and is deliberately not a policy
+ * field.
+ *
+ * @sdkReference errors 064
+ */
+type ToolExecutionFailureV1 = {
+    /** Payload version. */
+    schemaVersion: typeof TOOL_EXECUTION_ERROR_SCHEMA_VERSION;
+    /** Public tool id passed to `tools.execute`. */
+    toolId: string;
+    /** Provider responsible for the operation, or `null`. */
+    provider: string | null;
+    /** Provider operation name, or `null`. */
+    operation: string | null;
+    /** Stable machine-readable failure code, or `null`. */
+    code: string | null;
+    /** Boundary responsible for the failure. */
+    origin: ToolExecutionErrorOrigin;
+    /** Stable reason family. */
+    category: ToolExecutionErrorCategory;
+    /** Whether repeating the same semantic call is delivery-safe. */
+    retryable: boolean;
+    /** HTTP status when one exists, or `null`. */
+    statusCode: number | null;
+    /** Provider or Deepline request id, or `null`. */
+    requestId: string | null;
+    /** Suggested same-call retry delay in milliseconds, or `null`. */
+    retryAfterMs: number | null;
+    /** Network failure kind, or `null`. */
+    networkKind: ToolExecutionNetworkKind | null;
+    /** Network boundary that failed, or `null`. */
+    networkScope: ToolExecutionNetworkScope | null;
+};
+/**
+ * Constructor input for a structured tool failure.
+ *
+ * Deepline creates these values while decoding the versioned wire payload.
+ * Customer code normally reads `ToolExecutionError` fields instead of
+ * constructing an error.
+ *
+ * @sdkReference errors 065
+ */
+type ToolExecutionErrorOptions = Omit<ToolExecutionFailureV1, 'schemaVersion'> & {
+    /**
+     * Local diagnostic context inherited from DeeplineError. This is not part of
+     * the portable failure payload and is intentionally omitted by serialization.
+     */
+    details?: Record<string, unknown>;
+};
+/**
+ * Provider-owned failure categories that may fall through to another read
+ * provider.
+ *
+ * @sdkReference errors 060
+ */
+type ProviderTransientErrorCategory = 'rate_limit' | 'network' | 'upstream';
+/**
+ * Base error class shared by the SDK and play runtime.
+ *
+ * The global brand preserves `instanceof DeeplineError` when a bundled play
+ * and the runtime load separate physical copies of this module.
+ *
+ * @sdkReference errors 010
+ */
+declare class DeeplineError extends Error {
+    /** HTTP status when the failure crossed an HTTP boundary. */
+    statusCode?: number;
+    /** Stable machine-readable error code when one exists. */
+    code?: string;
+    /** Local diagnostic context; not a portable error contract. */
+    details?: Record<string, unknown>;
+    /**
+     * 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: string, statusCode?: number, code?: string, details?: Record<string, unknown>);
+    static [Symbol.hasInstance](value: unknown): boolean;
+}
+/**
+ * A failed `tools.execute` call with stable, allowlisted provenance.
+ *
+ * `retryable` means Deepline's delivery/idempotency contract says it is safe
+ * to repeat the same semantic call. It does not describe durable receipt
+ * repairability and does not make arbitrary side-effecting fallbacks safe.
+ *
+ * In a Play, catch `ProviderTransientError` to continue a read waterfall and
+ * let every other `ToolExecutionError` remain loud. In an SDK client, catch
+ * this base class when you need structured diagnostics for every tool failure.
+ *
+ * @sdkReference errors 070
+ */
+declare class ToolExecutionError extends DeeplineError {
+    /** Public tool id passed to `tools.execute`. */
+    readonly toolId: string;
+    /** Provider responsible for the operation, or `null` when unattributed. */
+    readonly provider: string | null;
+    /** Provider operation name, or `null` when unavailable. */
+    readonly operation: string | null;
+    /** Boundary responsible for the failure. */
+    readonly origin: ToolExecutionErrorOrigin;
+    /** Stable reason family for policy and diagnostics. */
+    readonly category: ToolExecutionErrorCategory;
+    /**
+     * Whether repeating the same semantic call is delivery-safe.
+     *
+     * This does not mean the error may be ignored. Waterfall fallthrough is
+     * represented by `ProviderTransientError`.
+     */
+    readonly retryable: boolean;
+    /** Provider or Deepline request id, or `null` when unavailable. */
+    readonly requestId: string | null;
+    /** Suggested same-call retry delay in milliseconds, or `null`. */
+    readonly retryAfterMs: number | null;
+    /** Network failure kind, or `null` for non-network failures. */
+    readonly networkKind: ToolExecutionNetworkKind | null;
+    /** Network boundary that failed, or `null` for non-network failures. */
+    readonly networkScope: ToolExecutionNetworkScope | null;
+    /**
+     * 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: string, options: ToolExecutionErrorOptions);
+    static [Symbol.hasInstance](value: unknown): boolean;
+}
+/**
+ * A provider-owned transient failure that is safe to handle as an empty
+ * waterfall leg. Validation, auth, billing, Deepline, and unknown failures
+ * never satisfy this type.
+ *
+ * `retryable` remains independent: it says whether the same semantic call may
+ * be repeated safely. Falling through to a different read provider depends on
+ * this class, not on `retryable`.
+ *
+ * @sdkReference errors 080
+ */
+declare class ProviderTransientError extends ToolExecutionError {
+    /** Provider attribution is guaranteed for this subtype. */
+    readonly origin: "provider";
+    /** Provider failure category that made this error eligible for fallthrough. */
+    readonly category: ProviderTransientErrorCategory;
+    /** Constructed by Deepline when a provider-owned transient failure arrives. */
+    constructor(message: string, options: Omit<ToolExecutionErrorOptions, 'origin' | 'category'> & {
+        category: ProviderTransientErrorCategory;
+    });
+    static [Symbol.hasInstance](value: unknown): boolean;
+}
+
+export { DeeplineError as D, type PlayArtifactKind as P, type ToolExecutionErrorSchemaVersion as T, type PlayCompilerManifest as a, PLAY_ARTIFACT_KINDS as b, ToolExecutionError as c, type ToolExecutionErrorOptions as d, ProviderTransientError as e, type ProviderTransientErrorCategory as f, type ToolExecutionErrorCategory as g, type ToolExecutionErrorOrigin as h, type ToolExecutionFailureV1 as i, type ToolExecutionNetworkKind as j, type ToolExecutionNetworkScope as k };