/**
 * Memory type definitions
 * Types for agent memory management with semantic entry types
 */

/**
 * Semantic memory entry types
 * Use-case agnostic types that describe the purpose of each entry
 * Memory types mirror action types for clarity and filtering
 */
export type MemoryEntryType =
  | 'context' // Pre-loaded context entry (before execution)
  | 'input' // User request or event payload
  | 'reasoning' // LLM thought process
  | 'tool-result' // Result from tool execution
  | 'delegation-result' // Result from sub-agent delegation (future)
  | 'error' // Error from failed action (tool error, validation error, etc.)

/**
 * Memory entry - represents a single entry in agent memory
 * Stored in agent memory, translated by adapters to vendor-specific formats
 */
export interface MemoryEntry {
  type: MemoryEntryType
  content: string
  timestamp: number
  turnNumber: number | null // Which turn/execution created this entry (1, 2, 3... for session turns, null for session memory or one-off executions)
  iterationNumber: number | null // Which iteration created this entry (0 = pre-iteration input, null = session memory/non-iteration-specific)
}

/**
 * Agent memory - Self-orchestrated memory with session + working storage
 * Agent has full control over what persists, framework handles auto-compaction
 */
export interface AgentMemory {
  /**
   * Session memory - Persists for session/conversation duration
   * Never auto-trimmed by framework
   * Agent-managed key-value store for critical information
   * Agent provides strings, framework wraps in MemoryEntry
   */
  sessionMemory: Record<string, MemoryEntry>

  /**
   * Working memory - Execution history
   * Automatically compacted by framework when needed
   * Agent doesn't control compaction
   */
  history: MemoryEntry[]
}

/**
 * Memory operations - Agent-directed memory management
 * Agent provides string content, framework wraps in MemoryEntry structure
 */
export interface MemoryOperations {
  /**
   * Add/update session memory
   * Agent provides string content, framework wraps in MemoryEntry
   */
  set?: Record<string, string> // key -> content string

  /**
   * Remove from session memory
   */
  delete?: string[] // array of keys to delete
}

/**
 * Memory status for agent awareness
 */
export interface MemoryStatus {
  // Session memory
  sessionMemoryKeys: number // Current count
  sessionMemoryLimit: number // Max allowed (default: 10)
  currentKeys: string[] // List of keys currently stored

  // History memory (token-based)
  historyPercent: number // 0-100 (percentage of token budget used)
  historyTokens: number // Current token count
  tokenBudget: number // Total token budget for memory
}

/**
 * Memory constraints (optional limits)
 */
export interface MemoryConstraints {
  maxSessionMemoryKeys?: number // Max session memory keys (default: 10)
  maxMemoryTokens?: number // Total token budget for all memory (default: 14000)
}
