deepline 0.1.301 → 0.1.303

package/dist/bundling-sources/sdk/src/client.ts

@@ -93,6 +93,10 @@ import {
   normalizePlayRuntimeSelection,
   type PlayRuntimeSelection,
 } from '../../shared_libs/play-runtime/runtime-environment.js';
+import {
+  TOOL_EXECUTION_ERROR_SCHEMA_HEADER,
+  TOOL_EXECUTION_ERROR_SCHEMA_VERSION,
+} from '../../shared_libs/tool-execution-error.js';
 import { decodePlayRunPublicStatus } from '../../shared_libs/play-runtime/run-lifecycle-policy.js';
 
 const TERMINAL_PLAY_STATUSES = new Set(['completed', 'failed', 'cancelled']);
@@ -1765,6 +1769,9 @@ export class DeeplineClient {
   ): Promise<ToolExecution<TData, TMeta>> {
     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' }
         : {}),
@@ -1782,6 +1789,7 @@ export class DeeplineClient {
         timeout: options?.timeout ?? resolveToolExecuteTimeoutMs(toolId, input),
         maxRetries: options?.maxRetries ?? 0,
         exactUrlOnly: true,
+        toolId,
       },
     );
   }

package/dist/bundling-sources/sdk/src/errors.ts

@@ -1,39 +1,31 @@
-/**
- * Base error class for all Deepline SDK errors.
- *
- * Every error thrown by the SDK extends this class, so you can catch all
- * Deepline-specific errors with a single `catch (e) { if (e instanceof DeeplineError) }`.
- *
- * @example
- * ```typescript
- * import { DeeplineClient, DeeplineError, AuthError } from 'deepline';
- *
- * const client = new DeeplineClient();
- * try {
- *   await client.executeTool('dropleads_search_people', { query: 'cto' });
- * } catch (err) {
- *   if (err instanceof AuthError) {
- *     console.error('Bad API key — run: deepline auth register');
- *   } else if (err instanceof DeeplineError) {
- *     console.error(`API error ${err.statusCode}: ${err.message}`);
- *   }
- * }
- * ```
- */
-export class DeeplineError extends Error {
-  constructor(
-    message: string,
-    /** HTTP status code from the API response, if applicable. */
-    public statusCode?: number,
-    /** Machine-readable error code (e.g. `'AUTH_ERROR'`, `'RATE_LIMIT'`, `'CONFIG_ERROR'`). */
-    public code?: string,
-    /** Additional context from the API response body. */
-    public details?: Record<string, unknown>,
-  ) {
-    super(message);
-    this.name = 'DeeplineError';
-  }
-}
+import {
+  DeeplineError,
+  ProviderTransientError,
+  ToolExecutionError,
+  brandAsProviderTransientError,
+  brandAsToolExecutionError,
+  isProviderTransientFailure,
+  type ProviderTransientErrorCategory,
+  type ToolExecutionErrorCategory,
+  type ToolExecutionFailureV1,
+  type ToolExecutionErrorOrigin,
+  type ToolExecutionErrorOptions,
+  type ToolExecutionNetworkKind,
+  type ToolExecutionNetworkScope,
+} from '../../shared_libs/tool-execution-error.js';
+
+export {
+  DeeplineError,
+  ProviderTransientError,
+  ToolExecutionError,
+  type ProviderTransientErrorCategory,
+  type ToolExecutionErrorCategory,
+  type ToolExecutionFailureV1,
+  type ToolExecutionErrorOrigin,
+  type ToolExecutionErrorOptions,
+  type ToolExecutionNetworkKind,
+  type ToolExecutionNetworkScope,
+} from '../../shared_libs/tool-execution-error.js';
 
 /**
  * Thrown when the API rejects the request due to an invalid or missing API key.
@@ -56,8 +48,11 @@ export class DeeplineError extends Error {
  *   }
  * }
  * ```
+ *
+ * @sdkReference errors 090
  */
 export class AuthError 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';
@@ -86,11 +81,14 @@ export class AuthError extends DeeplineError {
  *   }
  * }
  * ```
+ *
+ * @sdkReference errors 100
  */
 export class RateLimitError extends DeeplineError {
   /** Milliseconds to wait before retrying, from the `Retry-After` response header. Defaults to 5000. */
   public retryAfterMs: number;
 
+  /** Constructed by the SDK after exhausting HTTP-level rate-limit retries. */
   constructor(retryAfterMs = 5000, message?: string) {
     super(
       message ?? `Rate limited. Retry after ${retryAfterMs}ms.`,
@@ -102,6 +100,65 @@ export class RateLimitError extends DeeplineError {
   }
 }
 
+/**
+ * Tool-specific 429 preserving both historical RateLimitError catches and the
+ * structured ToolExecutionError ontology. JavaScript has one prototype chain,
+ * so this class extends RateLimitError and carries ToolExecutionError's stable
+ * cross-bundle brand.
+ *
+ * This class appears in external SDK calls after HTTP 429 retries are
+ * exhausted. It also satisfies `instanceof ToolExecutionError` and, for a
+ * provider-owned rate limit, `instanceof ProviderTransientError`. Authored
+ * Plays should use `ProviderTransientError`; they do not need this
+ * compatibility class.
+ *
+ * @sdkReference errors 110
+ */
+export class ToolRateLimitError extends RateLimitError {
+  /** Public tool id passed to `tools.execute`. */
+  readonly toolId: string;
+  /** Provider responsible for the operation, or `null`. */
+  readonly provider: string | null;
+  /** Provider operation name, or `null`. */
+  readonly operation: string | null;
+  /** Stable machine-readable failure code when one exists. */
+  override readonly code: string | undefined;
+  /** Boundary responsible for the failure. */
+  readonly origin: ToolExecutionError['origin'];
+  /** Stable reason family for policy and diagnostics. */
+  readonly category: ToolExecutionError['category'];
+  /** Whether repeating the same semantic call is delivery-safe. */
+  readonly retryable: boolean;
+  /** Provider or Deepline request id, or `null`. */
+  readonly requestId: string | null;
+  /** Network failure kind, or `null` for non-network failures. */
+  readonly networkKind: ToolExecutionError['networkKind'];
+  /** Network boundary that failed, or `null` for non-network failures. */
+  readonly networkScope: ToolExecutionError['networkScope'];
+
+  /** Constructed by the SDK after a structured tool HTTP 429. */
+  constructor(message: string, options: ToolExecutionErrorOptions) {
+    super(options.retryAfterMs ?? 5_000, message);
+    this.name = 'ToolRateLimitError';
+    this.statusCode = options.statusCode ?? 429;
+    this.code = options.code ?? undefined;
+    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);
+    }
+  }
+}
+
 /**
  * Thrown when the SDK cannot resolve a valid configuration.
  *
@@ -120,8 +177,11 @@ export class RateLimitError extends DeeplineError {
  *   }
  * }
  * ```
+ *
+ * @sdkReference errors 120
  */
 export class ConfigError extends DeeplineError {
+  /** Construct a local SDK configuration failure. */
   constructor(message: string) {
     super(message, undefined, 'CONFIG_ERROR');
     this.name = 'ConfigError';

package/dist/bundling-sources/sdk/src/http.ts

@@ -22,7 +22,18 @@ import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import type { ResolvedConfig } from './types.js';
-import { AuthError, DeeplineError, RateLimitError } from './errors.js';
+import {
+  AuthError,
+  DeeplineError,
+  RateLimitError,
+  ToolExecutionError,
+  ToolRateLimitError,
+} from './errors.js';
+import {
+  deserializeToolExecutionFailure,
+  serializeToolExecutionFailure,
+  TOOL_EXECUTION_ERROR_SCHEMA_VERSION,
+} from '../../shared_libs/tool-execution-error.js';
 import { SDK_API_CONTRACT, SDK_VERSION } from './version.js';
 import type { LiveEventEnvelope } from './types.js';
 import { baseUrlSlug, sdkCliStateDirPath } from './config.js';
@@ -67,6 +78,8 @@ interface RequestOptions {
   maxRetries?: number;
   /** Disable localhost/127.0.0.1 failover for non-idempotent requests. */
   exactUrlOnly?: boolean;
+  /** Enables endpoint-specific structured tool failure mapping. */
+  toolId?: string;
 }
 
 interface StreamOptions {
@@ -153,6 +166,10 @@ function providerLabelFromToolId(toolId: string): string {
   return provider || normalized || 'provider';
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
 /**
  * Low-level HTTP client used internally by {@link DeeplineClient}.
  *
@@ -374,6 +391,41 @@ export class HttpClient {
 
           clearTimeout(timeoutId);
 
+          const body = await response.text();
+          const parsed = parseResponseBody(body);
+
+          const structuredToolError =
+            options?.toolId && !response.ok
+              ? deserializeToolExecutionFailure(
+                  apiErrorMessage(parsed, response.status),
+                  isRecord(parsed)
+                    ? (parsed as Record<string, unknown>).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);
@@ -384,9 +436,6 @@ export class HttpClient {
             throw lastError;
           }
 
-          const body = await response.text();
-          const parsed = parseResponseBody(body);
-
           if (
             (response.status === 401 &&
               !isProviderOriginatedHttpError(parsed)) ||
@@ -394,7 +443,6 @@ export class HttpClient {
           ) {
             throw new AuthError();
           }
-
           if (!response.ok) {
             const retryableApiError =
               options?.retryApiErrors === true &&
@@ -486,6 +534,34 @@ export class HttpClient {
       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),
       undefined,
@@ -610,6 +686,7 @@ export class HttpClient {
       | 'timeout'
       | 'maxRetries'
       | 'exactUrlOnly'
+      | 'toolId'
     >,
   ): Promise<T> {
     return this.request<T>(path, {

package/dist/bundling-sources/sdk/src/index.ts

@@ -123,10 +123,22 @@ export {
 // ——— Errors ———
 export {
   DeeplineError,
+  ProviderTransientError,
+  ToolExecutionError,
   AuthError,
   RateLimitError,
+  ToolRateLimitError,
   ConfigError,
 } from './errors.js';
+export type {
+  ProviderTransientErrorCategory,
+  ToolExecutionErrorCategory,
+  ToolExecutionFailureV1,
+  ToolExecutionErrorOrigin,
+  ToolExecutionErrorOptions,
+  ToolExecutionNetworkKind,
+  ToolExecutionNetworkScope,
+} from './errors.js';
 
 // ——— Config ———
 export { resolveConfig, PROD_URL } from './config.js';

package/dist/bundling-sources/sdk/src/play.ts

@@ -113,6 +113,7 @@ import type {
   ToolMetadata,
 } from './types.js';
 import type { ToolExecution } from './client.js';
+import type { ToolExecutionErrorSchemaVersion } from '../../shared_libs/tool-execution-error.js';
 
 export type PlayCallExecution = 'inline' | 'child-workflow';
 
@@ -180,6 +181,16 @@ export type PlayBindings = {
    * older clients can continue to register revisions during the migration.
    */
   description?: string;
+  /**
+   * Public behavior that must remain pinned for this play artifact.
+   *
+   * New plays default to typed tool errors (`1`). Set `toolErrorSchemaVersion`
+   * to `0` only while migrating code that depends on legacy error names,
+   * messages, or classes.
+   */
+  compatibility?: {
+    toolErrorSchemaVersion: ToolExecutionErrorSchemaVersion;
+  };
   /** Allow compilers to bundle this named handler directly without a child run. */
   inline?: boolean;
   /** Optional per-run billing controls enforced by the runtime. */
@@ -903,7 +914,7 @@ export interface DeeplinePlayRuntimeContext {
     key: string,
     playRef: string | PlayReferenceLike,
     input: Record<string, unknown>,
-    options: PlayCallOptions,
+    options?: PlayCallOptions,
   ): Promise<TOutput>;
 
   /**
@@ -1182,6 +1193,8 @@ export type DefinePlayConfig<TInput, TOutput extends PlayReturnObject> = {
   bindings?: PlayBindings;
   /** Billing options. */
   billing?: PlayBindings['billing'];
+  /** Runtime compatibility override. Omit for the current typed contract. */
+  compatibility?: PlayBindings['compatibility'];
 };
 
 class DeeplineConditionalStepResolver<
@@ -1341,6 +1354,8 @@ export type DefinedPlay<TInput, TOutput extends PlayReturnObject> = ((
   DeeplineNamedPlay<TInput, TOutput> & {
     /** Optional trigger bindings (cron, webhook). */
     readonly bindings?: PlayBindings;
+    /** Runtime compatibility explicitly selected by the author. */
+    readonly compatibility?: PlayBindings['compatibility'];
     /** The play's name (same as `.name`). */
     readonly playName: string;
   };
@@ -1351,6 +1366,7 @@ type PlayMetadata = {
   bindings?: PlayBindings;
   inputSchema?: Record<string, unknown>;
   billing?: PlayBindings['billing'];
+  compatibility?: PlayBindings['compatibility'];
 };
 
 const PLAY_METADATA_SYMBOL = Symbol.for('deepline.play.metadata');
@@ -2108,6 +2124,7 @@ export function definePlay<TInput, TOutput extends PlayReturnObject>(
           description: maybeBindings?.description,
           inputSchema: undefined,
           billing: maybeBindings?.billing,
+          compatibility: maybeBindings?.compatibility,
         }
       : {
           name: nameOrConfig.id,
@@ -2116,6 +2133,8 @@ export function definePlay<TInput, TOutput extends PlayReturnObject>(
           description: nameOrConfig.description,
           inputSchema: nameOrConfig.input.schema,
           billing: nameOrConfig.billing,
+          compatibility:
+            nameOrConfig.compatibility ?? nameOrConfig.bindings?.compatibility,
         };
   const name = config.name;
   const fn = config.fn;
@@ -2123,6 +2142,7 @@ export function definePlay<TInput, TOutput extends PlayReturnObject>(
   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.');
   }
@@ -2156,6 +2176,7 @@ export function definePlay<TInput, TOutput extends PlayReturnObject>(
     ...(bindings ? { bindings } : {}),
     ...(inputSchema ? { inputSchema } : {}),
     ...(billing ? { billing } : {}),
+    ...(compatibility ? { compatibility } : {}),
   };
   const play = fn as DefinedPlay<TInput, TOutput>;
 
@@ -2180,6 +2201,13 @@ export function definePlay<TInput, TOutput extends PlayReturnObject>(
     writable: false,
   });
 
+  Object.defineProperty(play, 'compatibility', {
+    value: compatibility,
+    enumerable: true,
+    configurable: false,
+    writable: false,
+  });
+
   const handle = createNamedPlayHandle<TInput, TOutput>(
     () => new DeeplineClient(),
     name,

package/dist/bundling-sources/sdk/src/release.ts

@@ -1,3 +1,5 @@
+import { CURRENT_PLAY_ARTIFACT_CONTRACT_VERSION } from '../../shared_libs/plays/artifact-contract-version';
+
 /**
  * Single source of truth for SDK release metadata.
  *
@@ -155,7 +157,7 @@ export const 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',
@@ -171,8 +173,8 @@ export const 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',