@elevasis/core 0.48.0 → 0.48.1

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

@@ -1,116 +1,165 @@
-/**
- * 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 }
-}
+/**
+ * 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')
+    }
+  }
+}
+
+/**
+ * Collapse multiple session-visible messages into one assistant message.
+ *
+ * Session turns should produce at most one visible assistant bubble per
+ * iteration. Non-session executions keep the historical behavior because their
+ * messages are not rendered as conversational bubbles.
+ */
+function normalizeSessionMessages(actions: AgentAction[], sessionCapable: boolean): AgentAction[] {
+  if (!sessionCapable) {
+    return actions
+  }
+
+  const messages = actions.filter((action) => action.type === 'message')
+  if (messages.length <= 1) {
+    return actions
+  }
+
+  const collapsedText = messages.map((message) => message.text).join('\n\n')
+  const collapsedMessage: AgentAction = { type: 'message', text: collapsedText }
+  let emittedCollapsedMessage = false
+
+  return actions.flatMap((action): AgentAction[] => {
+    if (action.type !== 'message') {
+      return [action]
+    }
+
+    if (emittedCollapsedMessage) {
+      return []
+    }
+
+    emittedCollapsedMessage = true
+    return [collapsedMessage]
+  })
+}
+
+/**
+ * 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)
+  const normalizedActions = normalizeSessionMessages(response.nextActions, !!iterationContext.config.sessionCapable)
+
+  let shouldComplete = false
+
+  // Group actions by parallelizability
+  const toolCalls: ToolCallAction[] = []
+  const otherActions: AgentAction[] = []
+
+  for (const action of normalizedActions) {
+    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
+      }
+    }
+  }
+
+  // A user-facing message with no tool calls and no explicit completion ends a
+  // conversational turn. Without this, a tool-less sessionCapable agent loops and
+  // emits multiple message bubbles for a single user turn when the LLM omits `complete`.
+  if (
+    !shouldComplete &&
+    iterationContext.config.sessionCapable &&
+    toolCalls.length === 0 &&
+    normalizedActions.some((a) => a.type === 'message') &&
+    !normalizedActions.some((a) => a.type === 'navigate-knowledge')
+  ) {
+    shouldComplete = true
+  }
+
+  return { shouldComplete }
+}

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

@@ -86,7 +86,7 @@ describe('buildReasoningRequest', () => {
     })
   })
 
-  describe('session capability', () => {
+  describe('session capability', () => {
     it('should set includeMessageAction to false when sessionCapable is not set', () => {
       const context = createMockContext()
       const request = buildReasoningRequest(context)
@@ -113,7 +113,7 @@ describe('buildReasoningRequest', () => {
       expect(request.includeMessageAction).toBe(true)
     })
 
-    it('should set includeMessageAction to false when sessionCapable is false', () => {
+    it('should set includeMessageAction to false when sessionCapable is false', () => {
       const context = createMockContext({
         config: {
           type: 'agent',
@@ -128,12 +128,95 @@ describe('buildReasoningRequest', () => {
         }
       })
       const request = buildReasoningRequest(context)
-
-      expect(request.includeMessageAction).toBe(false)
-    })
-  })
-
-  describe('security prompt', () => {
+
+      expect(request.includeMessageAction).toBe(false)
+    })
+
+    it('should explain session message normalization and completion pairing', () => {
+      const context = createMockContext({
+        config: {
+          type: 'agent',
+          kind: 'utility',
+          resourceId: 'test-agent',
+          name: 'Test Agent',
+          description: 'Test agent',
+          version: '1.0.0',
+          status: 'dev',
+          systemPrompt: 'You are a test agent',
+          sessionCapable: true
+        }
+      })
+      const request = buildReasoningRequest(context)
+
+      expect(request.systemPrompt).toContain('Send at most one message per iteration')
+      expect(request.systemPrompt).toContain('Multiple messages in a session turn are collapsed into one visible assistant message')
+      expect(request.systemPrompt).toContain('send message + complete in the SAME iteration')
+    })
+  })
+
+  describe('action completion prompt contract', () => {
+    it('should allow complete with fire-and-forget tool calls while blocking navigate-knowledge completion', () => {
+      const mockTool = {
+        name: 'navigate_user',
+        description: 'Navigate the UI',
+        inputSchema: z.object({ path: z.string() }),
+        outputSchema: z.object({ ok: z.boolean() }),
+        execute: async () => ({ ok: true })
+      }
+
+      const toolRegistry = new Map()
+      toolRegistry.set('navigate_user', mockTool)
+
+      const context = createMockContext({ toolRegistry })
+      const request = buildReasoningRequest(context)
+
+      expect(request.systemPrompt).toContain('"complete" CAN mix with fire-and-forget tool-call actions')
+      expect(request.systemPrompt).toContain('"complete" CANNOT mix with navigate-knowledge actions')
+      expect(request.systemPrompt).not.toContain('"complete" CANNOT mix with tool-call or navigate-knowledge')
+    })
+
+    it('should tell agents not to complete after navigate-knowledge', () => {
+      const context = createMockContext({
+        config: {
+          type: 'agent',
+          kind: 'utility',
+          resourceId: 'test-agent',
+          name: 'Test Agent',
+          description: 'Test agent',
+          version: '1.0.0',
+          status: 'dev',
+          systemPrompt: 'You are a test agent',
+          sessionCapable: true
+        },
+        knowledgeMap: {
+          nodes: {
+            support: {
+              id: 'support',
+              description: 'Support knowledge',
+              loaded: false,
+              load: async () => ({ prompt: 'Support prompt' })
+            }
+          }
+        }
+      } as Partial<IterationContext>)
+      const request = buildReasoningRequest(context)
+
+      expect(request.includeNavigateKnowledge).toBe(true)
+      expect(request.systemPrompt).toContain('"complete" cannot mix with navigate-knowledge')
+      expect(request.systemPrompt).toContain('You used navigate-knowledge and need the newly loaded knowledge in the next iteration')
+
+      const navigateExampleStart = request.systemPrompt.indexOf('**Iteration 1 - Navigate to load knowledge:**')
+      const nextIterationStart = request.systemPrompt.indexOf('**Iteration 2 - Use newly available tools:**')
+      const navigateExample = request.systemPrompt.slice(navigateExampleStart, nextIterationStart)
+
+      expect(navigateExampleStart).toBeGreaterThan(-1)
+      expect(nextIterationStart).toBeGreaterThan(navigateExampleStart)
+      expect(navigateExample).toContain('"type": "navigate-knowledge"')
+      expect(navigateExample).not.toContain('"complete"')
+    })
+  })
+
+  describe('security prompt', () => {
     it('should include standard security rules by default', () => {
       const context = createMockContext()
       const request = buildReasoningRequest(context)

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

@@ -68,25 +68,28 @@ ${actionsList}
 
 ## 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.`
-      : ''
-  }
+- 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 navigate-knowledge${includeNavigateKnowledge ? '' : ' (when available)'}
+- "complete" can mix with tool-call when the tool is a fire-and-forget side effect and you do not need its result before ending${
+    includeMessageAction
+      ? `
+- Always send at least one message before completing
+- Send at most one message per iteration. Multiple messages in a session turn are collapsed into one visible assistant message.
+- 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
+**Don't use "complete" when:**
+- You just called a tool and need its results
+- You used navigate-knowledge and need the newly loaded knowledge in the next iteration
+- More iterations are needed
 
 ## Examples
 

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

@@ -33,12 +33,13 @@ export function buildToolsPrompt(tools: ToolDefinition[]): string {
   section +=
     '{\n  "type": "tool-call",\n  "id": "unique-id",\n  "name": "tool-name",\n  "input": { /* tool input matching schema */ }\n}\n\n'
 
-  section += '**IMPORTANT RULES:**\n'
-  section += '1. "complete" CANNOT mix with tool-call or navigate-knowledge actions in the same response\n'
-  section += '2. "complete" CAN mix with message — always pair your final message with complete in the same iteration\n'
-  section += '3. To use tools, return ONLY tool-call actions, then wait for results in the next iteration\n'
-  section += '4. After receiving tool results, you can either call more tools OR complete with final answer\n'
-  section += '5. navigate-knowledge actions load new capabilities - tools become available in the next iteration\n'
+  section += '**IMPORTANT RULES:**\n'
+  section += '1. "complete" CANNOT mix with navigate-knowledge actions in the same response\n'
+  section += '2. "complete" CAN mix with message - always pair your final message with complete in the same iteration\n'
+  section += '3. "complete" CAN mix with fire-and-forget tool-call actions when you do not need their results\n'
+  section += '4. To use tools and inspect their results, return ONLY tool-call actions, then wait for results in the next iteration\n'
+  section += '5. After receiving tool results, you can either call more tools OR complete with final answer\n'
+  section += '6. navigate-knowledge actions load new capabilities - tools become available in the next iteration\n'
 
   return section + '\n'
 }

package/src/execution/engine/tools/messages.ts

@@ -14,11 +14,12 @@ import type { ToolingErrorType } from './types'
  * Token usage metadata optionally attached to a ToolCallResponse.
  * Populated for LLM tool calls where cost accounting is available.
  */
-export interface TokenUsage {
-  inputTokens: number
-  outputTokens: number
-  cost?: number
-}
+export interface TokenUsage {
+  inputTokens: number
+  outputTokens: number
+  cost?: number
+  model?: string
+}
 
 /** Outbound tool-call from worker to parent */
 export interface ToolCallMessage {