deepline 0.3.45 → 0.3.47

package/dist/bundling-sources/shared_libs/plays/tool-execution-error.ts

@@ -0,0 +1,624 @@
+const DEEPLINE_ERROR_BRAND = Symbol.for('deepline.error.v1');
+export const TOOL_EXECUTION_ERROR_BRAND = Symbol.for(
+  'deepline.tool-execution-error.v1',
+);
+const PROVIDER_TRANSIENT_ERROR_BRAND = Symbol.for(
+  'deepline.provider-transient-error.v1',
+);
+
+export const LEGACY_TOOL_EXECUTION_ERROR_SCHEMA_VERSION = 0 as const;
+export const TOOL_EXECUTION_ERROR_SCHEMA_VERSION = 1 as const;
+export const SUPPORTED_TOOL_EXECUTION_ERROR_SCHEMA_VERSIONS = [
+  LEGACY_TOOL_EXECUTION_ERROR_SCHEMA_VERSION,
+  TOOL_EXECUTION_ERROR_SCHEMA_VERSION,
+] as const;
+export type ToolExecutionErrorSchemaVersion =
+  (typeof SUPPORTED_TOOL_EXECUTION_ERROR_SCHEMA_VERSIONS)[number];
+export const TOOL_EXECUTION_ERROR_SCHEMA_HEADER =
+  'x-deepline-tool-error-schema';
+
+const MAX_IDENTIFIER_LENGTH = 200;
+const MAX_CODE_LENGTH = 160;
+
+/**
+ * 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export type ProviderTransientErrorCategory =
+  | 'rate_limit'
+  | 'network'
+  | 'upstream';
+
+function nativeInstanceOf(constructor: object, value: unknown): boolean {
+  return Reflect.apply(Function.prototype[Symbol.hasInstance], constructor, [
+    value,
+  ]) as boolean;
+}
+
+function hasBrand(value: unknown, brand: symbol): boolean {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as Record<symbol, unknown>)[brand] === true
+  );
+}
+
+function applyBrand(value: object, brand: symbol): void {
+  if (hasBrand(value, brand)) return;
+  Object.defineProperty(value, brand, {
+    configurable: false,
+    enumerable: false,
+    writable: false,
+    value: true,
+  });
+}
+
+/**
+ * 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
+ */
+export 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>,
+  ) {
+    super(message);
+    this.name = 'DeeplineError';
+    this.statusCode = statusCode;
+    this.code = code;
+    this.details = details;
+    applyBrand(this, DEEPLINE_ERROR_BRAND);
+  }
+
+  static [Symbol.hasInstance](value: unknown): boolean {
+    // Subclasses inherit static methods. Delegate subclass checks to the native
+    // prototype algorithm so AuthError never accidentally matches ConfigError.
+    if (this !== DeeplineError) return nativeInstanceOf(this, value);
+    return hasBrand(value, DEEPLINE_ERROR_BRAND);
+  }
+}
+
+/**
+ * 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
+ */
+export 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) {
+    super(
+      message,
+      options.statusCode ?? undefined,
+      options.code ?? undefined,
+      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: unknown): boolean {
+    if (this !== ToolExecutionError) return nativeInstanceOf(this, value);
+    return hasBrand(value, TOOL_EXECUTION_ERROR_BRAND);
+  }
+}
+
+/**
+ * Brands a compatibility subclass (notably SDK ToolRateLimitError) as a tool
+ * failure without changing its existing prototype chain.
+ */
+export function brandAsToolExecutionError(value: object): void {
+  applyBrand(value, TOOL_EXECUTION_ERROR_BRAND);
+}
+
+export function isProviderTransientFailure(input: {
+  origin: ToolExecutionErrorOrigin;
+  category: ToolExecutionErrorCategory;
+  retryable: boolean;
+}): input is {
+  origin: 'provider';
+  category: ProviderTransientErrorCategory;
+  retryable: boolean;
+} {
+  return (
+    input.origin === 'provider' &&
+    (input.category === 'rate_limit' ||
+      input.category === 'network' ||
+      input.category === 'upstream')
+  );
+}
+
+/**
+ * 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
+ */
+export class ProviderTransientError extends ToolExecutionError {
+  /** Provider attribution is guaranteed for this subtype. */
+  override readonly origin = 'provider' as const;
+  /** Provider failure category that made this error eligible for fallthrough. */
+  declare readonly category: ProviderTransientErrorCategory;
+
+  /** Constructed by Deepline when a provider-owned transient failure arrives. */
+  constructor(
+    message: string,
+    options: Omit<ToolExecutionErrorOptions, 'origin' | 'category'> & {
+      category: ProviderTransientErrorCategory;
+    },
+  ) {
+    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: unknown): boolean {
+    if (this !== ProviderTransientError) return nativeInstanceOf(this, value);
+    return hasBrand(value, PROVIDER_TRANSIENT_ERROR_BRAND);
+  }
+}
+
+/** Why a provider cannot serve the current read request. */
+export type ProviderUnavailableReason =
+  | ProviderTransientErrorCategory
+  | 'account_capacity'
+  | 'credentials_missing';
+
+/**
+ * A provider failure that permits a read waterfall to try its next provider.
+ * A missing provider connection is included because another provider may still
+ * serve the read. Invalid credentials, caller input, and Deepline billing
+ * failures remain loud.
+ */
+export type ProviderUnavailableError =
+  | ProviderTransientError
+  | (ToolExecutionError & {
+      readonly origin: 'provider';
+      readonly code: 'PROVIDER_ACCOUNT_CAPACITY';
+    })
+  | (ToolExecutionError & {
+      readonly origin: 'caller';
+      readonly code: 'INTEGRATION_CREDENTIALS_MISSING';
+    });
+
+/**
+ * Return the provider-specific reason a read cannot run right now.
+ *
+ * `null` means this error must stay loud: it is caller input, an invalid
+ * customer credential, Deepline billing, or an internal failure. A missing
+ * provider connection is different: an explicit read waterfall may continue
+ * to a configured fallback and record the unavailable leg.
+ */
+export function getProviderUnavailableReason(
+  error: unknown,
+): ProviderUnavailableReason | null {
+  if (error instanceof ProviderTransientError) return error.category;
+  if (
+    error instanceof ToolExecutionError &&
+    error.origin === 'provider' &&
+    error.code === 'PROVIDER_ACCOUNT_CAPACITY'
+  ) {
+    return 'account_capacity';
+  }
+  if (
+    error instanceof ToolExecutionError &&
+    error.origin === 'caller' &&
+    error.code === 'INTEGRATION_CREDENTIALS_MISSING'
+  ) {
+    return 'credentials_missing';
+  }
+  return null;
+}
+
+/**
+ * Whether a provider cannot serve this read right now.
+ *
+ * Use this in an explicit `catch` to advance a read-only waterfall. For
+ * diagnostics, use `getProviderUnavailableReason(error)`.
+ */
+export function isProviderUnavailable(
+  error: unknown,
+): error is ProviderUnavailableError {
+  return getProviderUnavailableReason(error) !== null;
+}
+
+/** @deprecated Use isProviderUnavailable. */
+export const isProviderWaterfallUnavailableError = isProviderUnavailable;
+
+/** Brand an internal compatibility error after its normalized fields exist. */
+export function brandAsProviderTransientError(value: object): void {
+  applyBrand(value, PROVIDER_TRANSIENT_ERROR_BRAND);
+}
+
+function boundedString(
+  value: unknown,
+  maxLength = MAX_IDENTIFIER_LENGTH,
+): string | null {
+  if (typeof value !== 'string') return null;
+  const normalized = value.trim();
+  return normalized ? normalized.slice(0, maxLength) : null;
+}
+
+function finiteNonNegativeInteger(value: unknown): number | null {
+  return typeof value === 'number' &&
+    Number.isFinite(value) &&
+    value >= 0 &&
+    Number.isInteger(value)
+    ? value
+    : null;
+}
+
+export function normalizeToolExecutionOrigin(
+  value: unknown,
+  input?: { provider?: string | null; operation?: string | null },
+): ToolExecutionErrorOrigin {
+  const normalized = boundedString(value)?.toLowerCase();
+  if (normalized === 'caller') return 'caller';
+  if (normalized === 'provider' || normalized === 'provider_network') {
+    return 'provider';
+  }
+  // Older integration adapters use "upstream" for a provider-owned failure.
+  // Only accept that alias when the execution boundary identifies the provider
+  // action; an unscoped upstream error fails closed.
+  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';
+}
+
+export function normalizeToolExecutionCategory(
+  value: unknown,
+): ToolExecutionErrorCategory {
+  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() as ToolExecutionErrorCategory;
+    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: unknown): ToolExecutionNetworkKind | null {
+  switch (boundedString(value)?.toLowerCase()) {
+    case 'timeout':
+    case 'dns':
+    case 'connect':
+    case 'reset':
+    case 'unavailable':
+    case 'unknown':
+      return boundedString(value)!.toLowerCase() as ToolExecutionNetworkKind;
+    default:
+      return null;
+  }
+}
+
+function normalizeNetworkScope(
+  value: unknown,
+): ToolExecutionNetworkScope | null {
+  switch (boundedString(value)?.toLowerCase()) {
+    case 'client_to_deepline':
+    case 'runtime_to_deepline':
+    case 'deepline_to_provider':
+      return boundedString(value)!.toLowerCase() as ToolExecutionNetworkScope;
+    default:
+      return null;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function normalizeToolExecutionFailure(
+  value: unknown,
+): ToolExecutionFailureV1 | null {
+  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),
+  };
+}
+
+export function serializeToolExecutionFailure(
+  error: unknown,
+): ToolExecutionFailureV1 | null {
+  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,
+  });
+}
+
+export function deserializeToolExecutionFailure(
+  message: string,
+  value: unknown,
+  acceptedSchemaVersion: ToolExecutionErrorSchemaVersion,
+): ToolExecutionError | null {
+  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);
+}