@elevasis/core 0.1.0

package/src/execution/engine/agent/memory/manager.ts

@@ -0,0 +1,365 @@
+/**
+ * Memory Manager
+ * Encapsulates all memory operations with ultra-simple agent API
+ * Agent provides strings, framework handles wrapping and auto-compaction
+ */
+
+import type { AgentMemory, MemoryEntry, MemoryStatus, MemoryConstraints } from './types'
+import { estimateTokens } from '../../../../platform/utils'
+import type { AgentScopedLogger } from '../observability/logging'
+import { AgentMemoryValidationError } from '../errors'
+import {
+  MAX_SESSION_MEMORY_KEYS,
+  MAX_MEMORY_TOKENS,
+  MAX_SINGLE_ENTRY_TOKENS,
+  MAX_TOOL_RESULT_TOKENS
+} from '../../../../platform/constants/limits'
+
+/**
+ * Truncate tool result content if it exceeds the token limit.
+ * Uses character-based estimation (1 token ~ 3.5 chars, matching estimateTokens).
+ * Appends a notice so the agent knows data was cut.
+ *
+ * @param content - Raw tool result string
+ * @param maxTokens - Maximum allowed tokens
+ * @returns Original content if under limit, truncated content with notice otherwise
+ */
+export function truncateToolResult(content: string, maxTokens: number): string {
+  const estimated = estimateTokens(content)
+  if (estimated <= maxTokens) return content
+
+  // Use same ratio as estimateTokens (3.5 chars per token)
+  const maxChars = Math.floor(maxTokens * 3.5)
+  const truncated = content.slice(0, maxChars)
+  const omitted = estimated - maxTokens
+  return (
+    truncated +
+    `\n\n[Response truncated — estimated ${omitted} tokens omitted. Use more specific filters to get smaller results.]`
+  )
+}
+
+/**
+ * Memory Manager - Agent memory orchestration
+ * Provides ultra-simple API for agents (strings only)
+ * Handles automatic compaction and token management
+ */
+export class MemoryManager {
+  private cachedSnapshot?: AgentMemory
+
+  constructor(
+    private memory: AgentMemory,
+    private constraints: MemoryConstraints = {},
+    private logger?: AgentScopedLogger
+  ) {}
+
+  // === Agent Operations (Ultra-Simple) ===
+
+  /**
+   * Set session memory entry (agent provides string, framework wraps it)
+   * @param key - Session memory key
+   * @param content - String content from agent
+   */
+  set(key: string, content: string): void {
+    // Check single entry token limit
+    const entryTokens = estimateTokens(content)
+    if (entryTokens > MAX_SINGLE_ENTRY_TOKENS) {
+      const truncateTime = Date.now()
+      this.logger?.action(
+        'memory-truncate',
+        `Single entry exceeds token limit (${entryTokens}/${MAX_SINGLE_ENTRY_TOKENS}): ${key}`,
+        0,
+        truncateTime,
+        truncateTime,
+        0
+      )
+      // Truncate content to fit limit
+      const maxChars = MAX_SINGLE_ENTRY_TOKENS * 4
+      content = content.slice(0, maxChars) + '... [truncated]'
+    }
+
+    this.memory.sessionMemory[key] = {
+      type: 'context',
+      content,
+      timestamp: Date.now(),
+      turnNumber: null, // Session memory entries are not turn-specific
+      iterationNumber: null // Session memory entries are not iteration-specific
+    }
+  }
+
+  /**
+   * Get session memory entry content
+   * @param key - Session memory key
+   * @returns String content if exists, undefined otherwise
+   */
+  get(key: string): string | undefined {
+    const entry = this.memory.sessionMemory[key]
+    return entry?.content
+  }
+
+  /**
+   * Delete session memory entry
+   * @param key - Key to delete
+   * @returns True if key existed and was deleted
+   */
+  delete(key: string): boolean {
+    if (key in this.memory.sessionMemory) {
+      delete this.memory.sessionMemory[key]
+      return true
+    }
+    return false
+  }
+
+  // === Framework Operations (Automatic) ===
+
+  /**
+   * Add entry to history (called by framework after tool results, reasoning, etc.)
+   * Automatically sets timestamp to current time
+   * @param entry - Memory entry to add (without timestamp - auto-generated)
+   */
+  addToHistory(entry: Omit<MemoryEntry, 'timestamp'>): void {
+    // Validate turnNumber is provided for history entries (use null for session memory)
+    if (entry.turnNumber === undefined && entry.type !== 'context') {
+      throw new AgentMemoryValidationError('turnNumber required for history entries (use null for session memory)', {
+        entryType: entry.type,
+        missingField: 'turnNumber',
+        iterationNumber: entry.iterationNumber
+      })
+    }
+
+    // Truncate tool-result content if it exceeds the tool result token limit
+    let content = entry.content
+    if (entry.type === 'tool-result') {
+      const before = content
+      content = truncateToolResult(content, MAX_TOOL_RESULT_TOKENS)
+      if (content !== before) {
+        const truncateTime = Date.now()
+        this.logger?.action(
+          'memory-tool-result-truncate',
+          `Tool result truncated (${estimateTokens(before)} -> ${MAX_TOOL_RESULT_TOKENS} tokens)`,
+          entry.iterationNumber ?? 0,
+          truncateTime,
+          truncateTime,
+          0
+        )
+      }
+    }
+
+    this.memory.history.push({
+      ...entry,
+      content,
+      timestamp: Date.now()
+    })
+    // Auto-compact after adding (if needed)
+    this.autoCompact()
+  }
+
+  /**
+   * Auto-compact history if approaching token budget
+   * Uses preserve-anchors strategy: keep first + recent entries
+   */
+  autoCompact(): void {
+    const status = this.getStatus()
+
+    // Auto-compact when at 100% of token budget
+    if (status.historyPercent >= 100) {
+      const before = this.memory.history.length
+
+      // Preserve-anchors strategy: first entry + last 10 entries
+      this.memory.history = [
+        this.memory.history[0], // First (original input)
+        ...this.memory.history.slice(-10) // Last 10
+      ]
+
+      const compactTime = Date.now()
+      this.logger?.action(
+        'memory-auto-compact',
+        `Auto-compacted: ${before} -> ${this.memory.history.length} entries`,
+        0,
+        compactTime,
+        compactTime,
+        0
+      )
+    }
+  }
+
+  /**
+   * Enforce hard limits (called before LLM request)
+   * Emergency fallback if agent exceeds limits
+   */
+  enforceHardLimits(): void {
+    const maxSessionMemoryKeys = this.constraints.maxSessionMemoryKeys || MAX_SESSION_MEMORY_KEYS
+
+    // Check session memory count
+    const sessionMemoryKeys = Object.keys(this.memory.sessionMemory)
+    if (sessionMemoryKeys.length > maxSessionMemoryKeys) {
+      const limitTime = Date.now()
+      this.logger?.action(
+        'memory-limit-exceeded',
+        `Session memory exceeds hard limit (${sessionMemoryKeys.length}/${maxSessionMemoryKeys})`,
+        0,
+        limitTime,
+        limitTime,
+        0
+      )
+
+      // Remove oldest entries by timestamp
+      const sorted = Object.entries(this.memory.sessionMemory).sort((a, b) => a[1].timestamp - b[1].timestamp)
+
+      this.memory.sessionMemory = Object.fromEntries(sorted.slice(-maxSessionMemoryKeys))
+    }
+
+    // Check total token budget (emergency compaction)
+    const status = this.getStatus()
+    const maxTokens = this.constraints.maxMemoryTokens || MAX_MEMORY_TOKENS
+
+    if (status.historyTokens > maxTokens) {
+      const before = this.memory.history.length
+      const emergencyStartTime = Date.now()
+      this.logger?.action(
+        'memory-emergency',
+        `Total memory exceeds token budget (${status.historyTokens}/${maxTokens}), forcing emergency compaction`,
+        0,
+        emergencyStartTime,
+        emergencyStartTime,
+        0
+      )
+
+      // Emergency: Aggressively compact history
+      this.memory.history = [
+        this.memory.history[0],
+        ...this.memory.history.slice(-5) // Keep only last 5
+      ]
+
+      const emergencyEndTime = Date.now()
+      this.logger?.action(
+        'memory-emergency-compact',
+        `Emergency compaction: ${before} -> ${this.memory.history.length} entries`,
+        0,
+        emergencyStartTime,
+        emergencyEndTime,
+        emergencyEndTime - emergencyStartTime
+      )
+    }
+  }
+
+  /**
+   * Get history length (for logging and introspection)
+   * @returns Number of entries in history
+   */
+  getHistoryLength(): number {
+    return this.memory.history.length
+  }
+
+  /**
+   * Get memory status for agent awareness
+   * @returns Memory status with token usage and key counts
+   */
+  getStatus(): MemoryStatus {
+    const sessionMemoryKeys = Object.keys(this.memory.sessionMemory)
+
+    // Calculate tokens
+    const sessionMemoryContent = Object.values(this.memory.sessionMemory)
+      .map((entry) => entry.content)
+      .join('')
+    const historyContent = this.memory.history.map((entry) => entry.content).join('')
+    const sessionMemoryTokens = estimateTokens(sessionMemoryContent)
+    const historyTokens = estimateTokens(historyContent)
+    const totalTokens = sessionMemoryTokens + historyTokens
+
+    // Token budget
+    const tokenBudget = this.constraints.maxMemoryTokens || MAX_MEMORY_TOKENS
+    const sessionMemoryLimit = this.constraints.maxSessionMemoryKeys || MAX_SESSION_MEMORY_KEYS
+
+    return {
+      sessionMemoryKeys: sessionMemoryKeys.length,
+      sessionMemoryLimit,
+      currentKeys: sessionMemoryKeys,
+      historyPercent: Math.round((totalTokens / tokenBudget) * 100),
+      historyTokens: totalTokens,
+      tokenBudget
+    }
+  }
+
+  /**
+   * Create memory snapshot for persistence
+   * Caches snapshot internally for later retrieval
+   * @returns Deep copy of current memory state
+   */
+  toSnapshot(): AgentMemory {
+    this.cachedSnapshot = structuredClone(this.memory)
+    return this.cachedSnapshot
+  }
+
+  /**
+   * Get cached memory snapshot
+   * Returns snapshot created by toSnapshot()
+   * @returns Cached snapshot (undefined if toSnapshot() not called yet)
+   */
+  getSnapshot(): AgentMemory | undefined {
+    return this.cachedSnapshot
+  }
+
+  /**
+   * Build context string for LLM
+   * Serializes sessionmemory + history memory with clear sections
+   * Shows current iteration entries FIRST (reverse chronological) for LLM attention
+   * @param currentIteration - Current iteration number (0 = pre-iteration)
+   * @param currentTurn - Current turn number (optional, for session context filtering)
+   * @returns Formatted memory context for LLM prompt
+   */
+  toContext(currentIteration: number, currentTurn?: number): string {
+    const status = this.getStatus()
+
+    // Split by turn and iteration number
+    // DUAL FILTERING: Turn scope first (if provided), then iteration scope
+    // null iterations are session memory entries (excluded from history context)
+    // undefined/null turnNumbers are treated as legacy entries (pre-migration) or one-off executions
+    const currentContext = this.memory.history
+      .filter(
+        (entry) =>
+          (!currentTurn || entry.turnNumber === currentTurn || entry.turnNumber === undefined) &&
+          entry.iterationNumber === currentIteration
+      )
+      .reverse() // Most recent first (LLM positional bias)
+
+    const earlierContext = this.memory.history.filter(
+      (entry) =>
+        (!currentTurn || entry.turnNumber === currentTurn || entry.turnNumber === undefined) &&
+        entry.iterationNumber !== null &&
+        entry.iterationNumber < currentIteration
+    )
+    // Earlier entries stay chronological
+
+    // Format entry with simple label
+    const formatEntry = (entry: MemoryEntry): string => {
+      const label = `[${entry.type.toUpperCase()}]`
+      return `${label}\n${entry.content}`
+    }
+
+    // Serialize session memory
+    const sessionMemoryContext = Object.entries(this.memory.sessionMemory)
+      .map(([key, entry]) => `[SESSION:${key}]\n${entry.content}`)
+      .join('\n\n')
+
+    const currentSection = currentContext.map(formatEntry).join('\n\n')
+    const earlierSection =
+      earlierContext.length > 0 ? earlierContext.map(formatEntry).join('\n\n') : '(no earlier context)'
+
+    return `
+=== MEMORY STATUS ===
+${status.sessionMemoryKeys}/${status.sessionMemoryLimit} session keys
+${status.historyPercent}% of token budget
+
+=== SESSION MEMORY (Persists for conversation) ===
+${sessionMemoryContext || '(empty)'}
+
+=== ITERATION ${currentIteration} - CURRENT CONTEXT ===
+
+${currentSection}
+
+=== EARLIER CONTEXT ===
+
+${earlierSection}
+`.trim()
+  }
+}

package/src/execution/engine/agent/memory/processor.ts

@@ -0,0 +1,66 @@
+/**
+ * Memory Phase Processor
+ * Handles memory operations from LLM responses
+ * Phase 2 of iteration: REASON -> MEMORY -> ACT
+ */
+
+import type { LLMIterationResponse } from '../reasoning/types'
+import type { MemoryManager } from './manager'
+import type { AgentScopedLogger } from '../observability/logging'
+import { validateMemoryKeyOwnership } from './utils'
+
+/**
+ * Process memory operations from LLM response
+ * Applies agent-directed memory management (set/delete)
+ *
+ * @param memoryManager - Memory manager instance
+ * @param response - LLM iteration response with optional memoryOps
+ * @param logger - Scoped logger for memory operations
+ * @param iteration - Current iteration number
+ */
+export async function processMemory(
+  memoryManager: MemoryManager,
+  response: LLMIterationResponse,
+  logger: AgentScopedLogger,
+  iteration: number
+): Promise<void> {
+  if (!response.memoryOps) return
+
+  const { memoryOps } = response
+
+  // Apply set operations with domain validation
+  if (memoryOps.set) {
+    for (const [key, content] of Object.entries(memoryOps.set)) {
+      // Validate ownership - skip if system-managed
+      if (!validateMemoryKeyOwnership(key, logger, iteration)) {
+        continue
+      }
+
+      const startTime = Date.now()
+      // Auto-stringify non-string values (arrays, objects, etc.)
+      const stringValue = typeof content === 'string' ? content : JSON.stringify(content)
+      memoryManager.set(key, stringValue)
+      const endTime = Date.now()
+      logger.action('memory-set', `Set: ${key}`, iteration, startTime, endTime, endTime - startTime)
+    }
+  }
+
+  // Apply delete operations with domain validation
+  if (memoryOps.delete) {
+    for (const key of memoryOps.delete) {
+      // Validate ownership - skip if system-managed
+      if (!validateMemoryKeyOwnership(key, logger, iteration)) {
+        continue
+      }
+
+      const startTime = Date.now()
+      const deleted = memoryManager.delete(key)
+      const endTime = Date.now()
+      if (deleted) {
+        logger.action('memory-delete', `Deleted: ${key}`, iteration, startTime, endTime, endTime - startTime)
+      } else {
+        logger.action('memory-delete-missing', `Attempted to delete non-existent key: ${key}`, iteration, startTime, endTime, endTime - startTime)
+      }
+    }
+  }
+}

package/src/execution/engine/agent/memory/types.ts

@@ -0,0 +1,90 @@
+/**
+ * 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)
+}

package/src/execution/engine/agent/memory/utils.ts

@@ -0,0 +1,134 @@
+/**
+ * Memory utilities
+ * Helper functions for memory manipulation (formatting, snapshots)
+ */
+
+import type { AgentMemory } from './types'
+import type { ExecutionContext } from '../../base/types'
+import type { SupabaseClient } from '../../../../supabase'
+
+/**
+ * Load session memory from database
+ *
+ * Standard pattern for preloadMemory callback:
+ * - If sessionId exists: restore memory snapshot from database
+ * - If no sessionId: return fresh memory (one-off task)
+ * - Handles errors gracefully by returning empty memory
+ *
+ * @param supabaseClient - Supabase client instance
+ * @param context - Execution context (must include organizationId, optional sessionId)
+ * @returns Agent memory (restored from DB or fresh)
+ *
+ * @example
+ * ```typescript
+ * import { loadSessionMemory } from '@repo/core'
+ * import { supabaseClient } from '@repo/core/server'
+ *
+ * async function preloadMemory(context: ExecutionContext): Promise<AgentMemory> {
+ *   return loadSessionMemory(supabaseClient, context)
+ * }
+ * ```
+ */
+export async function loadSessionMemory(
+  supabaseClient: SupabaseClient,
+  context: ExecutionContext
+): Promise<AgentMemory> {
+  // If session turn, restore memory snapshot from database
+  if (context.sessionId) {
+    const { data: session, error } = await supabaseClient
+      .from('sessions')
+      .select('memory_snapshot')
+      .eq('session_id', context.sessionId)
+      .eq('organization_id', context.organizationId)
+      .single()
+
+    if (error) {
+      console.error('Failed to load session from DB', {
+        sessionId: context.sessionId,
+        error: error.message
+      })
+      return { sessionMemory: {}, history: [] }
+    }
+
+    const result = (session?.memory_snapshot as unknown as AgentMemory) || { sessionMemory: {}, history: [] }
+    return result
+  }
+
+  // One-off task: start with fresh memory
+  return { sessionMemory: {}, history: [] }
+}
+
+// ============================================================================
+// Memory Helpers
+// Utility functions for memory manipulation during action execution
+// ============================================================================
+
+import type { ToolCallAction } from '../actions/types'
+import type { MemoryManager } from './manager'
+import type { AgentScopedLogger } from '../observability/logging'
+import { isToolOwnedKey, isActionOwnedKey, getKeyOwner } from './domains'
+
+/**
+ * Add tool execution error to memory
+ * Errors are stored as 'error' type entries and returned to LLM as tool results
+ * This allows the LLM to recover from errors and try alternative approaches
+ *
+ * @param memoryManager - Memory manager to add error to
+ * @param action - Tool call that failed
+ * @param errorMessage - Error description
+ * @param iteration - Iteration number when error occurred
+ * @param turnNumber - Turn number when error occurred (optional, defaults to null for one-off executions)
+ * @param metadata - Structured error metadata from ToolingError (optional)
+ */
+export function addToolError(
+  memoryManager: MemoryManager,
+  action: ToolCallAction,
+  errorMessage: string,
+  iteration: number,
+  turnNumber: number | null = null,
+  metadata?: {
+    errorType?: string
+    severity?: string
+    isRetryable?: boolean
+  }
+): void {
+  memoryManager.addToHistory({
+    type: 'error',
+    content: JSON.stringify({
+      error: errorMessage,
+      toolName: action.name,
+      toolCallId: action.id,
+      ...(metadata?.errorType && { errorType: metadata.errorType }),
+      ...(metadata?.severity && { severity: metadata.severity }),
+      ...(metadata?.isRetryable !== undefined && { isRetryable: metadata.isRetryable })
+    }),
+    turnNumber,
+    iterationNumber: iteration
+  })
+}
+
+/**
+ * Validate memory key ownership
+ * Prevents LLM from updating system-managed keys (tool-owned or action-owned)
+ *
+ * @param key - Memory key to validate
+ * @param logger - Logger for rejected operations
+ * @param iteration - Current iteration number
+ * @returns true if key can be updated by LLM, false if rejected
+ */
+export function validateMemoryKeyOwnership(key: string, logger: AgentScopedLogger, iteration: number): boolean {
+  // VALIDATION: Prevent LLM from updating system-managed keys
+  if (isToolOwnedKey(key) || isActionOwnedKey(key)) {
+    const owner = getKeyOwner(key)
+    logger.action(
+      'memory-set-rejected',
+      `Rejected LLM update to ${owner}-managed key: ${key}`,
+      iteration,
+      Date.now(),
+      Date.now(),
+      0
+    )
+    return false
+  }
+  return true
+}