Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
3.7 KB
Raw Blame
/**
 * Plugin Workload SDK — structured error model (spec §15).
 *
 * Every failure surfaced to a plugin workload is a PluginWorkloadError with
 * a stable machine-readable code, an HTTP status, and a retryable hint.
 * Internal control-api response details never pass through verbatim — the
 * anti-corruption layer maps them here.
 */

export const PLUGIN_WORKLOAD_ERROR_CODES = [
  'capability_not_declared',
  'caller_not_allowed',
  'scope_denied',
  'target_not_allowed',
  'ambiguous_model',
  'event_type_not_allowed',
  'quota_exceeded',
  'provider_policy_denied',
  'provider_unavailable',
  'payload_too_large',
  'idempotency_conflict',
  'invalid_request',
  'unauthorized',
  'protocol_mismatch',
] as const
export type PluginWorkloadErrorCode = (typeof PLUGIN_WORKLOAD_ERROR_CODES)[number]

/** Safe, closed diagnostic classes for provider_unavailable responses. */
export const PLUGIN_WORKLOAD_ERROR_REASONS = [
  'rate_limited',
  'insufficient_quota',
  'auth',
  'provider_unavailable',
  'credential_unavailable',
  'configuration',
  'timeout',
  'network',
  'outcome_unknown',
] as const
export type PluginWorkloadErrorReason = (typeof PLUGIN_WORKLOAD_ERROR_REASONS)[number]

export type PluginWorkloadProviderAttemptContext = {
  providerAttemptId: string
  providerAttemptIndex: number
  target: {
    targetRef: string
    provider: string
    model: string
    credentialSlot: string
  }
  attemptCount: number
  fallbackUsed: boolean
  /** Known only after credential resolution; pre-provider failures may not have one. */
  llmSecretName?: string
}

const ERROR_HTTP_STATUS: Record<PluginWorkloadErrorCode, number> = {
  capability_not_declared: 403,
  caller_not_allowed: 403,
  scope_denied: 403,
  target_not_allowed: 403,
  ambiguous_model: 409,
  event_type_not_allowed: 403,
  quota_exceeded: 429,
  provider_policy_denied: 403,
  provider_unavailable: 503,
  payload_too_large: 413,
  idempotency_conflict: 422,
  invalid_request: 400,
  unauthorized: 401,
  protocol_mismatch: 503,
}

const ERROR_CODE_SET = new Set<string>(PLUGIN_WORKLOAD_ERROR_CODES)
const ERROR_REASON_SET = new Set<string>(PLUGIN_WORKLOAD_ERROR_REASONS)

export class PluginWorkloadError extends Error {
  readonly code: PluginWorkloadErrorCode
  readonly retryable: boolean
  readonly httpStatus: number
  readonly reason?: PluginWorkloadErrorReason
  /** True when the provider may already have accepted or returned a call. */
  readonly providerMayHaveExecuted: boolean
  /** Internal immutable context needed to persist an unknown spend receipt. */
  readonly providerAttempt?: PluginWorkloadProviderAttemptContext

  constructor(
    code: PluginWorkloadErrorCode,
    message: string,
    retryable = false,
    reason?: PluginWorkloadErrorReason,
    providerMayHaveExecuted = false,
    providerAttempt?: PluginWorkloadProviderAttemptContext
  ) {
    super(message)
    this.name = 'PluginWorkloadError'
    this.code = code
    this.retryable = retryable
    this.httpStatus = ERROR_HTTP_STATUS[code]
    this.reason = reason
    this.providerMayHaveExecuted = providerMayHaveExecuted
    this.providerAttempt = providerAttempt
  }

  toBody(): {
    error: PluginWorkloadErrorCode
    message: string
    retryable: boolean
    reason?: PluginWorkloadErrorReason
  } {
    return {
      error: this.code,
      message: this.message,
      retryable: this.retryable,
      ...(this.reason ? { reason: this.reason } : {}),
    }
  }
}

export function isKnownPluginWorkloadErrorCode(code: string): code is PluginWorkloadErrorCode {
  return ERROR_CODE_SET.has(code)
}

export function isKnownPluginWorkloadErrorReason(
  reason: string
): reason is PluginWorkloadErrorReason {
  return ERROR_REASON_SET.has(reason)
}