@elevasis/core 0.7.1 → 0.8.2

package/src/execution/engine/agent/reasoning/request-builder.ts

@@ -1,169 +1,169 @@
-/**
- * LLM Request Builder
- * Constructs universal LLMRequest from execution context using modular prompt system
- */
-
-import type { z } from 'zod'
-import type { IterationContext } from '../core/types'
-import type { ToolDefinition } from '../../tools/types'
-import type { KnowledgeMap } from '../knowledge-map/types'
-import { zodToJsonSchema } from '@alcyone-labs/zod-to-json-schema'
-import { buildSecurityPrompt } from './prompt-sections/security'
-import { buildBaseActionsPrompt } from './prompt-sections/base-actions'
-import { buildKnowledgeMapPrompt } from './prompt-sections/knowledge-map'
-import { buildToolsPrompt } from './prompt-sections/tools'
-import { buildMemoryPrompt, type MemoryStatus } from './prompt-sections/memory'
-import { buildCompletionPrompt } from './prompt-sections/completion'
-
-/**
- * Options for system prompt generation
- */
-export interface SystemPromptOptions {
-  /** Security level for prompt injection defense */
-  securityLevel: 'standard' | 'hardened' | 'none'
-  /** Whether to include message action (session-based agents only) */
-  includeMessageAction: boolean
-  /** Whether to include navigate-knowledge action (knowledge map present) */
-  includeNavigateKnowledge: boolean
-  /** Knowledge map with nodes (optional) */
-  knowledgeMap?: KnowledgeMap
-  /** Available tools */
-  tools: ToolDefinition[]
-  /** Current memory status */
-  memoryStatus: MemoryStatus
-  /** Output schema for completion guidance (optional) */
-  outputSchema?: z.ZodSchema
-  /** Memory preferences for opt-in memory management (optional string) */
-  memoryPreferences?: string
-}
-
-/**
- * Builds complete system prompt from modular sections
- *
- * Composition order:
- * 0. Security rules (standard/hardened, or omitted if 'none')
- * 1. Base actions (conditional message action based on session context)
- * 2. Knowledge map (if present)
- * 3. Tools (if present)
- * 4. Memory management (CONDITIONAL - only if preferences provided)
- * 5. Task completion
- * 6. Agent-specific instructions
- *
- * @param agentPrompt - Agent-specific instructions
- * @param options - Prompt configuration options
- * @returns Complete system prompt string
- */
-function buildSystemPrompt(agentPrompt: string, options: SystemPromptOptions): string {
-  const sections: string[] = []
-
-  // 0. Security rules (first position for maximum LLM attention)
-  const securitySection = buildSecurityPrompt(options.securityLevel)
-  if (securitySection) {
-    sections.push(securitySection)
-  }
-
-  // 1. Base actions (with conditional message and navigate-knowledge actions)
-  sections.push(buildBaseActionsPrompt(options.includeMessageAction, options.includeNavigateKnowledge))
-
-  // 2. Knowledge map (if present)
-  const knowledgeMapSection = buildKnowledgeMapPrompt(options.knowledgeMap)
-  if (knowledgeMapSection) {
-    sections.push(knowledgeMapSection)
-  }
-
-  // 3. Tools (if present)
-  const toolsSection = buildToolsPrompt(options.tools)
-  if (toolsSection) {
-    sections.push(toolsSection)
-  }
-
-  // 4. Memory management (CONDITIONAL - only if preferences provided)
-  // Conservative approach: Keep memoryOps in schema, but skip prompt if no preferences
-  if (options.memoryPreferences) {
-    sections.push(buildMemoryPrompt(options.memoryStatus, options.memoryPreferences))
-  }
-
-  // 5. Task completion guidance (always included)
-  sections.push(buildCompletionPrompt(options.outputSchema))
-
-  // 6. Agent-specific instructions (separator + prompt)
-  sections.push('---\n')
-  sections.push('# AGENT-SPECIFIC INSTRUCTIONS\n\n')
-  sections.push(agentPrompt)
-
-  return sections.join('\n')
-}
-
-/**
- * Build universal LLM iteration request from current state
- * Combines system prompt, tools, constraints, and memory using modular prompt builder
- *
- * @param iterationContext - Agent execution context
- * @returns Agent iteration request data
- */
-export function buildReasoningRequest(iterationContext: IterationContext): {
-  systemPrompt: string
-  tools: ToolDefinition[]
-  constraints: { maxOutputTokens?: number; temperature?: number }
-  memoryContext: string
-  includeMessageAction: boolean
-  includeNavigateKnowledge: boolean
-  includeMemoryOps: boolean
-} {
-  // Build tool definitions for system prompt from registry
-  const tools = Array.from(iterationContext.toolRegistry.values())
-  const toolDefinitions = tools.map((tool) => ({
-    name: tool.name,
-    description: tool.description,
-    inputSchema: zodToJsonSchema(tool.inputSchema as z.ZodSchema)
-  }))
-
-  // Get memory status for system prompt
-  const memoryStatus = iterationContext.memoryManager.getStatus()
-
-  // Agent capability: explicit session support declaration
-  // Controls whether message action is available in prompts
-  const isSessionCapable = !!iterationContext.config.sessionCapable
-
-  // Detect knowledge map availability
-  const hasKnowledgeMap = !!(
-    iterationContext.knowledgeMap && Object.keys(iterationContext.knowledgeMap.nodes).length > 0
-  )
-
-  // Detect if memory operations should be included
-  const includeMemoryOps = !!iterationContext.config.memoryPreferences
-
-  // Derive security level: explicit config > sessionCapable-based default
-  const securityLevel = iterationContext.config.securityLevel ?? (isSessionCapable ? 'hardened' : 'standard')
-
-  // Build complete system prompt using modular builder
-  const systemPrompt = buildSystemPrompt(iterationContext.config.systemPrompt, {
-    securityLevel,
-    includeMessageAction: isSessionCapable,
-    includeNavigateKnowledge: hasKnowledgeMap,
-    knowledgeMap: iterationContext.knowledgeMap,
-    tools: toolDefinitions,
-    memoryStatus,
-    outputSchema: iterationContext.contract.outputSchema,
-    memoryPreferences: iterationContext.config.memoryPreferences
-  })
-
-  // Enforce hard limits before building request
-  iterationContext.memoryManager.enforceHardLimits()
-
-  return {
-    systemPrompt,
-    tools: toolDefinitions,
-    constraints: {
-      maxOutputTokens: iterationContext.modelConfig.maxOutputTokens,
-      temperature: 1
-    },
-    memoryContext: iterationContext.memoryManager.toContext(
-      iterationContext.iteration,
-      iterationContext.executionContext.sessionTurnNumber
-    ),
-    includeMessageAction: isSessionCapable,
-    includeNavigateKnowledge: hasKnowledgeMap,
-    includeMemoryOps
-  }
-}
+/**
+ * LLM Request Builder
+ * Constructs universal LLMRequest from execution context using modular prompt system
+ */
+
+import type { z } from 'zod'
+import type { IterationContext } from '../core/types'
+import type { ToolDefinition } from '../../tools/types'
+import type { KnowledgeMap } from '../knowledge-map/types'
+import { zodToJsonSchema } from '@alcyone-labs/zod-to-json-schema'
+import { buildSecurityPrompt } from './prompt-sections/security'
+import { buildBaseActionsPrompt } from './prompt-sections/base-actions'
+import { buildKnowledgeMapPrompt } from './prompt-sections/knowledge-map'
+import { buildToolsPrompt } from './prompt-sections/tools'
+import { buildMemoryPrompt, type MemoryStatus } from './prompt-sections/memory'
+import { buildCompletionPrompt } from './prompt-sections/completion'
+
+/**
+ * Options for system prompt generation
+ */
+export interface SystemPromptOptions {
+  /** Security level for prompt injection defense */
+  securityLevel: 'standard' | 'hardened' | 'none'
+  /** Whether to include message action (session-based agents only) */
+  includeMessageAction: boolean
+  /** Whether to include navigate-knowledge action (knowledge map present) */
+  includeNavigateKnowledge: boolean
+  /** Knowledge map with nodes (optional) */
+  knowledgeMap?: KnowledgeMap
+  /** Available tools */
+  tools: ToolDefinition[]
+  /** Current memory status */
+  memoryStatus: MemoryStatus
+  /** Output schema for completion guidance (optional) */
+  outputSchema?: z.ZodSchema
+  /** Memory preferences for opt-in memory management (optional string) */
+  memoryPreferences?: string
+}
+
+/**
+ * Builds complete system prompt from modular sections
+ *
+ * Composition order:
+ * 0. Security rules (standard/hardened, or omitted if 'none')
+ * 1. Base actions (conditional message action based on session context)
+ * 2. Knowledge map (if present)
+ * 3. Tools (if present)
+ * 4. Memory management (CONDITIONAL - only if preferences provided)
+ * 5. Task completion
+ * 6. Agent-specific instructions
+ *
+ * @param agentPrompt - Agent-specific instructions
+ * @param options - Prompt configuration options
+ * @returns Complete system prompt string
+ */
+function buildSystemPrompt(agentPrompt: string, options: SystemPromptOptions): string {
+  const sections: string[] = []
+
+  // 0. Security rules (first position for maximum LLM attention)
+  const securitySection = buildSecurityPrompt(options.securityLevel)
+  if (securitySection) {
+    sections.push(securitySection)
+  }
+
+  // 1. Base actions (with conditional message and navigate-knowledge actions)
+  sections.push(buildBaseActionsPrompt(options.includeMessageAction, options.includeNavigateKnowledge))
+
+  // 2. Knowledge map (if present)
+  const knowledgeMapSection = buildKnowledgeMapPrompt(options.knowledgeMap)
+  if (knowledgeMapSection) {
+    sections.push(knowledgeMapSection)
+  }
+
+  // 3. Tools (if present)
+  const toolsSection = buildToolsPrompt(options.tools)
+  if (toolsSection) {
+    sections.push(toolsSection)
+  }
+
+  // 4. Memory management (CONDITIONAL - only if preferences provided)
+  // Conservative approach: Keep memoryOps in schema, but skip prompt if no preferences
+  if (options.memoryPreferences) {
+    sections.push(buildMemoryPrompt(options.memoryStatus, options.memoryPreferences))
+  }
+
+  // 5. Task completion guidance (always included)
+  sections.push(buildCompletionPrompt(options.outputSchema))
+
+  // 6. Agent-specific instructions (separator + prompt)
+  sections.push('---\n')
+  sections.push('# AGENT-SPECIFIC INSTRUCTIONS\n\n')
+  sections.push(agentPrompt)
+
+  return sections.join('\n')
+}
+
+/**
+ * Build universal LLM iteration request from current state
+ * Combines system prompt, tools, constraints, and memory using modular prompt builder
+ *
+ * @param iterationContext - Agent execution context
+ * @returns Agent iteration request data
+ */
+export function buildReasoningRequest(iterationContext: IterationContext): {
+  systemPrompt: string
+  tools: ToolDefinition[]
+  constraints: { maxOutputTokens?: number; temperature?: number }
+  memoryContext: string
+  includeMessageAction: boolean
+  includeNavigateKnowledge: boolean
+  includeMemoryOps: boolean
+} {
+  // Build tool definitions for system prompt from registry
+  const tools = Array.from(iterationContext.toolRegistry.values())
+  const toolDefinitions = tools.map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    inputSchema: zodToJsonSchema(tool.inputSchema as z.ZodSchema)
+  }))
+
+  // Get memory status for system prompt
+  const memoryStatus = iterationContext.memoryManager.getStatus()
+
+  // Agent capability: explicit session support declaration
+  // Controls whether message action is available in prompts
+  const isSessionCapable = !!iterationContext.config.sessionCapable
+
+  // Detect knowledge map availability
+  const hasKnowledgeMap = !!(
+    iterationContext.knowledgeMap && Object.keys(iterationContext.knowledgeMap.nodes).length > 0
+  )
+
+  // Detect if memory operations should be included
+  const includeMemoryOps = !!iterationContext.config.memoryPreferences
+
+  // Derive security level: explicit config > sessionCapable-based default
+  const securityLevel = iterationContext.config.securityLevel ?? (isSessionCapable ? 'hardened' : 'standard')
+
+  // Build complete system prompt using modular builder
+  const systemPrompt = buildSystemPrompt(iterationContext.config.systemPrompt, {
+    securityLevel,
+    includeMessageAction: isSessionCapable,
+    includeNavigateKnowledge: hasKnowledgeMap,
+    knowledgeMap: iterationContext.knowledgeMap,
+    tools: toolDefinitions,
+    memoryStatus,
+    outputSchema: iterationContext.contract.outputSchema,
+    memoryPreferences: iterationContext.config.memoryPreferences
+  })
+
+  // Enforce hard limits before building request
+  iterationContext.memoryManager.enforceHardLimits()
+
+  return {
+    systemPrompt,
+    tools: toolDefinitions,
+    constraints: {
+      maxOutputTokens: iterationContext.modelConfig.maxOutputTokens,
+      temperature: 1
+    },
+    memoryContext: iterationContext.memoryManager.toContext(
+      iterationContext.iteration,
+      iterationContext.executionContext.sessionTurnNumber
+    ),
+    includeMessageAction: isSessionCapable,
+    includeNavigateKnowledge: hasKnowledgeMap,
+    includeMemoryOps
+  }
+}

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

@@ -1,18 +1,18 @@
-/**
- * Reasoning Phase Types
- * Agent-internal types for iteration responses
- */
-
-import type { MemoryOperations } from '../memory/types'
-import type { AgentAction } from '../actions/types'
-
-/**
- * Iteration response - task execution phase
- * Returns reasoning, memory operations, and next actions
- * Used internally by agent iteration processor
- */
-export interface LLMIterationResponse {
-  reasoning: string
-  memoryOps?: MemoryOperations
-  nextActions: AgentAction[]
-}
+/**
+ * Reasoning Phase Types
+ * Agent-internal types for iteration responses
+ */
+
+import type { MemoryOperations } from '../memory/types'
+import type { AgentAction } from '../actions/types'
+
+/**
+ * Iteration response - task execution phase
+ * Returns reasoning, memory operations, and next actions
+ * Used internally by agent iteration processor
+ */
+export interface LLMIterationResponse {
+  reasoning: string
+  memoryOps?: MemoryOperations
+  nextActions: AgentAction[]
+}

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

@@ -1,118 +1,118 @@
-/**
- * Error categories for observability grouping and classification.
- * Used to categorize errors in the execution_errors table metadata.
- */
-export type ExecutionErrorCategory = 'llm' | 'tool' | 'workflow' | 'agent' | 'validation' | 'system'
-
-/**
- * Abstract base class for all execution engine errors.
- * Enforces contract for execution_errors table insertion with explicit type,
- * severity, category, and context properties.
- *
- * All execution engine errors MUST extend this class to ensure proper error
- * tracking and observability in the execution_errors table.
- *
- * @example
- * ```typescript
- * export class MyExecutionError extends ExecutionError {
- *   readonly type = 'my_execution_error' as const
- *   readonly severity = 'warning' as const
- *   readonly category = 'workflow' as const
- *
- *   constructor(message: string, context?: Record<string, unknown>) {
- *     super(message, context)
- *   }
- * }
- * ```
- */
-export abstract class ExecutionError extends Error {
-  /**
-   * Error type identifier for execution_errors table.
-   * Should be a unique, snake_case string that identifies this specific error class.
-   * Used for filtering, aggregation, and error-specific handling in observability systems.
-   */
-  abstract readonly type: string
-
-  /**
-   * Error severity level for execution_errors table.
-   * - critical: System failures, auth issues, resource exhaustion - execution cannot continue
-   * - warning: Transient failures, configuration errors - execution may retry or requires user correction
-   * - info: Validation failures, expected user errors - user/developer action needed
-   */
-  abstract readonly severity: 'critical' | 'warning' | 'info'
-
-  /**
-   * Error category for observability grouping.
-   * Used to categorize errors in dashboards and analytics.
-   */
-  abstract readonly category: ExecutionErrorCategory
-
-  /**
-   * Additional context/metadata for the error.
-   * Stored in execution_errors.metadata JSONB column.
-   */
-  public readonly context?: Record<string, unknown>
-
-  /**
-   * @param message - Human-readable error message
-   * @param context - Additional context/metadata for observability
-   */
-  constructor(message: string, context?: Record<string, unknown>) {
-    super(message)
-    this.name = this.constructor.name
-    this.context = context
-
-    // Maintain proper stack trace for where our error was thrown
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, this.constructor)
-    }
-  }
-
-  /**
-   * Indicates whether this error type is retryable.
-   * Default: false (safe default - only retry when explicitly safe to do so)
-   *
-   * Subclasses should override to return true for retryable scenarios:
-   * - Network/infrastructure errors (exponential backoff)
-   * - Rate limiting (linear backoff)
-   * - Service availability (exponential backoff)
-   * - Circuit breaker (circuit breaker's own delay)
-   *
-   * DO NOT retry:
-   * - Authentication/authorization errors
-   * - Validation errors
-   * - Configuration errors
-   * - Resource exhaustion errors
-   */
-  isRetryable(): boolean {
-    return false
-  }
-}
-
-/**
- * Unknown execution error - fallback for untyped errors
- *
- * Used when catching errors that are not ExecutionError instances.
- * Preserves original error context for debugging while ensuring
- * consistent error tracking in the execution_errors table.
- *
- * Severity: critical (unknown errors should be treated seriously until investigated)
- */
-export class UnknownExecutionError extends ExecutionError {
-  readonly type = 'unknown_execution_error' as const
-  readonly severity = 'critical' as const
-  readonly category = 'system' as const
-
-  constructor(
-    message: string,
-    public readonly originalError?: unknown
-  ) {
-    super(message, {
-      originalError: originalError instanceof Error ? {
-        name: originalError.name,
-        message: originalError.message,
-        stack: originalError.stack
-      } : originalError
-    })
-  }
-}
+/**
+ * Error categories for observability grouping and classification.
+ * Used to categorize errors in the execution_errors table metadata.
+ */
+export type ExecutionErrorCategory = 'llm' | 'tool' | 'workflow' | 'agent' | 'validation' | 'system'
+
+/**
+ * Abstract base class for all execution engine errors.
+ * Enforces contract for execution_errors table insertion with explicit type,
+ * severity, category, and context properties.
+ *
+ * All execution engine errors MUST extend this class to ensure proper error
+ * tracking and observability in the execution_errors table.
+ *
+ * @example
+ * ```typescript
+ * export class MyExecutionError extends ExecutionError {
+ *   readonly type = 'my_execution_error' as const
+ *   readonly severity = 'warning' as const
+ *   readonly category = 'workflow' as const
+ *
+ *   constructor(message: string, context?: Record<string, unknown>) {
+ *     super(message, context)
+ *   }
+ * }
+ * ```
+ */
+export abstract class ExecutionError extends Error {
+  /**
+   * Error type identifier for execution_errors table.
+   * Should be a unique, snake_case string that identifies this specific error class.
+   * Used for filtering, aggregation, and error-specific handling in observability systems.
+   */
+  abstract readonly type: string
+
+  /**
+   * Error severity level for execution_errors table.
+   * - critical: System failures, auth issues, resource exhaustion - execution cannot continue
+   * - warning: Transient failures, configuration errors - execution may retry or requires user correction
+   * - info: Validation failures, expected user errors - user/developer action needed
+   */
+  abstract readonly severity: 'critical' | 'warning' | 'info'
+
+  /**
+   * Error category for observability grouping.
+   * Used to categorize errors in dashboards and analytics.
+   */
+  abstract readonly category: ExecutionErrorCategory
+
+  /**
+   * Additional context/metadata for the error.
+   * Stored in execution_errors.metadata JSONB column.
+   */
+  public readonly context?: Record<string, unknown>
+
+  /**
+   * @param message - Human-readable error message
+   * @param context - Additional context/metadata for observability
+   */
+  constructor(message: string, context?: Record<string, unknown>) {
+    super(message)
+    this.name = this.constructor.name
+    this.context = context
+
+    // Maintain proper stack trace for where our error was thrown
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor)
+    }
+  }
+
+  /**
+   * Indicates whether this error type is retryable.
+   * Default: false (safe default - only retry when explicitly safe to do so)
+   *
+   * Subclasses should override to return true for retryable scenarios:
+   * - Network/infrastructure errors (exponential backoff)
+   * - Rate limiting (linear backoff)
+   * - Service availability (exponential backoff)
+   * - Circuit breaker (circuit breaker's own delay)
+   *
+   * DO NOT retry:
+   * - Authentication/authorization errors
+   * - Validation errors
+   * - Configuration errors
+   * - Resource exhaustion errors
+   */
+  isRetryable(): boolean {
+    return false
+  }
+}
+
+/**
+ * Unknown execution error - fallback for untyped errors
+ *
+ * Used when catching errors that are not ExecutionError instances.
+ * Preserves original error context for debugging while ensuring
+ * consistent error tracking in the execution_errors table.
+ *
+ * Severity: critical (unknown errors should be treated seriously until investigated)
+ */
+export class UnknownExecutionError extends ExecutionError {
+  readonly type = 'unknown_execution_error' as const
+  readonly severity = 'critical' as const
+  readonly category = 'system' as const
+
+  constructor(
+    message: string,
+    public readonly originalError?: unknown
+  ) {
+    super(message, {
+      originalError: originalError instanceof Error ? {
+        name: originalError.name,
+        message: originalError.message,
+        stack: originalError.stack
+      } : originalError
+    })
+  }
+}

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

@@ -1,2 +1,2 @@
-export { ExecutionError as ExecutionError, UnknownExecutionError, type ExecutionErrorCategory } from './errors'
-export * from './types'
+export { ExecutionError as ExecutionError, UnknownExecutionError, type ExecutionErrorCategory } from './errors'
+export * from './types'