@elevasis/core 0.1.0

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

@@ -0,0 +1,155 @@
+/**
+ * Agent-specific type definitions
+ * Types for autonomous agents with tools, memory, and constraints
+ */
+
+import type { Contract, ExecutionContext } from '../../base/types'
+import type { ResourceDefinition } from '../../../../platform/registry/types'
+import { Tool } from '../../tools/types'
+import type { AgentMemory } from '../memory/types'
+import type { LLMAdapter } from '../../llm/types'
+import type { ModelConfig } from '../../llm/model-info'
+import { AgentScopedLogger } from '../observability/logging'
+import { MemoryManager } from '../memory/manager'
+import type { ResourceMetricsConfig } from '../../../../operations/observability/types'
+import type { KnowledgeMap } from '../knowledge-map/types'
+import type { ExecutionInterface } from '../../interface/types'
+
+// Re-export memory types for backward compatibility
+export type { AgentMemory }
+
+/**
+ * Factory function for creating LLM adapters.
+ * Injected into the Agent class to decouple the engine from server-only provider SDKs.
+ * - API process: provides createLLMAdapter (real SDKs + process.env API keys)
+ * - SDK worker: provides PostMessageLLMAdapter (proxies via platform.call)
+ *
+ * Uses `any` for optional params so both the real createLLMAdapter (with typed
+ * AIUsageCollector/AICallContext) and the worker proxy (which ignores them) satisfy the type.
+ */
+export type LLMAdapterFactory = (
+  config: ModelConfig,
+  ...args: any[]
+) => LLMAdapter
+
+// Agent configuration
+export interface AgentConfig extends ResourceDefinition {
+  type: 'agent'
+
+  // Agent behavior
+  systemPrompt: string // System prompt defining agent behavior
+
+  // Execution constraints (simplified for v1)
+  constraints?: AgentConstraints
+
+  /**
+   * Session capability declaration (opt-in)
+   * If true, agent is designed for multi-turn session interactions
+   * Controls whether agent can use message action and appears in Sessions UI
+   *
+   * Use for:
+   * - Conversational agents with multi-turn interactions
+   * - Agents requiring persistent context across turns
+   * - Agents that need human-in-the-loop communication
+   */
+  sessionCapable?: boolean
+
+  /**
+   * Security level for system prompt hardening (auto-derived if omitted)
+   *
+   * - 'standard': Lightweight defense (3 rules) - default for non-session agents
+   * - 'hardened': Comprehensive defense (6 rules) - default for session-capable agents
+   * - 'none': No security prompt - for pure internal agents with no external input
+   *
+   * If omitted, derived from sessionCapable:
+   *   sessionCapable: true  -> 'hardened'
+   *   sessionCapable: false -> 'standard'
+   */
+  securityLevel?: 'standard' | 'hardened' | 'none'
+
+  /**
+   * Memory management preferences (opt-in)
+   * If provided, agent can use memoryOps to manage session memory
+   * If omitted, agent has no memory management capabilities
+   *
+   * Agent-specific guidance on what to preserve, when to persist, and what to clean up.
+   * This guidance is injected into the system prompt when memory management is enabled.
+   *
+   * Use for:
+   * - Conversational agents needing cross-turn context
+   * - Agents managing complex user preferences
+   * - Agents tracking decisions over multiple iterations
+   */
+  memoryPreferences?: string
+
+  // Lifecycle callbacks for observability (optional) - DEFERRED
+}
+
+// Execution constraints to prevent runaway agents
+export interface AgentConstraints {
+  // Agent execution control
+  maxIterations?: number // Prevent infinite loops
+  timeout?: number // Execution time limit (ms)
+
+  // Memory constraints
+  maxSessionMemoryKeys?: number // Max session memory keys (default: 10)
+  maxMemoryTokens?: number // Total token budget for all memory (default: 14000)
+}
+
+// Agent definition - pure configuration without instance state
+// Used by registry to define agents that can be instantiated with fresh memory
+export interface AgentDefinition {
+  config: AgentConfig
+  contract: Contract
+  tools: Tool[]
+
+  /**
+   * Model configuration for LLM execution
+   * Specifies provider, API key, and model-specific options
+   */
+  modelConfig: ModelConfig
+
+  /**
+   * Optional knowledge map for lazy-loading capabilities
+   * Enables agents to navigate organizational knowledge on-demand
+   */
+  knowledgeMap?: KnowledgeMap
+
+  /**
+   * Preload memory before execution starts
+   * Handles BOTH context loading AND session restoration
+   *
+   * @param context - Execution context (includes sessionId if session turn)
+   * @returns Initial AgentMemory state (sessionMemory entries + optionally history)
+   */
+  preloadMemory?: (context: ExecutionContext) => Promise<AgentMemory> | AgentMemory
+
+  /**
+   * Metrics configuration for ROI calculations
+   * Optional: Only needed if tracking automation savings
+   */
+  metricsConfig?: ResourceMetricsConfig
+
+  /**
+   * Execution interface configuration (optional)
+   * If provided, agent appears in Execution Runner UI
+   */
+  interface?: ExecutionInterface
+}
+
+/**
+ * Agent execution context
+ * Groups all state needed for agent execution phases
+ */
+export interface IterationContext {
+  config: AgentConfig
+  contract: Contract
+  toolRegistry: Map<string, Tool>
+  memoryManager: MemoryManager
+  executionContext: ExecutionContext
+  iteration: number
+  logger: AgentScopedLogger
+  modelConfig: ModelConfig
+  adapterFactory: LLMAdapterFactory
+  knowledgeMap?: KnowledgeMap
+}

package/src/execution/engine/agent/errors.ts

@@ -0,0 +1,251 @@
+/**
+ * Agent error classes
+ * Errors specific to agent execution and iteration
+ */
+
+import { ExecutionError } from '../base/errors'
+
+/**
+ * Thrown when agent initialization fails
+ *
+ * Severity: critical (agent cannot start without proper initialization)
+ * Category: agent
+ *
+ * @example
+ * ```typescript
+ * throw new AgentInitializationError(
+ *   'Failed to initialize agent: Invalid LLM configuration',
+ *   {
+ *     agentId: 'agent-123',
+ *     reason: 'missing_api_key',
+ *     llmModel: 'gpt-4'
+ *   }
+ * )
+ * ```
+ */
+export class AgentInitializationError extends ExecutionError {
+  readonly type = 'agent_initialization_error' as const
+  readonly severity = 'critical' as const
+  readonly category = 'agent' as const
+
+  constructor(message: string, context?: Record<string, unknown>) {
+    super(message, context)
+  }
+}
+
+/**
+ * Thrown when an agent iteration fails during execution
+ *
+ * Severity: warning (iteration failure that may be retried or requires user intervention)
+ * Category: agent
+ *
+ * @example
+ * ```typescript
+ * throw new AgentIterationError(
+ *   'Agent iteration failed: Tool execution timeout',
+ *   {
+ *     agentId: 'agent-123',
+ *     iterationNumber: 5,
+ *     toolName: 'web_search',
+ *     attemptCount: 2
+ *   }
+ * )
+ * ```
+ */
+export class AgentIterationError extends ExecutionError {
+  readonly type = 'agent_iteration_error' as const
+  readonly severity = 'warning' as const
+  readonly category = 'agent' as const
+
+  constructor(message: string, context?: Record<string, unknown>) {
+    super(message, context)
+  }
+}
+
+/**
+ * Thrown when agent completion phase fails
+ *
+ * Severity: warning (completion failure that may require retry or user intervention)
+ * Category: agent
+ *
+ * @example
+ * ```typescript
+ * throw new AgentCompletionError(
+ *   'Failed to generate final output: LLM timeout',
+ *   {
+ *     agentId: 'agent-123',
+ *     attempts: 1,
+ *     reason: 'llm_timeout'
+ *   }
+ * )
+ * ```
+ */
+export class AgentCompletionError extends ExecutionError {
+  readonly type = 'agent_completion_error' as const
+  readonly severity = 'warning' as const
+  readonly category = 'agent' as const
+
+  constructor(message: string, context?: Record<string, unknown>) {
+    super(message, context)
+  }
+}
+
+/**
+ * Thrown when agent output validation fails
+ *
+ * Severity: info (validation failure indicating agent output doesn't meet expected schema)
+ * Category: validation
+ *
+ * @example
+ * ```typescript
+ * throw new AgentOutputValidationError(
+ *   'Agent output validation failed: Missing required field "result"',
+ *   {
+ *     agentId: 'agent-123',
+ *     iterationNumber: 3,
+ *     expectedSchema: 'CompletionSchema',
+ *     field: 'result'
+ *   }
+ * )
+ * ```
+ */
+export class AgentOutputValidationError extends ExecutionError {
+  readonly type = 'agent_output_validation_error' as const
+  readonly severity = 'info' as const
+  readonly category = 'validation' as const
+
+  constructor(message: string, context?: Record<string, unknown>) {
+    super(message, context)
+  }
+}
+
+/**
+ * Thrown when agent exceeds maximum iterations without completing
+ *
+ * Severity: critical (agent failed to complete within allowed iterations)
+ * Category: agent
+ *
+ * @example
+ * ```typescript
+ * throw new AgentMaxIterationsError(
+ *   'Agent exceeded maximum iterations (10)',
+ *   {
+ *     maxIterations: 10,
+ *     currentIteration: 10
+ *   }
+ * )
+ * ```
+ */
+export class AgentMaxIterationsError extends ExecutionError {
+  readonly type = 'agent_max_iterations_error' as const
+  readonly severity = 'critical' as const
+  readonly category = 'agent' as const
+
+  constructor(message: string, context?: { maxIterations: number; currentIteration: number }) {
+    super(message, context)
+  }
+}
+
+/**
+ * Thrown when agent execution exceeds its configured timeout ceiling
+ *
+ * Severity: critical (execution terminated, no further iterations)
+ * Category: agent
+ *
+ * @example
+ * ```typescript
+ * throw new AgentTimeoutError(
+ *   'Agent execution exceeded timeout (300000ms)',
+ *   {
+ *     timeout: 300000,
+ *     iteration: 3
+ *   }
+ * )
+ * ```
+ */
+export class AgentTimeoutError extends ExecutionError {
+  readonly type = 'agent_timeout_error' as const
+  readonly severity = 'critical' as const
+  readonly category = 'agent' as const
+
+  constructor(message: string, context?: { timeout: number; iteration: number }) {
+    super(message, context)
+  }
+}
+
+/**
+ * Thrown when a user cancels a running execution via the cancel endpoint.
+ * The AbortController fires with reason 'user_cancellation', which the
+ * iterate() between-iteration check distinguishes from 'timeout'.
+ *
+ * Severity: warning (user-initiated, not an unexpected failure)
+ * Category: agent
+ *
+ * @example
+ * ```typescript
+ * throw new AgentCancellationError('Execution cancelled by user', { iteration: 3 })
+ * ```
+ */
+export class AgentCancellationError extends ExecutionError {
+  readonly type = 'agent_cancellation_error' as const
+  readonly severity = 'warning' as const
+  readonly category = 'agent' as const
+
+  constructor(message: string, context?: { iteration: number }) {
+    super(message, context)
+  }
+}
+
+/**
+ * Thrown when a running execution is flagged as stalled by the heartbeat
+ * monitor (pg_cron). The AbortController fires with reason 'stalled',
+ * which the iterate() between-iteration check distinguishes from 'timeout'.
+ *
+ * Severity: critical (execution terminated, no further iterations)
+ * Category: agent
+ *
+ * @example
+ * ```typescript
+ * throw new AgentStalledError(
+ *   'Execution stalled: no heartbeat received within threshold',
+ *   { iteration: 5 }
+ * )
+ * ```
+ */
+export class AgentStalledError extends ExecutionError {
+  readonly type = 'agent_stalled_error' as const
+  readonly severity = 'critical' as const
+  readonly category = 'agent' as const
+
+  constructor(message: string, context?: { iteration: number }) {
+    super(message, context)
+  }
+}
+
+/**
+ * Thrown when memory entry validation fails
+ *
+ * Severity: info (validation failure indicating improper memory entry structure)
+ * Category: validation
+ *
+ * @example
+ * ```typescript
+ * throw new AgentMemoryValidationError(
+ *   'turnNumber required for history entries (use null for session memory)',
+ *   {
+ *     entryType: 'reasoning',
+ *     missingField: 'turnNumber',
+ *     iterationNumber: 1
+ *   }
+ * )
+ * ```
+ */
+export class AgentMemoryValidationError extends ExecutionError {
+  readonly type = 'agent_memory_validation_error' as const
+  readonly severity = 'info' as const
+  readonly category = 'validation' as const
+
+  constructor(message: string, context?: Record<string, unknown>) {
+    super(message, context)
+  }
+}

package/src/execution/engine/agent/index.ts

@@ -0,0 +1,78 @@
+/**
+ * Agent module exports
+ * Core agent framework for autonomous AI agents
+ */
+
+// Agent class
+export { Agent } from './core/agent'
+
+// Types
+export type {
+  AgentConfig,
+  AgentConstraints,
+  AgentDefinition,
+  IterationContext,
+  LLMAdapterFactory
+} from './core/types'
+
+// Memory
+export type { AgentMemory, MemoryEntry, MemoryEntryType } from './memory/types'
+export { addToolError, loadSessionMemory, validateMemoryKeyOwnership } from './memory/utils'
+export { isToolOwnedKey, isActionOwnedKey, isLLMOwnedKey, getKeyOwner } from './memory/domains'
+
+// Tools & Actions
+export type { Tool, ToolDefinition } from '../tools/types'
+export type { AgentAction, ToolCallAction, CompleteAction, MessageAction, NavigateKnowledgeAction } from './actions/types'
+export {
+  ToolCallActionSchema,
+  CompleteActionSchema,
+  MessageActionSchema,
+  NavigateKnowledgeActionSchema,
+  AgentActionSchema
+} from './actions/types'
+
+// Knowledge Map
+export type { KnowledgeMap, KnowledgeNode, KnowledgeContent, KnowledgeMapState } from './knowledge-map/types'
+export { reloadKnowledgeMapTools } from './knowledge-map/utils'
+
+// LLM exports (re-exported from llm module)
+export type { LLMAdapter, LLMGenerateRequest, LLMGenerateResponse, LLMMessage } from '../llm/types'
+export type { LLMModel, ModelConfig } from '../llm/model-info'
+
+// LLM type exports (browser-safe - types only)
+// NOTE: Implementations (OpenAIAdapter, createLLMAdapter) are server-only - import from @repo/core/server
+export type { OpenAIAdapterConfig } from '../llm/adapters/server/openai'
+
+// Logging - Simplified 2-event model (lifecycle + iteration)
+export type {
+  AgentLogContext,
+  AgentLogMessage,
+  AgentLifecycle,
+  LifecycleStage,
+  IterationEventType,
+  AgentLifecycleEvent,
+  AgentIterationEvent,
+  ActionPlaceholderData
+} from './observability/logging'
+
+// Logging - Type Guards (2 primary + helpers)
+export {
+  // Primary type guards
+  isLifecycleEvent,
+  isIterationEvent,
+  // Helper type guards
+  isInitialization,
+  isIteration,
+  isCompletion,
+  isReasoningEvent,
+  isActionEvent,
+  isToolUseAction,
+  isIterationContext,
+  // Logging utilities
+  createAgentLogger
+} from './observability/logging'
+
+// Utilities - Currently empty, reserved for future functions
+
+// Agent errors
+export * from './errors'