@elevasis/core 0.7.1 → 0.8.0

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

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

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

@@ -1,134 +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
-}
+/**
+ * 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
+}