@xynehq/jaf 0.1.19 → 0.1.21

package/README.md

@@ -89,6 +89,7 @@ examples/
 │   ├── index.ts    # Demo entry point
 │   ├── rag-agent.ts # RAG agent implementation
 │   └── rag-tool.ts  # RAG tool implementation
+├── hooks/turn-end-review.ts # Demonstrates awaiting onTurnEnd reviews between turns
 └── server-demo/    # Development server demo
     └── index.ts    # Server demo entry point
 docs/               # Documentation
@@ -154,6 +155,10 @@ const config = {
   modelProvider,
   maxTurns: 10,
   onEvent: (event) => console.log(event), // Real-time tracing
+  onTurnEnd: async ({ turn, lastAssistantMessage }) => {
+    console.log(`Turn ${turn} completed:`, lastAssistantMessage?.content);
+    // Run reviews, persist breadcrumbs, throttle next turn, etc.
+  },
 };
 
 const initialState = {
@@ -168,6 +173,7 @@ const initialState = {
 const result = await run(initialState, config);
 ```
 
+
 ## 🔄 Function Composition
 
 JAF emphasizes function composition to build complex behaviors from simple, reusable functions:
@@ -619,4 +625,4 @@ npm run typecheck # Type checking
 
 ---
 
-**JAF** - Building the future of functional AI agent systems 🚀
+**JAF** - Building the future of functional AI agent systems 🚀

package/dist/core/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/core/engine.ts"],"names":[],"mappings":"AACA,OAAO,EACL,QAAQ,EACR,SAAS,EACT,SAAS,EAET,UAAU,EAMX,MAAM,YAAY,CAAC;AAMpB,wBAAsB,GAAG,CAAC,GAAG,EAAE,GAAG,EAChC,YAAY,EAAE,QAAQ,CAAC,GAAG,CAAC,EAC3B,MAAM,EAAE,SAAS,CAAC,GAAG,CAAC,GACrB,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAgEzB;AA8CD;;;;;;;GAOG;AACH,wBAAuB,SAAS,CAAC,GAAG,EAAE,GAAG,EACvC,YAAY,EAAE,QAAQ,CAAC,GAAG,CAAC,EAC3B,MAAM,EAAE,SAAS,CAAC,GAAG,CAAC,EACtB,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,GAAG,GAAG,OAAO,CAAC,IAAI,GAAG,GAAG,CAAC,GAC3E,cAAc,CAAC,UAAU,EAAE,IAAI,EAAE,OAAO,CAAC,CAwC3C"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/core/engine.ts"],"names":[],"mappings":"AACA,OAAO,EACL,QAAQ,EACR,SAAS,EACT,SAAS,EAET,UAAU,EASX,MAAM,YAAY,CAAC;AA8CpB,wBAAsB,GAAG,CAAC,GAAG,EAAE,GAAG,EAChC,YAAY,EAAE,QAAQ,CAAC,GAAG,CAAC,EAC3B,MAAM,EAAE,SAAS,CAAC,GAAG,CAAC,GACrB,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CA0EzB;AAsED;;;;;;;GAOG;AACH,wBAAuB,SAAS,CAAC,GAAG,EAAE,GAAG,EACvC,YAAY,EAAE,QAAQ,CAAC,GAAG,CAAC,EAC3B,MAAM,EAAE,SAAS,CAAC,GAAG,CAAC,EACtB,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,GAAG,GAAG,OAAO,CAAC,IAAI,GAAG,GAAG,CAAC,GAC3E,cAAc,CAAC,UAAU,EAAE,IAAI,EAAE,OAAO,CAAC,CAwC3C"}

package/dist/core/engine.js

@@ -1,7 +1,36 @@
-import { getTextContent, } from './types.js';
+import { z } from 'zod';
+import { getTextContent, InterruptionStatus, } from './types.js';
 import { setToolRuntime } from './tool-runtime.js';
 import { buildEffectiveGuardrails, executeInputGuardrailsParallel, executeInputGuardrailsSequential, executeOutputGuardrails } from './guardrails.js';
 import { safeConsole } from '../utils/logger.js';
+import { DEFAULT_CLARIFICATION_DESCRIPTION } from '../utils/constants.js';
+/**
+ * Create the built-in clarification tool
+ */
+function createClarificationTool(config) {
+    const description = config.clarificationDescription || DEFAULT_CLARIFICATION_DESCRIPTION;
+    return {
+        schema: {
+            name: 'request_user_clarification',
+            description,
+            parameters: z.object({
+                question: z.string().describe('The clarifying question to ask the user'),
+                options: z.array(z.object({
+                    id: z.string().describe('Unique identifier for this option'),
+                    label: z.string().describe('Human-readable label shown to the user')
+                })).min(2).describe('clear and meaningful options that user can choose from (minimum 2 options)')
+            })
+        },
+        execute: async (args, _context) => {
+            const trigger = {
+                _clarification_trigger: true,
+                question: args.question,
+                options: args.options
+            };
+            return JSON.stringify(trigger);
+        }
+    };
+}
 export async function run(initialState, config) {
     try {
         config.onEvent?.({
@@ -41,7 +70,12 @@ export async function run(initialState, config) {
         }
         config.onEvent?.({
             type: 'run_end',
-            data: { outcome: result.outcome, traceId: initialState.traceId, runId: initialState.runId }
+            data: {
+                outcome: result.outcome,
+                finalState: result.finalState,
+                traceId: initialState.traceId,
+                runId: initialState.runId
+            }
         });
         return result;
     }
@@ -58,7 +92,12 @@ export async function run(initialState, config) {
         };
         config.onEvent?.({
             type: 'run_end',
-            data: { outcome: errorResult.outcome, traceId: initialState.traceId, runId: initialState.runId }
+            data: {
+                outcome: errorResult.outcome,
+                finalState: errorResult.finalState,
+                traceId: initialState.traceId,
+                runId: initialState.runId
+            }
         });
         return errorResult;
     }
@@ -108,6 +147,20 @@ function createAsyncEventStream() {
         },
     };
 }
+async function runTurnEndHooks(config, payload) {
+    config.onEvent?.({
+        type: 'turn_end',
+        data: { turn: payload.turn, agentName: payload.agentName }
+    });
+    if (config.onTurnEnd) {
+        await config.onTurnEnd({
+            turn: payload.turn,
+            agentName: payload.agentName,
+            state: payload.state,
+            lastAssistantMessage: payload.lastAssistantMessage
+        });
+    }
+}
 /**
  * Stream run events as they happen via an async generator.
  * Consumers can iterate events to build live UIs or forward via SSE.
@@ -238,6 +291,48 @@ async function runInternal(state, config) {
     const resumed = await tryResumePendingToolCalls(state, config);
     if (resumed)
         return resumed;
+    // Check if we're resuming from a clarification
+    if (state.clarifications && state.clarifications.size > 0) {
+        const lastMessage = state.messages[state.messages.length - 1];
+        if (lastMessage?.role === 'tool') {
+            try {
+                const content = JSON.parse(getTextContent(lastMessage.content));
+                if (content.status === InterruptionStatus.AwaitingClarification) {
+                    const clarificationId = content.clarification_id;
+                    const selectedId = state.clarifications.get(clarificationId);
+                    if (selectedId) {
+                        safeConsole.log(`[JAF:ENGINE] Resuming with clarification: ${clarificationId}, selected option: ${selectedId}`);
+                        // Find the selected option to include in the event
+                        const updatedMessages = [...state.messages];
+                        updatedMessages[updatedMessages.length - 1] = {
+                            ...lastMessage,
+                            content: JSON.stringify({
+                                status: InterruptionStatus.ClarificationProvided,
+                                message: `User selected option: ${selectedId}`
+                            })
+                        };
+                        config.onEvent?.({
+                            type: 'clarification_provided',
+                            data: {
+                                clarificationId,
+                                selectedId,
+                                selectedOption: { id: selectedId, label: selectedId }
+                            }
+                        });
+                        // Continue execution with updated messages
+                        const stateWithClarification = {
+                            ...state,
+                            messages: updatedMessages
+                        };
+                        return runInternal(stateWithClarification, config);
+                    }
+                }
+            }
+            catch (e) {
+                safeConsole.log(`[JAF:ENGINE] Error checking for clarification resume:`, e);
+            }
+        }
+    }
     const maxTurns = config.maxTurns ?? 50;
     if (state.turnCount >= maxTurns) {
         return {
@@ -295,26 +390,35 @@ async function runInternal(state, config) {
         inputGuardrailsToRunLength: inputGuardrailsToRun.length,
         hasAdvancedGuardrails
     });
-    safeConsole.log(`[JAF:ENGINE] Using agent: ${currentAgent.name}`);
-    safeConsole.log(`[JAF:ENGINE] Agent has ${currentAgent.tools?.length || 0} tools available`);
-    if (currentAgent.tools) {
-        safeConsole.log(`[JAF:ENGINE] Available tools:`, currentAgent.tools.map(t => t.schema.name));
+    const effectiveTools = [
+        ...(currentAgent.tools || [])
+    ];
+    if (config.allowClarificationRequests) {
+        effectiveTools.push(createClarificationTool(config));
+    }
+    const effectiveAgent = {
+        ...currentAgent,
+        tools: effectiveTools
+    };
+    safeConsole.log(`[JAF:ENGINE] Using agent: ${effectiveAgent.name}`);
+    if (effectiveTools) {
+        safeConsole.log(`[JAF:ENGINE] Available tools:`, effectiveTools.map(t => t.schema.name));
     }
     config.onEvent?.({
         type: 'agent_processing',
         data: {
-            agentName: currentAgent.name,
+            agentName: effectiveAgent.name,
             traceId: state.traceId,
             runId: state.runId,
             turnCount: state.turnCount,
             messageCount: state.messages.length,
-            toolsAvailable: currentAgent.tools?.map(t => ({
+            toolsAvailable: effectiveTools.map(t => ({
                 name: t.schema.name,
                 description: t.schema.description
-            })) || [],
-            handoffsAvailable: currentAgent.handoffs || [],
-            modelConfig: currentAgent.modelConfig,
-            hasOutputCodec: !!currentAgent.outputCodec,
+            })),
+            handoffsAvailable: effectiveAgent.handoffs || [],
+            modelConfig: effectiveAgent.modelConfig,
+            hasOutputCodec: !!effectiveAgent.outputCodec,
             context: state.context,
             currentState: {
                 messages: state.messages.map(m => ({
@@ -341,18 +445,18 @@ async function runInternal(state, config) {
     const turnNumber = state.turnCount + 1;
     config.onEvent?.({ type: 'turn_start', data: { turn: turnNumber, agentName: currentAgent.name } });
     const llmCallData = {
-        agentName: currentAgent.name,
+        agentName: effectiveAgent.name,
         model: model || 'unknown',
         traceId: state.traceId,
         runId: state.runId,
         messages: state.messages,
-        tools: currentAgent.tools?.map(tool => ({
+        tools: effectiveTools.map(tool => ({
             name: tool.schema.name,
             description: tool.schema.description,
             parameters: tool.schema.parameters
         })),
         modelConfig: {
-            ...currentAgent.modelConfig,
+            ...effectiveAgent.modelConfig,
             modelOverride: config.modelOverride
         },
         turnCount: state.turnCount,
@@ -373,6 +477,12 @@ async function runInternal(state, config) {
                 if (executionMode === 'sequential') {
                     const guardrailResult = await executeInputGuardrailsSequential(inputGuardrailsToRun, firstUserMessage, config);
                     if (!guardrailResult.isValid) {
+                        await runTurnEndHooks(config, {
+                            turn: turnNumber,
+                            agentName: currentAgent.name,
+                            state,
+                            lastAssistantMessage: undefined
+                        });
                         return {
                             finalState: state,
                             outcome: {
@@ -385,11 +495,11 @@ async function runInternal(state, config) {
                         };
                     }
                     safeConsole.log(`✅ All input guardrails passed. Starting LLM call.`);
-                    llmResponse = await config.modelProvider.getCompletion(state, currentAgent, config);
+                    llmResponse = await config.modelProvider.getCompletion(state, effectiveAgent, config);
                 }
                 else {
                     const guardrailPromise = executeInputGuardrailsParallel(inputGuardrailsToRun, firstUserMessage, config);
-                    const llmPromise = config.modelProvider.getCompletion(state, currentAgent, config);
+                    const llmPromise = config.modelProvider.getCompletion(state, effectiveAgent, config);
                     const [guardrailResult, llmResult] = await Promise.all([
                         guardrailPromise,
                         llmPromise
@@ -398,6 +508,12 @@ async function runInternal(state, config) {
                     if (!guardrailResult.isValid) {
                         safeConsole.log(`🚨 Input guardrail violation: ${guardrailResult.errorMessage}`);
                         safeConsole.log(`[JAF:GUARDRAILS] Discarding LLM response due to input guardrail violation`);
+                        await runTurnEndHooks(config, {
+                            turn: turnNumber,
+                            agentName: currentAgent.name,
+                            state,
+                            lastAssistantMessage: undefined
+                        });
                         return {
                             finalState: state,
                             outcome: {
@@ -422,6 +538,12 @@ async function runInternal(state, config) {
                             type: 'guardrail_violation',
                             data: { stage: 'input', reason: errorMessage }
                         });
+                        await runTurnEndHooks(config, {
+                            turn: turnNumber,
+                            agentName: currentAgent.name,
+                            state,
+                            lastAssistantMessage: undefined
+                        });
                         return {
                             finalState: state,
                             outcome: {
@@ -434,14 +556,14 @@ async function runInternal(state, config) {
                         };
                     }
                 }
-                llmResponse = await config.modelProvider.getCompletion(state, currentAgent, config);
+                llmResponse = await config.modelProvider.getCompletion(state, effectiveAgent, config);
             }
         }
         else {
             if (typeof config.modelProvider.getCompletionStream === 'function') {
                 try {
                     streamingUsed = true;
-                    const stream = config.modelProvider.getCompletionStream(state, currentAgent, config);
+                    const stream = config.modelProvider.getCompletionStream(state, effectiveAgent, config);
                     let aggregatedText = '';
                     const toolCalls = [];
                     for await (const chunk of stream) {
@@ -509,11 +631,11 @@ async function runInternal(state, config) {
                 catch (e) {
                     streamingUsed = false;
                     assistantEventStreamed = false;
-                    llmResponse = await config.modelProvider.getCompletion(state, currentAgent, config);
+                    llmResponse = await config.modelProvider.getCompletion(state, effectiveAgent, config);
                 }
             }
             else {
-                llmResponse = await config.modelProvider.getCompletion(state, currentAgent, config);
+                llmResponse = await config.modelProvider.getCompletion(state, effectiveAgent, config);
             }
         }
     }
@@ -521,7 +643,7 @@ async function runInternal(state, config) {
         if (typeof config.modelProvider.getCompletionStream === 'function') {
             try {
                 streamingUsed = true;
-                const stream = config.modelProvider.getCompletionStream(state, currentAgent, config);
+                const stream = config.modelProvider.getCompletionStream(state, effectiveAgent, config);
                 let aggregatedText = '';
                 const toolCalls = [];
                 for await (const chunk of stream) {
@@ -589,11 +711,11 @@ async function runInternal(state, config) {
             catch (e) {
                 streamingUsed = false;
                 assistantEventStreamed = false;
-                llmResponse = await config.modelProvider.getCompletion(state, currentAgent, config);
+                llmResponse = await config.modelProvider.getCompletion(state, effectiveAgent, config);
             }
         }
         else {
-            llmResponse = await config.modelProvider.getCompletion(state, currentAgent, config);
+            llmResponse = await config.modelProvider.getCompletion(state, effectiveAgent, config);
         }
     }
     const usage = llmResponse?.usage;
@@ -631,7 +753,12 @@ async function runInternal(state, config) {
     }
     catch { /* ignore */ }
     if (!llmResponse.message) {
-        config.onEvent?.({ type: 'turn_end', data: { turn: turnNumber, agentName: currentAgent.name } });
+        await runTurnEndHooks(config, {
+            turn: turnNumber,
+            agentName: currentAgent.name,
+            state,
+            lastAssistantMessage: undefined
+        });
         return {
             finalState: state,
             outcome: {
@@ -668,7 +795,7 @@ async function runInternal(state, config) {
             config.onEvent?.({ type: 'tool_requests', data: { toolCalls: requests } });
         }
         catch { /* ignore */ }
-        const toolResults = await executeToolCalls(llmResponse.message.tool_calls, currentAgent, state, config);
+        const toolResults = await executeToolCalls(llmResponse.message.tool_calls, effectiveAgent, state, config);
         const interruptions = toolResults
             .map(r => r.interruption)
             .filter((interruption) => interruption !== undefined);
@@ -676,6 +803,7 @@ async function runInternal(state, config) {
             const completedToolResults = toolResults.filter(r => !r.interruption);
             const approvalRequiredResults = toolResults.filter(r => r.interruption);
             const updatedApprovals = new Map(state.approvals ?? []);
+            const updatedClarifications = new Map(state.clarifications ?? []);
             for (const interruption of interruptions) {
                 if (interruption.type === 'tool_approval') {
                     updatedApprovals.set(interruption.toolCall.id, {
@@ -684,12 +812,26 @@ async function runInternal(state, config) {
                         additionalContext: { status: 'pending', timestamp: new Date().toISOString() }
                     });
                 }
+                else if (interruption.type === 'clarification_required') {
+                    // Emit clarification requested event
+                    config.onEvent?.({
+                        type: 'clarification_requested',
+                        data: {
+                            clarificationId: interruption.clarificationId,
+                            question: interruption.question,
+                            options: interruption.options,
+                            context: interruption.context
+                        }
+                    });
+                    safeConsole.log(`[JAF:ENGINE] Clarification requested: ${interruption.question}`);
+                }
             }
             const interruptedState = {
                 ...state,
                 messages: [...newMessages, ...completedToolResults.map(r => r.message)],
                 turnCount: updatedTurnCount,
                 approvals: updatedApprovals,
+                clarifications: updatedClarifications,
             };
             if (config.memory?.autoStore && config.conversationId) {
                 safeConsole.log(`[JAF:ENGINE] Storing conversation state due to interruption for ${config.conversationId}`);
@@ -699,6 +841,12 @@ async function runInternal(state, config) {
                 };
                 await storeConversationHistory(stateForStorage, config);
             }
+            await runTurnEndHooks(config, {
+                turn: turnNumber,
+                agentName: currentAgent.name,
+                state: interruptedState,
+                lastAssistantMessage: assistantMessage
+            });
             return {
                 finalState: interruptedState,
                 outcome: {
@@ -707,7 +855,7 @@ async function runInternal(state, config) {
                 },
             };
         }
-        safeConsole.log(`[JAF:ENGINE] Tool execution completed. Results count:`, toolResults.length);
+        // safeConsole.log(`[JAF:ENGINE] Tool execution completed. Results count:`, toolResults.length);
         config.onEvent?.({
             type: 'tool_results_to_llm',
             data: { results: toolResults.map(r => r.message) }
@@ -721,8 +869,15 @@ async function runInternal(state, config) {
                         type: 'handoff_denied',
                         data: { from: currentAgent.name, to: targetAgent, reason: `Agent ${currentAgent.name} cannot handoff to ${targetAgent}` }
                     });
+                    const failureState = { ...state, messages: newMessages, turnCount: updatedTurnCount };
+                    await runTurnEndHooks(config, {
+                        turn: turnNumber,
+                        agentName: currentAgent.name,
+                        state: failureState,
+                        lastAssistantMessage: assistantMessage
+                    });
                     return {
-                        finalState: { ...state, messages: newMessages, turnCount: updatedTurnCount },
+                        finalState: failureState,
                         outcome: {
                             status: 'error',
                             error: {
@@ -759,7 +914,12 @@ async function runInternal(state, config) {
                     turnCount: updatedTurnCount,
                     approvals: state.approvals ?? new Map(),
                 };
-                config.onEvent?.({ type: 'turn_end', data: { turn: turnNumber, agentName: currentAgent.name } });
+                await runTurnEndHooks(config, {
+                    turn: turnNumber,
+                    agentName: currentAgent.name,
+                    state: nextState,
+                    lastAssistantMessage: assistantMessage
+                });
                 return runInternal(nextState, config);
             }
         }
@@ -785,7 +945,12 @@ async function runInternal(state, config) {
             turnCount: updatedTurnCount,
             approvals: state.approvals ?? new Map(),
         };
-        config.onEvent?.({ type: 'turn_end', data: { turn: turnNumber, agentName: currentAgent.name } });
+        await runTurnEndHooks(config, {
+            turn: turnNumber,
+            agentName: currentAgent.name,
+            state: nextState,
+            lastAssistantMessage: assistantMessage
+        });
         return runInternal(nextState, config);
     }
     if (llmResponse.message.content) {
@@ -793,7 +958,12 @@ async function runInternal(state, config) {
             const parseResult = currentAgent.outputCodec.safeParse(tryParseJSON(llmResponse.message.content));
             if (!parseResult.success) {
                 config.onEvent?.({ type: 'decode_error', data: { errors: parseResult.error.issues } });
-                config.onEvent?.({ type: 'turn_end', data: { turn: turnNumber, agentName: currentAgent.name } });
+                await runTurnEndHooks(config, {
+                    turn: turnNumber,
+                    agentName: currentAgent.name,
+                    state: { ...state, messages: newMessages, turnCount: updatedTurnCount },
+                    lastAssistantMessage: assistantMessage
+                });
                 return {
                     finalState: { ...state, messages: newMessages, turnCount: updatedTurnCount },
                     outcome: {
@@ -825,7 +995,12 @@ async function runInternal(state, config) {
                 }
             }
             if (!outputGuardrailResult.isValid) {
-                config.onEvent?.({ type: 'turn_end', data: { turn: turnNumber, agentName: currentAgent.name } });
+                await runTurnEndHooks(config, {
+                    turn: turnNumber,
+                    agentName: currentAgent.name,
+                    state: { ...state, messages: newMessages, turnCount: updatedTurnCount },
+                    lastAssistantMessage: assistantMessage
+                });
                 return {
                     finalState: { ...state, messages: newMessages, turnCount: updatedTurnCount },
                     outcome: {
@@ -839,7 +1014,12 @@ async function runInternal(state, config) {
             }
             config.onEvent?.({ type: 'final_output', data: { output: parseResult.data } });
             // End of turn
-            config.onEvent?.({ type: 'turn_end', data: { turn: turnNumber, agentName: currentAgent.name } });
+            await runTurnEndHooks(config, {
+                turn: turnNumber,
+                agentName: currentAgent.name,
+                state: { ...state, messages: newMessages, turnCount: updatedTurnCount },
+                lastAssistantMessage: assistantMessage
+            });
             return {
                 finalState: { ...state, messages: newMessages, turnCount: updatedTurnCount },
                 outcome: {
@@ -869,7 +1049,12 @@ async function runInternal(state, config) {
                 }
             }
             if (!outputGuardrailResult.isValid) {
-                config.onEvent?.({ type: 'turn_end', data: { turn: turnNumber, agentName: currentAgent.name } });
+                await runTurnEndHooks(config, {
+                    turn: turnNumber,
+                    agentName: currentAgent.name,
+                    state: { ...state, messages: newMessages, turnCount: updatedTurnCount },
+                    lastAssistantMessage: assistantMessage
+                });
                 return {
                     finalState: { ...state, messages: newMessages, turnCount: updatedTurnCount },
                     outcome: {
@@ -883,7 +1068,12 @@ async function runInternal(state, config) {
             }
             config.onEvent?.({ type: 'final_output', data: { output: llmResponse.message.content } });
             // End of turn
-            config.onEvent?.({ type: 'turn_end', data: { turn: turnNumber, agentName: currentAgent.name } });
+            await runTurnEndHooks(config, {
+                turn: turnNumber,
+                agentName: currentAgent.name,
+                state: { ...state, messages: newMessages, turnCount: updatedTurnCount },
+                lastAssistantMessage: assistantMessage
+            });
             return {
                 finalState: { ...state, messages: newMessages, turnCount: updatedTurnCount },
                 outcome: {
@@ -893,7 +1083,12 @@ async function runInternal(state, config) {
             };
         }
     }
-    config.onEvent?.({ type: 'turn_end', data: { turn: turnNumber, agentName: currentAgent.name } });
+    await runTurnEndHooks(config, {
+        turn: turnNumber,
+        agentName: currentAgent.name,
+        state: { ...state, messages: newMessages, turnCount: updatedTurnCount },
+        lastAssistantMessage: assistantMessage
+    });
     safeConsole.error(`[JAF:ENGINE] No tool calls or content returned by model. LLMResponse: `, llmResponse);
     return {
         finalState: { ...state, messages: newMessages, turnCount: updatedTurnCount },
@@ -938,14 +1133,10 @@ async function executeToolCalls(toolCalls, agent, state, config) {
                 });
                 // If event handler returns a value, use it to override the args
                 if (beforeEventResponse !== undefined && beforeEventResponse !== null) {
-                    console.log(`[JAF:ENGINE] Tool args modified by before_tool_execution event handler for ${toolCall.function.name}`);
-                    console.log(`[JAF:ENGINE] Original args:`, rawArgs);
-                    console.log(`[JAF:ENGINE] Modified args:`, beforeEventResponse);
                     rawArgs = beforeEventResponse;
                 }
             }
             catch (eventError) {
-                console.error(`[JAF:ENGINE] Error in before_tool_execution event handler:`, eventError);
                 // Continue with original args if event handler fails
             }
         }
@@ -1079,6 +1270,38 @@ async function executeToolCalls(toolCalls, agent, state, config) {
                 ? { ...state.context, ...additionalContext }
                 : state.context;
             let toolResult = await tool.execute(parseResult.data, contextWithAdditional);
+            // Check if this is a clarification request
+            // The clarification tool returns a JSON string containing the trigger marker
+            if (typeof toolResult === 'string') {
+                try {
+                    const parsed = JSON.parse(toolResult);
+                    if (parsed && typeof parsed === 'object' && '_clarification_trigger' in parsed && parsed._clarification_trigger === true) {
+                        const clarificationId = `clarify_${toolCall.id}`;
+                        const trigger = parsed;
+                        return {
+                            interruption: {
+                                type: 'clarification_required',
+                                clarificationId,
+                                question: trigger.question,
+                                options: trigger.options,
+                                context: trigger.context
+                            },
+                            message: {
+                                role: 'tool',
+                                content: JSON.stringify({
+                                    status: InterruptionStatus.AwaitingClarification,
+                                    clarification_id: clarificationId,
+                                    message: 'Waiting for user to provide clarification'
+                                }),
+                                tool_call_id: toolCall.id
+                            }
+                        };
+                    }
+                }
+                catch {
+                    // Not a clarification trigger, continue with normal processing
+                }
+            }
             // Apply onAfterToolExecution callback if configured
             if (config.onAfterToolExecution) {
                 try {
@@ -1104,14 +1327,13 @@ async function executeToolCalls(toolCalls, agent, state, config) {
             let toolResultObj = null;
             if (typeof toolResult === 'string') {
                 resultString = toolResult;
-                safeConsole.log(`[JAF:ENGINE] Tool ${toolCall.function.name} returned string:`, resultString);
+                safeConsole.log(`[JAF:ENGINE] Tool ${toolCall.function.name}`);
             }
             else {
                 toolResultObj = toolResult;
                 const { toolResultToString } = await import('./tool-results');
                 resultString = toolResultToString(toolResult);
-                safeConsole.log(`[JAF:ENGINE] Tool ${toolCall.function.name} returned ToolResult:`, toolResult);
-                safeConsole.log(`[JAF:ENGINE] Converted to string:`, resultString);
+                safeConsole.log(`[JAF:ENGINE] Tool ${toolCall.function.name} `);
             }
             config.onEvent?.({
                 type: 'tool_call_end',