@elevasis/core 0.7.0 → 0.8.0

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

@@ -1,92 +1,92 @@
-/**
- * Reasoning Phase Processor
- * Handles LLM interaction for the REASON phase of agent execution
- */
-
-import type { IterationContext } from '../core/types'
-import type { LLMIterationResponse } from './types'
-import { buildReasoningRequest } from './request-builder'
-import { callLLMForAgentIteration } from './adapters/agent-adapter-helpers'
-
-/**
- * Process reasoning phase - Query LLM for next actions
- * Handles adapter resolution, request building, LLM call, logging, and memory storage
- *
- * @param iterationContext - Agent execution context
- * @returns LLM's reasoning and planned actions
- */
-export async function processReasoning(iterationContext: IterationContext): Promise<LLMIterationResponse> {
-  // Create adapter via injected factory (stateless, per-iteration)
-  // API process: factory wraps with UniversalLLMAdapter for retry, circuit breaker, observability
-  // SDK worker: factory creates PostMessageLLMAdapter that proxies via platform.call()
-  const adapter = iterationContext.adapterFactory(
-    iterationContext.modelConfig,
-    iterationContext.executionContext.aiUsageCollector,
-    'agent-reasoning',
-    {
-      type: 'agent-reasoning',
-      iteration: iterationContext.iteration,
-      sessionId: iterationContext.executionContext.sessionId,
-      turnNumber: iterationContext.executionContext.sessionTurnNumber
-    }
-  )
-
-  // Build agent iteration request
-  const request = buildReasoningRequest(iterationContext)
-
-  // Track timing for LLM call
-  const startTime = Date.now()
-
-  // Get LLM iteration response using agent-specific helper
-  const { reasoning, memoryOps, nextActions } = await callLLMForAgentIteration(adapter, {
-    systemPrompt: request.systemPrompt,
-    memoryContext: request.memoryContext,
-    tools: request.tools,
-    constraints: request.constraints,
-    model: iterationContext.modelConfig.model,
-    includeMessageAction: request.includeMessageAction,
-    includeNavigateKnowledge: request.includeNavigateKnowledge,
-    includeMemoryOps: request.includeMemoryOps,
-    signal: iterationContext.executionContext.signal
-  })
-
-  const endTime = Date.now()
-  const duration = endTime - startTime
-
-  const response: LLMIterationResponse = { reasoning, memoryOps, nextActions }
-
-  // Emit reasoning event (for session message persistence)
-  await iterationContext.executionContext.onMessageEvent?.({
-    type: 'agent:reasoning',
-    iteration: iterationContext.iteration,
-    reasoning: response.reasoning
-  })
-
-  // Log reasoning event (always present in universal protocol)
-  iterationContext.logger.reasoning(response.reasoning, iterationContext.iteration, startTime, endTime, duration)
-
-  // Store reasoning in memory (always, even when completing)
-  // This preserves the LLM's thought process for future iterations
-  const memoryStartTime = Date.now()
-
-  iterationContext.memoryManager.addToHistory({
-    type: 'reasoning',
-    content: response.reasoning,
-    turnNumber: iterationContext.executionContext.sessionTurnNumber ?? null,
-    iterationNumber: iterationContext.iteration
-  })
-
-  const memoryEndTime = Date.now()
-  const memoryDuration = memoryEndTime - memoryStartTime
-
-  iterationContext.logger.action(
-    'memory-reasoning',
-    `Stored reasoning (${response.reasoning.length} chars), history size: ${iterationContext.memoryManager.getHistoryLength()}, actions: ${response.nextActions.map((a) => a.type).join(', ')}`,
-    iterationContext.iteration,
-    memoryStartTime,
-    memoryEndTime,
-    memoryDuration
-  )
-
-  return response
-}
+/**
+ * Reasoning Phase Processor
+ * Handles LLM interaction for the REASON phase of agent execution
+ */
+
+import type { IterationContext } from '../core/types'
+import type { LLMIterationResponse } from './types'
+import { buildReasoningRequest } from './request-builder'
+import { callLLMForAgentIteration } from './adapters/agent-adapter-helpers'
+
+/**
+ * Process reasoning phase - Query LLM for next actions
+ * Handles adapter resolution, request building, LLM call, logging, and memory storage
+ *
+ * @param iterationContext - Agent execution context
+ * @returns LLM's reasoning and planned actions
+ */
+export async function processReasoning(iterationContext: IterationContext): Promise<LLMIterationResponse> {
+  // Create adapter via injected factory (stateless, per-iteration)
+  // API process: factory wraps with UniversalLLMAdapter for retry, circuit breaker, observability
+  // SDK worker: factory creates PostMessageLLMAdapter that proxies via platform.call()
+  const adapter = iterationContext.adapterFactory(
+    iterationContext.modelConfig,
+    iterationContext.executionContext.aiUsageCollector,
+    'agent-reasoning',
+    {
+      type: 'agent-reasoning',
+      iteration: iterationContext.iteration,
+      sessionId: iterationContext.executionContext.sessionId,
+      turnNumber: iterationContext.executionContext.sessionTurnNumber
+    }
+  )
+
+  // Build agent iteration request
+  const request = buildReasoningRequest(iterationContext)
+
+  // Track timing for LLM call
+  const startTime = Date.now()
+
+  // Get LLM iteration response using agent-specific helper
+  const { reasoning, memoryOps, nextActions } = await callLLMForAgentIteration(adapter, {
+    systemPrompt: request.systemPrompt,
+    memoryContext: request.memoryContext,
+    tools: request.tools,
+    constraints: request.constraints,
+    model: iterationContext.modelConfig.model,
+    includeMessageAction: request.includeMessageAction,
+    includeNavigateKnowledge: request.includeNavigateKnowledge,
+    includeMemoryOps: request.includeMemoryOps,
+    signal: iterationContext.executionContext.signal
+  })
+
+  const endTime = Date.now()
+  const duration = endTime - startTime
+
+  const response: LLMIterationResponse = { reasoning, memoryOps, nextActions }
+
+  // Emit reasoning event (for session message persistence)
+  await iterationContext.executionContext.onMessageEvent?.({
+    type: 'agent:reasoning',
+    iteration: iterationContext.iteration,
+    reasoning: response.reasoning
+  })
+
+  // Log reasoning event (always present in universal protocol)
+  iterationContext.logger.reasoning(response.reasoning, iterationContext.iteration, startTime, endTime, duration)
+
+  // Store reasoning in memory (always, even when completing)
+  // This preserves the LLM's thought process for future iterations
+  const memoryStartTime = Date.now()
+
+  iterationContext.memoryManager.addToHistory({
+    type: 'reasoning',
+    content: response.reasoning,
+    turnNumber: iterationContext.executionContext.sessionTurnNumber ?? null,
+    iterationNumber: iterationContext.iteration
+  })
+
+  const memoryEndTime = Date.now()
+  const memoryDuration = memoryEndTime - memoryStartTime
+
+  iterationContext.logger.action(
+    'memory-reasoning',
+    `Stored reasoning (${response.reasoning.length} chars), history size: ${iterationContext.memoryManager.getHistoryLength()}, actions: ${response.nextActions.map((a) => a.type).join(', ')}`,
+    iterationContext.iteration,
+    memoryStartTime,
+    memoryEndTime,
+    memoryDuration
+  )
+
+  return response
+}

package/src/execution/engine/agent/reasoning/prompt-sections/base-actions.ts

@@ -1,134 +1,134 @@
-/**
- * Base Actions Section
- * Core action definitions with conditional message action based on execution context
- */
-
-/**
- * Builds the base actions section of the system prompt
- * Includes core agent instructions, JSON format, and action type definitions
- *
- * @param includeMessageAction - Whether to include the message action (session-based agents only)
- * @param includeNavigateKnowledge - Whether to include the navigate-knowledge action (knowledge map present)
- * @returns Base actions prompt section
- */
-export function buildBaseActionsPrompt(includeMessageAction: boolean, includeNavigateKnowledge: boolean): string {
-  // Calculate action count and build list
-  let actionCount = 2 // tool-call and complete always available
-  const actions = ['1. tool-call (call a tool)']
-
-  if (includeMessageAction) {
-    actionCount++
-    actions.push(`${actionCount}. message (send message to user)`)
-  }
-
-  if (includeNavigateKnowledge) {
-    actionCount++
-    actions.push(`${actionCount}. navigate-knowledge (load knowledge node)`)
-  }
-
-  actions.push(`${actionCount + 1}. complete (finish task)`)
-  actionCount++ // complete is always last
-
-  const actionsList = actions.join('\n')
-
-  return `# CORE AGENT INSTRUCTIONS
-
-You are an AI agent. Respond with valid JSON:
-
-{
-  "reasoning": "Your thought process",
-  "nextActions": [/* actions to execute */]
-}
-
-## Action Types (${actionCount} available)
-
-${actionsList}
-
-**Formats:**
-- tool-call: { "type": "tool-call", "id": "unique-id", "name": "tool_name", "input": {...} }${
-    includeMessageAction
-      ? `
-- message: { "type": "message", "text": "Your message" }`
-      : ''
-  }${
-    includeNavigateKnowledge
-      ? `
-- navigate-knowledge: { "type": "navigate-knowledge", "id": "unique-id", "nodeId": "node-name" }`
-      : ''
-  }
-- complete: { "type": "complete" }
-
-## Execution Flow
-
-1. You respond with reasoning + actions
-2. System executes actions (tool calls run **in parallel**)
-3. Tool results automatically appear in your next iteration
-4. You see results and decide: more work needed? Or complete?
-5. **Without "complete" action, system iterates again**
-
-## Rules
-
-- Batch independent tool calls in one iteration (faster execution)
-- Dependent operations need separate iterations (tool B needs tool A's result)
-- "complete" cannot mix with tool-call${includeNavigateKnowledge ? '/navigate-knowledge' : ''}${
-    includeMessageAction
-      ? `
-- Always send at least one message before completing
-- When you have your answer, send message + complete in the SAME iteration. Never send a message alone then complete in a later iteration.
-- Never repeat or rephrase the same answer across iterations. One clear answer, then complete.`
-      : ''
-  }
-
-**Use "complete" when:**
-- Task finished successfully
-- Tool returned empty/error results (inform user first)
-- You need user input to proceed (ask question first)
-
-**Don't use "complete" when:**
-- You just called a tool and need its results
-- More iterations are needed
-
-## Examples
-
-### Example 1: Simple Task (No Tools)
-{ "reasoning": "Simple greeting, no tools needed.",
-  "nextActions": [${includeMessageAction ? '{ "type": "message", "text": "Hi! How can I help?" }, ' : ''}{ "type": "complete" }] }
-
-### Example 2: Tool Usage (Two Iterations)
-
-**Iteration 1 - Call tool (NO complete - waiting for results):**
-{ "reasoning": "User asked for time. Calling get_time tool.",
-  "nextActions": [${includeMessageAction ? '{ "type": "message", "text": "Checking the time..." }, ' : ''}{ "type": "tool-call", "id": "t1", "name": "get_time", "input": { "timezone": "UTC" } }] }
-
-**Iteration 2 - Tool result received, now complete:**
-{ "reasoning": "Got time result: 12:00 PM UTC. Task done.",
-  "nextActions": [${includeMessageAction ? '{ "type": "message", "text": "The current time is 12:00 PM UTC." }, ' : ''}{ "type": "complete" }] }
-
-### Example 3: Parallel Tool Calls (Independent Operations)
-When tools don't depend on each other, batch them for faster execution.
-
-{ "reasoning": "User wants time AND weather. Independent operations - calling both in parallel.",
-  "nextActions": [${includeMessageAction ? '{ "type": "message", "text": "Getting time and weather..." }, ' : ''}{ "type": "tool-call", "id": "t1", "name": "get_time", "input": {} },
-    { "type": "tool-call", "id": "w1", "name": "get_weather", "input": { "city": "NYC" } }] }
-
-### Example 4: Dependent Operations (Separate Iterations Required)
-
-**❌ WRONG - Cannot batch dependent operations:**
-{ "nextActions": [
-    { "type": "tool-call", "id": "1", "name": "search_user", "input": { "email": "user@example.com" } },
-    { "type": "tool-call", "id": "2", "name": "update_user", "input": { "userId": "???" } }] }
-Problem: update_user needs userId from search_user result!
-
-**✅ CORRECT - Iteration 1 (get the dependency):**
-{ "reasoning": "Need to find user first before updating.",
-  "nextActions": [${includeMessageAction ? '{ "type": "message", "text": "Looking up user..." }, ' : ''}{ "type": "tool-call", "id": "1", "name": "search_user", "input": { "email": "user@example.com" } }] }
-
-**✅ CORRECT - Iteration 2 (use the result):**
-{ "reasoning": "Found userId: user_123. Now can update.",
-  "nextActions": [{ "type": "tool-call", "id": "2", "name": "update_user", "input": { "userId": "user_123", "name": "New Name" } }] }
-
----
-
-These are your CORE INSTRUCTIONS. Additional context follows below.
-`
-}
+/**
+ * Base Actions Section
+ * Core action definitions with conditional message action based on execution context
+ */
+
+/**
+ * Builds the base actions section of the system prompt
+ * Includes core agent instructions, JSON format, and action type definitions
+ *
+ * @param includeMessageAction - Whether to include the message action (session-based agents only)
+ * @param includeNavigateKnowledge - Whether to include the navigate-knowledge action (knowledge map present)
+ * @returns Base actions prompt section
+ */
+export function buildBaseActionsPrompt(includeMessageAction: boolean, includeNavigateKnowledge: boolean): string {
+  // Calculate action count and build list
+  let actionCount = 2 // tool-call and complete always available
+  const actions = ['1. tool-call (call a tool)']
+
+  if (includeMessageAction) {
+    actionCount++
+    actions.push(`${actionCount}. message (send message to user)`)
+  }
+
+  if (includeNavigateKnowledge) {
+    actionCount++
+    actions.push(`${actionCount}. navigate-knowledge (load knowledge node)`)
+  }
+
+  actions.push(`${actionCount + 1}. complete (finish task)`)
+  actionCount++ // complete is always last
+
+  const actionsList = actions.join('\n')
+
+  return `# CORE AGENT INSTRUCTIONS
+
+You are an AI agent. Respond with valid JSON:
+
+{
+  "reasoning": "Your thought process",
+  "nextActions": [/* actions to execute */]
+}
+
+## Action Types (${actionCount} available)
+
+${actionsList}
+
+**Formats:**
+- tool-call: { "type": "tool-call", "id": "unique-id", "name": "tool_name", "input": {...} }${
+    includeMessageAction
+      ? `
+- message: { "type": "message", "text": "Your message" }`
+      : ''
+  }${
+    includeNavigateKnowledge
+      ? `
+- navigate-knowledge: { "type": "navigate-knowledge", "id": "unique-id", "nodeId": "node-name" }`
+      : ''
+  }
+- complete: { "type": "complete" }
+
+## Execution Flow
+
+1. You respond with reasoning + actions
+2. System executes actions (tool calls run **in parallel**)
+3. Tool results automatically appear in your next iteration
+4. You see results and decide: more work needed? Or complete?
+5. **Without "complete" action, system iterates again**
+
+## Rules
+
+- Batch independent tool calls in one iteration (faster execution)
+- Dependent operations need separate iterations (tool B needs tool A's result)
+- "complete" cannot mix with tool-call${includeNavigateKnowledge ? '/navigate-knowledge' : ''}${
+    includeMessageAction
+      ? `
+- Always send at least one message before completing
+- When you have your answer, send message + complete in the SAME iteration. Never send a message alone then complete in a later iteration.
+- Never repeat or rephrase the same answer across iterations. One clear answer, then complete.`
+      : ''
+  }
+
+**Use "complete" when:**
+- Task finished successfully
+- Tool returned empty/error results (inform user first)
+- You need user input to proceed (ask question first)
+
+**Don't use "complete" when:**
+- You just called a tool and need its results
+- More iterations are needed
+
+## Examples
+
+### Example 1: Simple Task (No Tools)
+{ "reasoning": "Simple greeting, no tools needed.",
+  "nextActions": [${includeMessageAction ? '{ "type": "message", "text": "Hi! How can I help?" }, ' : ''}{ "type": "complete" }] }
+
+### Example 2: Tool Usage (Two Iterations)
+
+**Iteration 1 - Call tool (NO complete - waiting for results):**
+{ "reasoning": "User asked for time. Calling get_time tool.",
+  "nextActions": [${includeMessageAction ? '{ "type": "message", "text": "Checking the time..." }, ' : ''}{ "type": "tool-call", "id": "t1", "name": "get_time", "input": { "timezone": "UTC" } }] }
+
+**Iteration 2 - Tool result received, now complete:**
+{ "reasoning": "Got time result: 12:00 PM UTC. Task done.",
+  "nextActions": [${includeMessageAction ? '{ "type": "message", "text": "The current time is 12:00 PM UTC." }, ' : ''}{ "type": "complete" }] }
+
+### Example 3: Parallel Tool Calls (Independent Operations)
+When tools don't depend on each other, batch them for faster execution.
+
+{ "reasoning": "User wants time AND weather. Independent operations - calling both in parallel.",
+  "nextActions": [${includeMessageAction ? '{ "type": "message", "text": "Getting time and weather..." }, ' : ''}{ "type": "tool-call", "id": "t1", "name": "get_time", "input": {} },
+    { "type": "tool-call", "id": "w1", "name": "get_weather", "input": { "city": "NYC" } }] }
+
+### Example 4: Dependent Operations (Separate Iterations Required)
+
+**❌ WRONG - Cannot batch dependent operations:**
+{ "nextActions": [
+    { "type": "tool-call", "id": "1", "name": "search_user", "input": { "email": "user@example.com" } },
+    { "type": "tool-call", "id": "2", "name": "update_user", "input": { "userId": "???" } }] }
+Problem: update_user needs userId from search_user result!
+
+**✅ CORRECT - Iteration 1 (get the dependency):**
+{ "reasoning": "Need to find user first before updating.",
+  "nextActions": [${includeMessageAction ? '{ "type": "message", "text": "Looking up user..." }, ' : ''}{ "type": "tool-call", "id": "1", "name": "search_user", "input": { "email": "user@example.com" } }] }
+
+**✅ CORRECT - Iteration 2 (use the result):**
+{ "reasoning": "Found userId: user_123. Now can update.",
+  "nextActions": [{ "type": "tool-call", "id": "2", "name": "update_user", "input": { "userId": "user_123", "name": "New Name" } }] }
+
+---
+
+These are your CORE INSTRUCTIONS. Additional context follows below.
+`
+}

package/src/execution/engine/agent/reasoning/prompt-sections/completion.ts

@@ -1,49 +1,49 @@
-/**
- * Task Completion Section
- * Provides guidance on when/how to complete tasks, with optional output schema description
- */
-
-import type { z } from 'zod'
-import { zodToJsonSchema } from '@alcyone-labs/zod-to-json-schema'
-
-/**
- * Builds the task completion section of the system prompt
- * Includes complete action usage and optional output schema guidance
- *
- * @param outputSchema - Optional Zod schema for output validation
- * @returns Task completion prompt section
- */
-export function buildCompletionPrompt(outputSchema?: z.ZodSchema): string {
-  let section = '## Task Completion Guidance\n\n'
-  section += 'When the task is complete, return a complete action:\n'
-  section += '```json\n{ "type": "complete" }\n```\n\n'
-
-  // Only describe output schema if present
-  if (outputSchema) {
-    section += 'After task completion, the final output will be generated and will need to include:\n'
-    section += describeOutputSchema(outputSchema)
-    section += '\n\nDuring task execution, focus on gathering all necessary information.'
-  } else {
-    section += 'This is a side-effect agent (no output generation). Focus on performing the requested actions.'
-  }
-
-  return section + '\n'
-}
-
-/**
- * Generate natural language description of output schema
- * Provides guidance without enforcing structure during iteration
- *
- * @param schema - Zod schema to describe
- * @returns Natural language description
- */
-function describeOutputSchema(schema: z.ZodSchema): string {
-  const jsonSchema = zodToJsonSchema(schema as z.ZodSchema<any>, {
-    $refStrategy: 'none',
-    errorMessages: true
-  })
-
-  // Simple description - just show the JSON schema
-  // LLM can understand this without needing full enforcement
-  return '```json\n' + JSON.stringify(jsonSchema, null, 2) + '\n```'
-}
+/**
+ * Task Completion Section
+ * Provides guidance on when/how to complete tasks, with optional output schema description
+ */
+
+import type { z } from 'zod'
+import { zodToJsonSchema } from '@alcyone-labs/zod-to-json-schema'
+
+/**
+ * Builds the task completion section of the system prompt
+ * Includes complete action usage and optional output schema guidance
+ *
+ * @param outputSchema - Optional Zod schema for output validation
+ * @returns Task completion prompt section
+ */
+export function buildCompletionPrompt(outputSchema?: z.ZodSchema): string {
+  let section = '## Task Completion Guidance\n\n'
+  section += 'When the task is complete, return a complete action:\n'
+  section += '```json\n{ "type": "complete" }\n```\n\n'
+
+  // Only describe output schema if present
+  if (outputSchema) {
+    section += 'After task completion, the final output will be generated and will need to include:\n'
+    section += describeOutputSchema(outputSchema)
+    section += '\n\nDuring task execution, focus on gathering all necessary information.'
+  } else {
+    section += 'This is a side-effect agent (no output generation). Focus on performing the requested actions.'
+  }
+
+  return section + '\n'
+}
+
+/**
+ * Generate natural language description of output schema
+ * Provides guidance without enforcing structure during iteration
+ *
+ * @param schema - Zod schema to describe
+ * @returns Natural language description
+ */
+function describeOutputSchema(schema: z.ZodSchema): string {
+  const jsonSchema = zodToJsonSchema(schema as z.ZodSchema<any>, {
+    $refStrategy: 'none',
+    errorMessages: true
+  })
+
+  // Simple description - just show the JSON schema
+  // LLM can understand this without needing full enforcement
+  return '```json\n' + JSON.stringify(jsonSchema, null, 2) + '\n```'
+}