deepline 0.1.300 → 0.1.302

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

@@ -0,0 +1,428 @@
+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;
+
+export type ToolExecutionErrorOrigin =
+  | 'caller'
+  | 'provider'
+  | 'deepline'
+  | 'unknown';
+
+export type ToolExecutionErrorCategory =
+  | 'validation'
+  | 'authentication'
+  | 'authorization'
+  | 'rate_limit'
+  | 'network'
+  | 'upstream'
+  | 'billing'
+  | 'conflict'
+  | 'internal'
+  | 'unknown';
+
+export type ToolExecutionNetworkKind =
+  | 'timeout'
+  | 'dns'
+  | 'connect'
+  | 'reset'
+  | 'unavailable'
+  | 'unknown';
+
+export type ToolExecutionNetworkScope =
+  | 'client_to_deepline'
+  | 'runtime_to_deepline'
+  | 'deepline_to_provider';
+
+export type ToolExecutionFailureV1 = {
+  schemaVersion: typeof TOOL_EXECUTION_ERROR_SCHEMA_VERSION;
+  toolId: string;
+  provider: string | null;
+  operation: string | null;
+  code: string | null;
+  origin: ToolExecutionErrorOrigin;
+  category: ToolExecutionErrorCategory;
+  retryable: boolean;
+  statusCode: number | null;
+  requestId: string | null;
+  retryAfterMs: number | null;
+  networkKind: ToolExecutionNetworkKind | null;
+  networkScope: ToolExecutionNetworkScope | null;
+};
+
+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>;
+};
+
+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.
+ */
+export class DeeplineError extends Error {
+  constructor(
+    message: string,
+    public statusCode?: number,
+    public code?: string,
+    public details?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = 'DeeplineError';
+    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.
+ */
+export class ToolExecutionError extends DeeplineError {
+  readonly toolId: string;
+  readonly provider: string | null;
+  readonly operation: string | null;
+  readonly origin: ToolExecutionErrorOrigin;
+  readonly category: ToolExecutionErrorCategory;
+  readonly retryable: boolean;
+  readonly requestId: string | null;
+  readonly retryAfterMs: number | null;
+  readonly networkKind: ToolExecutionNetworkKind | null;
+  readonly networkScope: ToolExecutionNetworkScope | null;
+
+  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.
+ */
+export class ProviderTransientError extends ToolExecutionError {
+  override readonly origin = 'provider' as const;
+  declare readonly category: ProviderTransientErrorCategory;
+
+  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);
+  }
+}
+
+/** 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);
+}