@elevasis/core 0.1.0

package/src/execution/engine/agent/actions/executor.ts

@@ -0,0 +1,205 @@
+/**
+ * Action Executor
+ * Executes individual actions (tool calls, delegation)
+ */
+
+import type { IterationContext } from '../core/types'
+import type { ToolCallAction } from './types'
+import { addToolError } from '../memory/utils'
+import { ToolingError, timeoutError } from '../../tools/types'
+import { DEFAULT_TOOL_TIMEOUT } from '../../../../platform/constants/timeouts'
+
+/**
+ * Execute a single tool call action
+ * Handles tool lookup, validation, execution, and error handling
+ *
+ * Results (success or error) are added to memory as tool-result messages
+ *
+ * @param iterationContext - Agent execution context
+ * @param action - Tool call action to execute
+ */
+export async function executeToolCall(iterationContext: IterationContext, action: ToolCallAction): Promise<void> {
+  // Emit tool call event (before execution)
+  await iterationContext.executionContext.onMessageEvent?.({
+    type: 'agent:tool_call',
+    toolName: action.name,
+    args: action.input
+  })
+
+  // Track tool call timing
+  const toolStartTime = Date.now()
+
+  // Look up tool via registry (O(1) instead of O(n))
+  const tool = iterationContext.toolRegistry.get(action.name)
+  if (!tool) {
+    const toolEndTime = Date.now()
+    const toolDuration = toolEndTime - toolStartTime
+
+    // Emit tool error event
+    await iterationContext.executionContext.onMessageEvent?.({
+      type: 'agent:tool_result',
+      toolName: action.name,
+      success: false,
+      error: `Tool '${action.name}' not found`
+    })
+
+    // Log tool call event (failed - tool not found)
+    iterationContext.logger.toolCall(
+      action.name,
+      iterationContext.iteration,
+      toolStartTime,
+      toolEndTime,
+      toolDuration,
+      false,
+      `Tool '${action.name}' not found`,
+      action.input,
+      undefined
+    )
+
+    addToolError(
+      iterationContext.memoryManager,
+      action,
+      `Tool '${action.name}' not found`,
+      iterationContext.iteration,
+      iterationContext.executionContext.sessionTurnNumber ?? null
+    )
+    return
+  }
+
+  try {
+    // Validate input against tool's schema
+    const validatedInput = tool.inputSchema.parse(action.input)
+
+    // Compose timeout signal: per-tool timeout OR execution ceiling, whichever fires first
+    const toolTimeout = tool.timeout ?? DEFAULT_TOOL_TIMEOUT
+    const signals: AbortSignal[] = [AbortSignal.timeout(toolTimeout)]
+    if (iterationContext.executionContext.signal) {
+      signals.push(iterationContext.executionContext.signal)
+    }
+    const composedSignal = AbortSignal.any(signals)
+
+    // Execute tool with Promise.race to enforce timeout even if tool ignores the signal
+    const rawResult = await Promise.race([
+      tool.execute({
+        input: validatedInput,
+        executionContext: iterationContext.executionContext,
+        iterationContext,
+        signal: composedSignal
+      }),
+      new Promise<never>((_, reject) => {
+        if (composedSignal.aborted) {
+          reject(timeoutError(action.name))
+          return
+        }
+        composedSignal.addEventListener('abort', () => reject(timeoutError(action.name)), { once: true })
+      })
+    ])
+
+    // Validate output against schema
+    const validatedResult = tool.outputSchema.parse(rawResult)
+
+    const toolEndTime = Date.now()
+    const toolDuration = toolEndTime - toolStartTime
+
+    // Emit tool success event
+    await iterationContext.executionContext.onMessageEvent?.({
+      type: 'agent:tool_result',
+      toolName: action.name,
+      success: true,
+      result: validatedResult
+    })
+
+    // Log tool call event (success)
+    iterationContext.logger.toolCall(
+      action.name,
+      iterationContext.iteration,
+      toolStartTime,
+      toolEndTime,
+      toolDuration,
+      true,
+      undefined,
+      action.input,
+      validatedResult
+    )
+
+    // Add validated result to memory
+    const memoryStartTime = Date.now()
+
+    iterationContext.memoryManager.addToHistory({
+      type: 'tool-result',
+      content: JSON.stringify(validatedResult),
+      turnNumber: iterationContext.executionContext.sessionTurnNumber ?? null,
+      iterationNumber: iterationContext.iteration
+    })
+
+    const memoryEndTime = Date.now()
+    const memoryDuration = memoryEndTime - memoryStartTime
+
+    iterationContext.logger.action(
+      'memory-tool-result',
+      `Stored tool-result for ${action.name} (${JSON.stringify(validatedResult).length} chars), history size: ${iterationContext.memoryManager.getHistoryLength()}`,
+      iterationContext.iteration,
+      memoryStartTime,
+      memoryEndTime,
+      memoryDuration
+    )
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error)
+    const toolEndTime = Date.now()
+    const toolDuration = toolEndTime - toolStartTime
+
+    // Emit tool error event
+    await iterationContext.executionContext.onMessageEvent?.({
+      type: 'agent:tool_result',
+      toolName: action.name,
+      success: false,
+      error: errorMessage
+    })
+
+    // Log tool call event (failed)
+    iterationContext.logger.toolCall(
+      action.name,
+      iterationContext.iteration,
+      toolStartTime,
+      toolEndTime,
+      toolDuration,
+      false,
+      errorMessage,
+      action.input,
+      undefined
+    )
+
+    // Add error to memory (don't throw - continue with other actions)
+    const memoryStartTime = Date.now()
+
+    // Extract structured metadata if available
+    const metadata = error instanceof ToolingError
+      ? {
+          errorType: error.errorType,
+          severity: error.severity,
+          isRetryable: error.isRetryable()
+        }
+      : undefined
+
+    addToolError(
+      iterationContext.memoryManager,
+      action,
+      errorMessage,
+      iterationContext.iteration,
+      iterationContext.executionContext.sessionTurnNumber ?? null,
+      metadata
+    )
+
+    const memoryEndTime = Date.now()
+    const memoryDuration = memoryEndTime - memoryStartTime
+
+    iterationContext.logger.action(
+      'memory-tool-error',
+      `Stored error for ${action.name}: ${errorMessage}, history size: ${iterationContext.memoryManager.getHistoryLength()}`,
+      iterationContext.iteration,
+      memoryStartTime,
+      memoryEndTime,
+      memoryDuration
+    )
+  }
+}

package/src/execution/engine/agent/actions/navigate-knowledge-executor.ts

@@ -0,0 +1,230 @@
+/**
+ * Navigate Knowledge Action Executor
+ * Loads knowledge nodes and registers their tools dynamically
+ *
+ * Features:
+ * - Dynamic tool registration with duplicate checking
+ * - Memory scoping (session vs task)
+ * - Hierarchical navigation (flattens child nodes into main map)
+ * - Cross-turn persistence (tracks loaded nodes in sessionMemory)
+ */
+
+import type { IterationContext } from '../core/types'
+import type { NavigateKnowledgeAction } from './types'
+import type { KnowledgeMapState } from '../knowledge-map/types'
+
+/**
+ * Execute a navigate-knowledge action
+ * Loads knowledge node content and registers tools with the agent
+ *
+ * @param iterationContext - Agent execution context
+ * @param action - Navigate knowledge action to execute
+ */
+export async function executeNavigateKnowledge(
+  iterationContext: IterationContext,
+  action: NavigateKnowledgeAction
+): Promise<void> {
+  const { knowledgeMap, toolRegistry, memoryManager, executionContext, iteration, logger } = iterationContext
+
+  // Emit navigate knowledge event (before execution)
+  await executionContext.onMessageEvent?.({
+    type: 'agent:tool_call',
+    toolName: 'navigate_knowledge',
+    args: { nodeId: action.nodeId }
+  })
+
+  const startTime = Date.now()
+
+  try {
+    // Validate knowledge map exists
+    if (!knowledgeMap) {
+      throw new Error('Knowledge map not available - agent does not have knowledge navigation enabled')
+    }
+
+    // Look up knowledge node
+    const node = knowledgeMap.nodes[action.nodeId]
+    if (!node) {
+      throw new Error(`Knowledge node '${action.nodeId}' not found in knowledge map`)
+    }
+
+    // Load knowledge content
+    const content = await node.load(executionContext)
+
+    // Cache prompt and set loaded flag (minimal caching)
+    node.loaded = true
+    node.prompt = content.prompt
+
+    // Flatten child nodes into main knowledge map (hierarchical navigation)
+    let childNodesCount = 0
+    if (content.nodes && Object.keys(content.nodes).length > 0) {
+      for (const [childId, childNode] of Object.entries(content.nodes)) {
+        if (!knowledgeMap.nodes[childId]) {
+          knowledgeMap.nodes[childId] = childNode
+          childNodesCount++
+        }
+      }
+
+      if (childNodesCount > 0) {
+        logger.action(
+          'knowledge-nodes-discovered',
+          `Discovered ${childNodesCount} child nodes from '${action.nodeId}': ${Object.keys(content.nodes).join(', ')}`,
+          iteration,
+          startTime,
+          startTime,
+          0
+        )
+      }
+    }
+
+    // Register tools if provided (skip tools that are already registered)
+    if (content.tools && content.tools.length > 0) {
+      const newTools: string[] = []
+      const skippedTools: string[] = []
+
+      for (const tool of content.tools) {
+        if (toolRegistry.has(tool.name)) {
+          skippedTools.push(tool.name)
+        } else {
+          toolRegistry.set(tool.name, tool)
+          newTools.push(tool.name)
+        }
+      }
+
+      if (newTools.length > 0) {
+        logger.action(
+          'knowledge-tools-registered',
+          `Registered ${newTools.length} tools from knowledge node '${action.nodeId}': ${newTools.join(', ')}`,
+          iteration,
+          startTime,
+          startTime,
+          0
+        )
+      }
+
+      if (skippedTools.length > 0) {
+        logger.action(
+          'knowledge-tools-skipped',
+          `Skipped ${skippedTools.length} already-registered tools: ${skippedTools.join(', ')}`,
+          iteration,
+          startTime,
+          startTime,
+          0
+        )
+      }
+    }
+
+    // Track loaded node in sessionMemory state for cross-turn persistence
+    // Note: Prompt is now cached on node.content and serialized into system prompt
+    // No separate sessionMemory/history storage needed
+    const stateKey = 'knowledge-map-state'
+    const existingState = memoryManager.get(stateKey)
+    let state: KnowledgeMapState
+
+    if (existingState) {
+      try {
+        state = JSON.parse(existingState) as KnowledgeMapState
+      } catch {
+        // Invalid state, create new
+        state = { loadedNodes: [], version: 1 }
+      }
+    } else {
+      state = { loadedNodes: [], version: 1 }
+    }
+
+    // Add node to loaded list if not already present
+    if (!state.loadedNodes.includes(action.nodeId)) {
+      state.loadedNodes.push(action.nodeId)
+      memoryManager.set(stateKey, JSON.stringify(state))
+
+      logger.action(
+        'knowledge-state-updated',
+        `Added '${action.nodeId}' to loaded nodes (total: ${state.loadedNodes.length})`,
+        iteration,
+        startTime,
+        startTime,
+        0
+      )
+    }
+
+    const endTime = Date.now()
+    const duration = endTime - startTime
+
+    // Emit success event
+    await executionContext.onMessageEvent?.({
+      type: 'agent:tool_result',
+      toolName: 'navigate_knowledge',
+      success: true,
+      result: {
+        nodeId: action.nodeId,
+        toolsLoaded: content.tools?.length ?? 0,
+        childNodesDiscovered: childNodesCount,
+        promptLength: content.prompt.length
+      }
+    })
+
+    // Log tool call event (success)
+    logger.toolCall(
+      'navigate_knowledge',
+      iteration,
+      startTime,
+      endTime,
+      duration,
+      true,
+      undefined,
+      { nodeId: action.nodeId },
+      {
+        nodeId: action.nodeId,
+        toolsLoaded: content.tools?.length ?? 0,
+        childNodesDiscovered: childNodesCount,
+        promptLength: content.prompt.length
+      }
+    )
+
+    // Build result message
+    let resultMessage = `Knowledge node '${action.nodeId}' loaded successfully. ${content.tools?.length ?? 0} tools registered.`
+    if (childNodesCount > 0) {
+      resultMessage += ` ${childNodesCount} child nodes discovered.`
+    }
+
+    // Add success result to memory
+    memoryManager.addToHistory({
+      type: 'tool-result',
+      content: resultMessage,
+      turnNumber: executionContext.sessionTurnNumber ?? null,
+      iterationNumber: iteration
+    })
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error)
+    const endTime = Date.now()
+    const duration = endTime - startTime
+
+    // Emit error event
+    await executionContext.onMessageEvent?.({
+      type: 'agent:tool_result',
+      toolName: 'navigate_knowledge',
+      success: false,
+      error: errorMessage
+    })
+
+    // Log tool call event (failed)
+    logger.toolCall(
+      'navigate_knowledge',
+      iteration,
+      startTime,
+      endTime,
+      duration,
+      false,
+      errorMessage,
+      { nodeId: action.nodeId },
+      undefined
+    )
+
+    // Add error to memory
+    memoryManager.addToHistory({
+      type: 'error',
+      content: `Error loading knowledge node '${action.nodeId}': ${errorMessage}`,
+      turnNumber: executionContext.sessionTurnNumber ?? null,
+      iterationNumber: iteration
+    })
+  }
+}

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

@@ -0,0 +1,116 @@
+/**
+ * Action Phase Processor
+ * Orchestrates execution of LLM-planned actions
+ */
+
+import type { IterationContext } from '../core/types'
+import type { LLMIterationResponse } from '../reasoning/types'
+import type { AgentAction, ToolCallAction } from './types'
+import { executeToolCall } from './executor'
+import { executeNavigateKnowledge } from './navigate-knowledge-executor'
+
+/**
+ * Validate action sequence for correctness
+ * Ensures no invalid patterns that would cause undefined behavior
+ *
+ * Rules:
+ * - No multiple 'complete' actions
+ * - 'complete' cannot mix with 'navigate-knowledge' (loading knowledge without
+ *   reasoning about it is always wasteful — the LLM should iterate instead)
+ * - 'complete' CAN mix with 'tool-call' (side-effect tools like navigate_user,
+ *   update_filters are fire-and-forget — tool calls execute first via
+ *   Promise.allSettled before completion is signaled)
+ * - 'message' actions ARE allowed before 'complete' (user-facing communication)
+ *
+ * @param actions - Action array to validate
+ * @throws Error if validation fails
+ */
+function validateActionSequence(actions: AgentAction[]): void {
+  // Count completion actions
+  const completeActions = actions.filter((a) => a.type === 'complete')
+
+  // Rule 1: No duplicate completions
+  if (completeActions.length > 1) {
+    throw new Error('Multiple complete actions not allowed in single iteration')
+  }
+
+  // Rule 2: Completion cannot mix with navigate-knowledge
+  // (tool-call + complete is allowed — side-effect tools execute before completion)
+  if (completeActions.length === 1) {
+    const hasNavigateKnowledge = actions.some((a) => a.type === 'navigate-knowledge')
+    if (hasNavigateKnowledge) {
+      throw new Error('Complete action cannot mix with navigate-knowledge actions')
+    }
+  }
+}
+
+/**
+ * Process all actions from LLM response
+ * Executes tool calls in parallel, handles completion, and messages sequentially
+ *
+ * Tool calls are parallelized using Promise.allSettled() for performance:
+ * - Independent tool calls execute concurrently (up to 5x faster)
+ * - Partial failures don't abort successful tools
+ * - Results added to memory as they complete
+ *
+ * Other actions (navigate-knowledge, message, complete) remain sequential
+ * because they are order-dependent.
+ *
+ * @param iterationContext - Agent execution context
+ * @param response - LLM response with actions to execute
+ * @returns Object with shouldComplete flag (no finalAnswer - generated in completion phase)
+ */
+export async function processActions(
+  iterationContext: IterationContext,
+  response: LLMIterationResponse
+): Promise<{ shouldComplete: boolean }> {
+  // Validate action sequence before processing
+  validateActionSequence(response.nextActions)
+
+  let shouldComplete = false
+
+  // Group actions by parallelizability
+  const toolCalls: ToolCallAction[] = []
+  const otherActions: AgentAction[] = []
+
+  for (const action of response.nextActions) {
+    if (action.type === 'tool-call') {
+      toolCalls.push(action)
+    } else {
+      otherActions.push(action)
+    }
+  }
+
+  // Execute tool calls in parallel (if any)
+  // Uses Promise.allSettled() for partial success handling:
+  // - If 4/5 tools succeed, we get those results
+  // - Each tool handles errors independently and adds to memory
+  // - No result aggregation needed (each tool call adds to memory directly)
+  if (toolCalls.length > 0) {
+    await Promise.allSettled(toolCalls.map((action) => executeToolCall(iterationContext, action)))
+  }
+
+  // Execute other actions sequentially (order matters)
+  for (const action of otherActions) {
+    switch (action.type) {
+      case 'navigate-knowledge':
+        await executeNavigateKnowledge(iterationContext, action)
+        break
+
+      case 'complete':
+        shouldComplete = true
+        break
+
+      case 'message': {
+        // Emit assistant message event (immediate persistence + streaming)
+        await iterationContext.executionContext.onMessageEvent?.({
+          type: 'assistant_message',
+          text: action.text
+        })
+        break
+      }
+    }
+  }
+
+  return { shouldComplete }
+}

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

@@ -0,0 +1,70 @@
+/**
+ * Action Type Definitions
+ * All action-related types and validation schemas
+ */
+
+import { z } from 'zod'
+
+/**
+ * Agent action types
+ * Discriminated union for type-safe action handling
+ */
+export type AgentAction =
+  | ToolCallAction
+  | CompleteAction
+  | MessageAction
+  | NavigateKnowledgeAction
+
+export interface ToolCallAction {
+  type: 'tool-call'
+  id: string // Unique ID for tracking tool call/result pairs
+  name: string // Tool name
+  input: Record<string, unknown> // Tool input (validated against tool's inputSchema)
+}
+
+export interface CompleteAction {
+  type: 'complete'
+}
+
+export interface MessageAction {
+  type: 'message'
+  text: string // User-facing message text
+}
+
+export interface NavigateKnowledgeAction {
+  type: 'navigate-knowledge'
+  id: string // Unique ID for tracking action/result pairs
+  nodeId: string // Knowledge node identifier
+}
+
+/**
+ * Zod schemas for runtime validation
+ */
+export const ToolCallActionSchema = z.object({
+  type: z.literal('tool-call'),
+  id: z.string(),
+  name: z.string(),
+  input: z.any() // Use z.any() instead of z.unknown() for JSON Schema compatibility
+})
+
+export const CompleteActionSchema = z.object({
+  type: z.literal('complete')
+})
+
+export const MessageActionSchema = z.object({
+  type: z.literal('message'),
+  text: z.string()
+})
+
+export const NavigateKnowledgeActionSchema = z.object({
+  type: z.literal('navigate-knowledge'),
+  id: z.string(),
+  nodeId: z.string()
+})
+
+export const AgentActionSchema = z.discriminatedUnion('type', [
+  ToolCallActionSchema,
+  CompleteActionSchema,
+  MessageActionSchema,
+  NavigateKnowledgeActionSchema
+])