/**
 * Shared HITL (Human-in-the-Loop) constants and enums.
 *
 * Single source of truth for approval-related values consumed by
 * the agents library, host backend, and browser extension.
 *
 * @module approval/constants
 */

// ============================================================================
// Execution Context
// ============================================================================

/**
 * Execution context determines whether HITL approval is required.
 *
 * - `INTERACTIVE`: User is present in the chat session — approval prompts are shown.
 * - `SCHEDULED`: Automated/scheduled execution — all approvals are auto-granted.
 * - `HANDOFF`: Agent is running as a handoff/delegate/workflow target — approvals
 *   are auto-granted so the autonomous multi-agent pipeline isn't blocked.
 *   The primary agent retains HITL; only handoff agents bypass it.
 */
export enum ExecutionContext {
  INTERACTIVE = 'interactive',
  SCHEDULED = 'scheduled',
  HANDOFF = 'handoff',
}

// ============================================================================
// Approval Policy
// ============================================================================

/**
 * Static approval policy values.
 *
 * - `ALWAYS`: Every tool call requires approval (strictest).
 * - `NEVER`: No tool call requires approval (used for auto-approved tools).
 */
export enum ApprovalPolicy {
  ALWAYS = 'always',
  NEVER = 'never',
}

// ============================================================================
// Approval Tier
// ============================================================================

/**
 * Three-tier policy evaluation pipeline.
 * Higher tiers are checked first; once a tier matches, lower tiers are skipped.
 *
 * - `AUTO_APPROVE`: Built-in tools that always skip approval (Tier 1).
 * - `RULE_BASED`: Per-tool argument-aware rules (Tier 2).
 * - `KEYWORD_FALLBACK`: Token-based keyword matching on tool name (Tier 3).
 */
export enum ApprovalTier {
  AUTO_APPROVE = 'auto_approve',
  RULE_BASED = 'rule_based',
  KEYWORD_FALLBACK = 'keyword_fallback',
}

// ============================================================================
// Risk Level
// ============================================================================

/**
 * Risk classification for tool calls.
 * Used for audit logging and future UI customization (e.g., showing risk badges).
 *
 * - `NONE`: Read-only, no side effects (search, list, get).
 * - `LOW`: Minor side effects (bookmark, star, mark as read).
 * - `MEDIUM`: User-specific mutations (send email to known contact).
 * - `HIGH`: Destructive or irreversible (delete, modify critical data).
 * - `CRITICAL`: Multi-system impact (transfer funds, delete account).
 */
export enum RiskLevel {
  NONE = 'none',
  LOW = 'low',
  MEDIUM = 'medium',
  HIGH = 'high',
  CRITICAL = 'critical',
}

// ============================================================================
// Action Category
// ============================================================================

/**
 * Semantic category for tool actions.
 * Maps action keywords to high-level intent for risk classification.
 */
export enum ActionCategory {
  READ = 'read',
  WRITE = 'write',
  DELETE = 'delete',
  SEND = 'send',
  EXECUTE = 'execute',
  FINANCIAL = 'financial',
  ACCOUNT = 'account',
}

// ============================================================================
// MCP Delimiter
// ============================================================================

/**
 * Delimiter used in MCP tool names to separate the tool name from the server key.
 *
 * Example: `send_email_mcp_outlook` → tool = `send_email`, server = `outlook`
 *
 * Must match the host data-provider delimiter constant.
 */
export const MCP_DELIMITER = '_mcp_';