@ariaflowagents/core 0.7.1 → 0.8.1

package/dist/runtime/pipeline/AgentExecuteStage.js

@@ -0,0 +1,889 @@
+/**
+ * AgentExecuteStage — Stage 4 of the turn pipeline.
+ *
+ * Absorbs the full runLoop from Runtime: handoff loop, flow agent execution,
+ * LLM agent execution (structured triage, streamText, tool loop),
+ * tool enforcement, output processing, result handling, and handoff delegation.
+ */
+import crypto from 'node:crypto';
+import { streamText, streamObject, stepCountIs } from 'ai';
+import { z } from 'zod';
+import { runContextGatherStage, emitGatherEvents } from './ContextGatherStage.js';
+import { runContextAssembleStage, buildStructuredTriagePrompt } from './ContextAssembleStage.js';
+import { isFlowAgent, isTriageAgent } from './agentTypeGuards.js';
+import { getFlowState, setFlowState, clearFlowState, updateFlowStateSnapshot, appendSessionMessage, appendSessionMessages, } from './sessionUtils.js';
+import { runOutputProcessing, postProcessPersistedAssistantMessages, getAgentOutputProcessors, } from './outputProcessing.js';
+import { checkStopConditions } from '../../guards/StopConditions.js';
+import { createHandoffTool, isHandoffResult } from '../../tools/handoff.js';
+import { isFinalResult } from '../../tools/final.js';
+import { runInputProcessors } from '../../processors/ProcessorRunner.js';
+import { getChunkArgs, getChunkErrorMessage, getChunkResult, getChunkToolCallId } from '../../utils/streamChunk.js';
+import { isRecord } from '../../utils/isRecord.js';
+import { estimateTokenCount } from '../ContextBudget.js';
+/**
+ * Runs the full agent execution loop (Stage 4).
+ * Handles handoffs, flow agents, LLM agents, structured triage, tool loops.
+ */
+export async function* runAgentExecuteStage(execInput, services) {
+    const { context, injectionQueue, abortController } = execInput;
+    let currentInput = execInput.input;
+    const abortSignal = abortController?.signal;
+    let interruptionEmitted = false;
+    let circularRecoveryActive = false;
+    let circularRecoveryAttempts = 0;
+    while (context.handoffStack.length < services.maxHandoffs) {
+        if (abortSignal?.aborted) {
+            if (!interruptionEmitted) {
+                interruptionEmitted = true;
+                yield* services.streamEmitter.emit(context, {
+                    type: 'interrupted',
+                    sessionId: context.session.id,
+                    reason: abortSignal.reason ?? 'Operation cancelled',
+                    timestamp: new Date(),
+                    lastAgentId: context.agentId,
+                    lastStep: context.stepCount,
+                });
+            }
+            return;
+        }
+        // Circular handoff detection
+        if (services.agentStateController.isCircularHandoff(context.handoffStack, context.agentId) && !circularRecoveryActive) {
+            const err = `Circular handoff detected: ${context.handoffStack.join(' -> ')} -> ${context.agentId}`;
+            yield* services.streamEmitter.emit(context, { type: 'error', error: err });
+            circularRecoveryAttempts += 1;
+            if (circularRecoveryAttempts > 1) {
+                yield* emitCircularHandoffFallback(context, services);
+                return;
+            }
+            circularRecoveryActive = true;
+            context.handoffStack = [];
+        }
+        context.handoffStack.push(context.agentId);
+        const agent = services.agents.get(context.agentId);
+        if (!agent) {
+            yield* services.streamEmitter.emit(context, { type: 'error', error: `Agent "${context.agentId}" not found` });
+            return;
+        }
+        // Agent-specific input processors
+        if (agent.inputProcessors && agent.inputProcessors.length > 0) {
+            const procCtx = {
+                session: context.session,
+                agentId: agent.id,
+                toolCallHistory: context.toolCallHistory,
+                abortSignal,
+            };
+            const outcome = await runInputProcessors({
+                processors: agent.inputProcessors,
+                input: currentInput,
+                messages: context.session.messages,
+                context: procCtx,
+            });
+            if (outcome.blocked) {
+                yield* services.streamEmitter.emit(context, {
+                    type: 'tripwire',
+                    phase: 'input',
+                    processorId: outcome.processorId,
+                    reason: outcome.reason,
+                    message: outcome.message,
+                });
+                yield* services.streamEmitter.emit(context, { type: 'text-delta', text: outcome.message });
+                yield* services.streamEmitter.emit(context, { type: 'turn-end' });
+                return;
+            }
+            if (outcome.input !== currentInput) {
+                currentInput = outcome.input;
+                const last = context.session.messages[context.session.messages.length - 1];
+                if (last && last.role === 'user' && typeof last.content === 'string') {
+                    last.content = currentInput;
+                    services.conversationState.touchSession(context.session);
+                }
+            }
+        }
+        yield* services.streamEmitter.emit(context, { type: 'agent-start', agentId: agent.id });
+        await services.hookRunner.onAgentStart(context, agent.id);
+        // Stage 2: Context Gather
+        const gatherResult = await runContextGatherStage(agent, context, currentInput, services, abortSignal);
+        yield* emitGatherEvents(gatherResult.autoRetrieveEvents, context, services);
+        const { extractionSnapshot, activeRoutes } = gatherResult;
+        // Stage 3: Context Assemble
+        const turnToolErrors = [];
+        const assembleGen = runContextAssembleStage({ agent, context, injectionQueue, gatherResult, currentInput, circularRecoveryActive }, services);
+        let assembleNext = await assembleGen.next();
+        while (!assembleNext.done) {
+            yield assembleNext.value;
+            assembleNext = await assembleGen.next();
+        }
+        let system = assembleNext.value.systemPrompt;
+        const handoffCandidates = circularRecoveryActive ? [] : getHandoffCandidates(agent, services, activeRoutes);
+        const handoffTool = handoffCandidates.length > 0
+            ? createHandoffTool(handoffCandidates, context.agentId)
+            : null;
+        let handoffTo = null;
+        let handoffReason = 'No reason provided';
+        if (isFlowAgent(agent)) {
+            yield* runFlowAgentStep(agent, context, currentInput, system, handoffTool, abortSignal, services, turnToolErrors, interruptionEmitted, (to, reason) => { handoffTo = to; handoffReason = reason ?? 'No reason provided'; }, (v) => { interruptionEmitted = v; });
+        }
+        else {
+            const result = yield* runLLMAgentSteps(agent, context, currentInput, system, handoffTool, abortSignal, services, turnToolErrors, interruptionEmitted, activeRoutes, (to, reason) => { handoffTo = to; handoffReason = reason ?? 'No reason provided'; }, (v) => { interruptionEmitted = v; });
+            if (result === 'return')
+                return;
+        }
+        yield* services.streamEmitter.emit(context, { type: 'agent-end', agentId: agent.id });
+        await services.hookRunner.onAgentEnd(context, agent.id);
+        if (circularRecoveryActive && handoffTo) {
+            yield* services.streamEmitter.emit(context, {
+                type: 'error',
+                error: `Circular handoff recovery failed: attempted handoff ${context.agentId} -> ${handoffTo}`,
+            });
+            yield* emitCircularHandoffFallback(context, services);
+            return;
+        }
+        if (circularRecoveryActive) {
+            circularRecoveryActive = false;
+        }
+        if (!handoffTo)
+            break;
+        await services.hookRunner.onHandoff(context, context.agentId, handoffTo, handoffReason);
+        yield* services.streamEmitter.emit(context, {
+            type: 'handoff',
+            from: context.agentId,
+            to: handoffTo,
+            reason: handoffReason,
+        });
+        services.agentStateController.recordHandoff({
+            session: context.session,
+            fromAgentId: context.agentId,
+            toAgentId: handoffTo,
+            reason: handoffReason,
+        });
+        // Apply handoff input filter if configured
+        const handoffAgent = services.agents.get(context.agentId);
+        const agentRoutes = handoffAgent?.routes;
+        const matchedRoute = agentRoutes?.find((r) => r.agentId === handoffTo);
+        if (matchedRoute?.inputFilter) {
+            try {
+                const filterInput = {
+                    messages: [...context.session.messages],
+                    workingMemory: { ...context.session.workingMemory },
+                    sourceAgentId: context.agentId,
+                    targetAgentId: handoffTo,
+                    reason: handoffReason,
+                };
+                const filterResult = await matchedRoute.inputFilter(filterInput);
+                context.session.messages = filterResult.messages;
+                const internalState = {};
+                const internalKeys = [
+                    'runtimeEventLog',
+                    '__ariaSessionTurn',
+                    '__ariaRedactCarry',
+                    'flowStateByAgent',
+                    '__ariaAssistantText',
+                    '__ariaContextBudget',
+                ];
+                for (const key of internalKeys) {
+                    if (key in context.session.workingMemory) {
+                        internalState[key] = context.session.workingMemory[key];
+                    }
+                }
+                context.session.workingMemory = { ...filterResult.workingMemory, ...internalState };
+            }
+            catch (err) {
+                console.warn('[AriaFlow] Handoff input filter failed, using full context:', err);
+            }
+        }
+        services.agentStateController.setActiveAgent(context.session, handoffTo);
+        await services.eventLog.checkpoint(context.session);
+        if (services.sessionCache) {
+            services.sessionCache.put(context.session);
+        }
+        context.agentId = handoffTo;
+    }
+    if (context.handoffStack.length >= services.maxHandoffs) {
+        yield* services.streamEmitter.emit(context, { type: 'error', error: `Maximum handoffs (${services.maxHandoffs}) exceeded` });
+    }
+}
+// --- Flow agent step ---
+async function* runFlowAgentStep(agent, context, currentInput, system, handoffTool, abortSignal, services, turnToolErrors, interruptionEmitted, onHandoff, setInterruptionEmitted) {
+    const stopResult = checkStopConditions(context, services.stopConditions);
+    if (stopResult.shouldStop) {
+        yield* services.streamEmitter.emit(context, { type: 'error', error: `Stopped: ${stopResult.reason}` });
+        return;
+    }
+    const agentMaxSteps = agent.maxSteps ?? agent.maxTurns ?? services.maxSteps;
+    if (agentMaxSteps <= 0) {
+        yield* services.streamEmitter.emit(context, { type: 'error', error: `Max steps exceeded for agent "${agent.id}"` });
+        return;
+    }
+    context.stepCount += 1;
+    yield* services.streamEmitter.emit(context, { type: 'step-start', step: context.stepCount, agentId: agent.id });
+    await services.hookRunner.onStepStart(context, context.stepCount);
+    const toolCalls = [];
+    let handoffTo = null;
+    let handoffReason = 'No reason provided';
+    try {
+        const helpers = buildFlowExecutorHelpers(services);
+        for await (const part of services.flowExecutor.runFlowAgent(agent, context, currentInput, system, handoffTool ?? undefined, (target, reason) => {
+            handoffTo = target;
+            handoffReason = reason ?? 'No reason provided';
+            onHandoff(target, reason);
+        }, toolCalls, helpers, abortSignal)) {
+            yield part;
+        }
+        context.consecutiveErrors = 0;
+        if (context.session.metadata) {
+            context.session.metadata.totalSteps += 1;
+        }
+        yield* services.streamEmitter.emit(context, { type: 'step-end', step: context.stepCount, agentId: agent.id });
+        await services.hookRunner.onStepEnd(context, context.stepCount, {
+            toolCalls,
+            finishReason: 'flow',
+            tokensUsed: 0,
+            handoffTo: handoffTo ?? undefined,
+        });
+    }
+    catch (error) {
+        if (abortSignal?.aborted) {
+            if (!interruptionEmitted) {
+                setInterruptionEmitted(true);
+                yield* services.streamEmitter.emit(context, {
+                    type: 'interrupted',
+                    sessionId: context.session.id,
+                    reason: abortSignal.reason ?? 'Operation cancelled',
+                    timestamp: new Date(),
+                    lastAgentId: context.agentId,
+                    lastStep: context.stepCount,
+                });
+            }
+            return;
+        }
+        context.consecutiveErrors += 1;
+        await services.hookRunner.onError(context, error);
+        yield* services.streamEmitter.emit(context, { type: 'error', error: error.message });
+        if (context.consecutiveErrors >= 3) {
+            return;
+        }
+    }
+}
+// --- LLM agent step loop ---
+async function* runLLMAgentSteps(agent, context, currentInput, system, handoffTool, abortSignal, services, turnToolErrors, interruptionEmitted, activeRoutes, onHandoff, setInterruptionEmitted) {
+    const tools = wrapToolsWithEnforcement(context, handoffTool ? { ...agent.tools, handoff: handoffTool } : { ...agent.tools }, services);
+    let agentSteps = 0;
+    const agentMaxSteps = agent.maxSteps ?? agent.maxTurns ?? services.maxSteps;
+    let handoffTo = null;
+    let handoffReason = 'No reason provided';
+    while (agentSteps < agentMaxSteps) {
+        const stopResult = checkStopConditions(context, services.stopConditions);
+        if (stopResult.shouldStop) {
+            yield* services.streamEmitter.emit(context, { type: 'error', error: `Stopped: ${stopResult.reason}` });
+            return 'return';
+        }
+        agentSteps += 1;
+        context.stepCount += 1;
+        yield* services.streamEmitter.emit(context, { type: 'step-start', step: context.stepCount, agentId: agent.id });
+        await services.hookRunner.onStepStart(context, context.stepCount);
+        try {
+            const model = agent.model ?? services.defaultModel;
+            if (!model) {
+                throw new Error(`Agent "${agent.id}" is missing a model`);
+            }
+            // Structured triage
+            if (isTriageAgent(agent) && agent.triageMode === 'structured') {
+                const triageResult = yield* runStructuredTriage(agent, context, system, abortSignal, services, activeRoutes);
+                handoffTo = triageResult.handoffTo;
+                handoffReason = triageResult.handoffReason;
+                onHandoff(handoffTo, handoffReason);
+                yield* services.streamEmitter.emit(context, { type: 'step-end', step: context.stepCount, agentId: agent.id });
+                await services.hookRunner.onStepEnd(context, context.stepCount, {
+                    toolCalls: [],
+                    finishReason: 'handoff',
+                    tokensUsed: 0,
+                    handoffTo: handoffTo ?? undefined,
+                });
+                break;
+            }
+            // onBeforeModelCall hook
+            if (services.config.hooks?.onBeforeModelCall) {
+                system = await runBeforeModelCallHook(agent, context, system, services);
+            }
+            const result = streamText({
+                model: model,
+                system,
+                messages: context.session.messages,
+                tools,
+                abortSignal,
+                stopWhen: stepCountIs(agent.toolMaxSteps ?? 5),
+                experimental_context: {
+                    session: context.session,
+                    agentId: agent.id,
+                },
+                experimental_telemetry: agent.telemetry ?? services.config.telemetry,
+            });
+            const toolCalls = [];
+            let finalResult = null;
+            let finalEmitted = false;
+            const outputProcessors = getAgentOutputProcessors(agent, services.outputProcessors);
+            const bufferOutput = services.outputProcessorMode === 'buffer' && outputProcessors.length > 0;
+            const bufferedParts = [];
+            let stoppedByGuard = false;
+            // Process stream chunks
+            for await (const chunk of result.fullStream) {
+                const chunkResult = yield* processStreamChunk(chunk, context, agent, services, toolCalls, turnToolErrors, finalResult, finalEmitted, bufferOutput, bufferedParts);
+                if (chunkResult.finalResult)
+                    finalResult = chunkResult.finalResult;
+                if (chunkResult.finalEmitted)
+                    finalEmitted = chunkResult.finalEmitted;
+                if (chunkResult.handoffTo) {
+                    handoffTo = chunkResult.handoffTo;
+                    handoffReason = chunkResult.handoffReason ?? 'No reason provided';
+                    onHandoff(handoffTo, handoffReason);
+                }
+                if (chunkResult.stoppedByGuard) {
+                    stoppedByGuard = true;
+                    break;
+                }
+            }
+            if (stoppedByGuard)
+                return 'return';
+            const response = await result.response;
+            const finishReason = finalResult ? 'final' : await result.finishReason;
+            // Finalize buffered output
+            if (finalResult || (bufferOutput && finishReason !== 'tool-calls') || turnToolErrors.length > 0) {
+                let rawText = finalResult ? finalResult.text : bufferedParts.join('');
+                if (turnToolErrors.length > 0) {
+                    const failedTools = turnToolErrors.map(e => `\`${e.toolName}\``).join(', ');
+                    rawText = `I encountered an error while using the following tools: ${failedTools}. I cannot proceed with the requested action at this time.`;
+                    yield* services.streamEmitter.emit(context, {
+                        type: 'error',
+                        error: `Turn blocked by critical tool failures: ${failedTools}`,
+                    });
+                }
+                const getAbortSignal = () => abortSignal;
+                const processed = await runOutputProcessing(agent, context, rawText, services.outputProcessors, services.outputRedactions, getAbortSignal);
+                if (processed.tripwire) {
+                    yield* services.streamEmitter.emit(context, {
+                        type: 'tripwire',
+                        phase: 'output',
+                        processorId: processed.tripwire.processorId,
+                        reason: processed.tripwire.reason,
+                        message: processed.tripwire.message,
+                    });
+                }
+                if (bufferOutput || turnToolErrors.length > 0) {
+                    yield* services.streamEmitter.emit(context, { type: 'text-delta', text: processed.text });
+                }
+                appendSessionMessage(context.session, { role: 'assistant', content: processed.text }, services.conversationState);
+            }
+            else {
+                const beforeLen = context.session.messages.length;
+                appendSessionMessages(context.session, response.messages, services.conversationState);
+                const getAbortSignal = () => abortSignal;
+                const tripwires = await postProcessPersistedAssistantMessages(agent, context, beforeLen, services.outputProcessors, services.outputRedactions, getAbortSignal);
+                for (const t of tripwires) {
+                    yield* services.streamEmitter.emit(context, {
+                        type: 'tripwire',
+                        phase: 'output',
+                        processorId: t.processorId,
+                        reason: t.reason,
+                        message: t.message,
+                    });
+                }
+            }
+            const usage = await result.usage;
+            const totalTokens = usage.totalTokens ?? 0;
+            context.totalTokens += totalTokens;
+            if (context.session.metadata) {
+                context.session.metadata.totalTokens += totalTokens;
+                context.session.metadata.totalSteps += 1;
+            }
+            context.consecutiveErrors = 0;
+            yield* services.streamEmitter.emit(context, { type: 'step-end', step: context.stepCount, agentId: agent.id });
+            await services.hookRunner.onStepEnd(context, context.stepCount, {
+                toolCalls,
+                finishReason,
+                tokensUsed: totalTokens,
+                handoffTo: handoffTo ?? undefined,
+            });
+            if (finalResult || finishReason !== 'tool-calls' || handoffTo) {
+                break;
+            }
+        }
+        catch (error) {
+            console.error('RUNTIME_LOOP_ERROR:', error);
+            if (abortSignal?.aborted) {
+                if (!interruptionEmitted) {
+                    setInterruptionEmitted(true);
+                    yield* services.streamEmitter.emit(context, {
+                        type: 'interrupted',
+                        sessionId: context.session.id,
+                        reason: abortSignal.reason ?? 'Operation cancelled',
+                        timestamp: new Date(),
+                        lastAgentId: context.agentId,
+                        lastStep: context.stepCount,
+                    });
+                }
+                return 'return';
+            }
+            context.consecutiveErrors += 1;
+            await services.hookRunner.onError(context, error);
+            yield* services.streamEmitter.emit(context, { type: 'error', error: error.message });
+            if (context.consecutiveErrors >= 3) {
+                return 'return';
+            }
+        }
+    }
+    return 'break';
+}
+async function* processStreamChunk(chunk, context, agent, services, toolCalls, turnToolErrors, finalResult, finalEmitted, bufferOutput, bufferedParts) {
+    const result = {};
+    if (chunk.type === 'text-delta') {
+        if (finalResult)
+            return result;
+        if (turnToolErrors.length > 0)
+            return result;
+        if (bufferOutput) {
+            bufferedParts.push(chunk.text);
+        }
+        else {
+            yield* services.streamEmitter.emit(context, { type: 'text-delta', text: chunk.text });
+        }
+    }
+    if (chunk.type === 'tool-call') {
+        const args = getChunkArgs(chunk);
+        const idempotencyKey = services.toolExecutor.buildIdempotencyKey({
+            sessionId: context.session.id,
+            agentId: context.agentId,
+            step: context.stepCount,
+            toolName: chunk.toolName,
+            toolCallId: chunk.toolCallId,
+        });
+        const callRecord = {
+            toolCallId: chunk.toolCallId,
+            toolName: chunk.toolName,
+            args,
+            idempotencyKey,
+            success: true,
+            timestamp: Date.now(),
+        };
+        toolCalls.push(callRecord);
+        await services.hookRunner.onToolCall(context, callRecord);
+        const toolConfig = services.agents.get(context.agentId)?.tools;
+        const toolDef = toolConfig?.[chunk.toolName];
+        const filler = toolDef?.filler ?? `Let me check ${chunk.toolName}...`;
+        yield* services.streamEmitter.emit(context, {
+            type: 'tool-start',
+            toolCallId: chunk.toolCallId,
+            toolName: chunk.toolName,
+            message: filler,
+        });
+        yield* services.streamEmitter.emit(context, {
+            type: 'tool-call',
+            toolCallId: chunk.toolCallId,
+            toolName: chunk.toolName,
+            args,
+        });
+    }
+    if (chunk.type === 'tool-error') {
+        const errText = getChunkErrorMessage(chunk);
+        const args = getChunkArgs(chunk);
+        const toolCallId = getChunkToolCallId(chunk);
+        const callRecord = toolCalls.find(call => call.toolCallId === toolCallId);
+        if (callRecord) {
+            callRecord.success = false;
+            callRecord.error = new Error(errText);
+            if (args !== undefined)
+                callRecord.args = args;
+            context.toolCallHistory.push(callRecord);
+            await services.hookRunner.onToolError(context, callRecord, callRecord.error);
+            const toolPolicy = agent.toolPolicies?.[callRecord.toolName];
+            const toolDef = agent.tools?.[callRecord.toolName];
+            const isCritical = toolPolicy?.critical ?? toolDef?.critical ?? true;
+            if (isCritical) {
+                turnToolErrors.push(callRecord);
+            }
+        }
+        yield* services.streamEmitter.emit(context, {
+            type: 'tool-error',
+            toolCallId: toolCallId ?? chunk.toolCallId,
+            toolName: chunk.toolName,
+            error: errText,
+        });
+    }
+    if (chunk.type === 'tool-result') {
+        const startTime = toolCalls.find(call => call.toolCallId === chunk.toolCallId)?.timestamp ?? Date.now();
+        const toolResult = getChunkResult(chunk);
+        const callRecord = toolCalls.find(call => call.toolCallId === chunk.toolCallId);
+        if (callRecord) {
+            callRecord.result = toolResult;
+            callRecord.durationMs = Date.now() - callRecord.timestamp;
+            context.toolCallHistory.push(callRecord);
+            await services.hookRunner.onToolResult(context, callRecord);
+        }
+        const durationMs = Date.now() - startTime;
+        yield* services.streamEmitter.emit(context, {
+            type: 'tool-done',
+            toolCallId: chunk.toolCallId,
+            toolName: chunk.toolName,
+            durationMs,
+        });
+        if (callRecord) {
+            const enforcement = await services.enforcer.checkResult(callRecord, {
+                previousCalls: context.toolCallHistory,
+                currentStep: context.stepCount,
+                sessionState: context.session.state ?? {},
+            });
+            if (!enforcement.allowed) {
+                const reason = enforcement.reason ?? 'Tool result blocked by enforcement';
+                callRecord.success = false;
+                callRecord.error = new Error(reason);
+                await services.hookRunner.onToolError(context, callRecord, callRecord.error);
+                turnToolErrors.push(callRecord);
+                yield* services.streamEmitter.emit(context, {
+                    type: 'tool-error',
+                    toolCallId: chunk.toolCallId,
+                    toolName: chunk.toolName,
+                    error: reason,
+                });
+                result.finalResult = { type: 'final', text: reason };
+                if (!finalEmitted) {
+                    result.finalEmitted = true;
+                    if (bufferOutput) {
+                        bufferedParts.push(reason);
+                    }
+                    else {
+                        yield* services.streamEmitter.emit(context, { type: 'text-delta', text: reason });
+                    }
+                }
+                return result;
+            }
+        }
+        yield* services.streamEmitter.emit(context, {
+            type: 'tool-result',
+            toolCallId: chunk.toolCallId,
+            toolName: chunk.toolName,
+            result: toolResult,
+        });
+        const stopCheck = checkStopConditions(context, services.stopConditions);
+        if (stopCheck.shouldStop) {
+            yield* services.streamEmitter.emit(context, { type: 'error', error: `Stopped: ${stopCheck.reason}` });
+            result.stoppedByGuard = true;
+            return result;
+        }
+        if (isFinalResult(toolResult)) {
+            result.finalResult = toolResult;
+            if (!finalEmitted) {
+                result.finalEmitted = true;
+                if (bufferOutput) {
+                    bufferedParts.push(toolResult.text);
+                }
+                else {
+                    yield* services.streamEmitter.emit(context, { type: 'text-delta', text: toolResult.text });
+                }
+            }
+            return result;
+        }
+        if (isHandoffResult(toolResult)) {
+            const targetAgent = toolResult.targetAgent ?? toolResult.targetAgentId;
+            result.handoffTo = targetAgent;
+            result.handoffReason = toolResult.reason ?? 'No reason provided';
+        }
+    }
+    return result;
+}
+// --- Structured triage ---
+async function* runStructuredTriage(agent, context, system, abortSignal, services, activeRoutes) {
+    const allowed = new Set((activeRoutes ?? agent.routes).map(route => route.agentId));
+    // Single-candidate short-circuit
+    if (allowed.size === 1) {
+        const [onlyAgent] = allowed;
+        return { handoffTo: onlyAgent, handoffReason: 'Single active route — direct handoff' };
+    }
+    const model = agent.model ?? services.defaultModel;
+    const schema = z.object({
+        agentId: z.string().describe('Target agent ID for this request.'),
+        reason: z.string().describe('Short, concrete reason grounded in the user request.'),
+        confidence: z.number().min(0).max(1).describe('Routing confidence from 0 to 1.'),
+        stayWithCurrent: z.boolean().describe('True only if the current agent is best fit.'),
+    });
+    const result = streamObject({
+        model: model,
+        schema,
+        system: buildStructuredTriagePrompt(agent, activeRoutes),
+        messages: context.session.messages,
+        abortSignal,
+        experimental_telemetry: agent.telemetry ?? services.config.telemetry,
+    });
+    let handoffTo;
+    let handoffReason = 'Routed by triage';
+    let resolved = false;
+    for await (const partial of result.partialObjectStream) {
+        if (partial.agentId && allowed.has(partial.agentId)) {
+            handoffTo = partial.agentId;
+            handoffReason = partial.reason ?? 'Routed by triage';
+            resolved = true;
+            break;
+        }
+    }
+    if (!resolved) {
+        const fullObject = await result.object;
+        let target = fullObject.agentId;
+        if (!allowed.has(target)) {
+            const fallback = agent.defaultAgent ?? agent.routes[0]?.agentId;
+            if (fallback && fallback !== agent.id) {
+                target = fallback;
+            }
+            else {
+                // No valid target -- respond directly from triage
+                handoffTo = agent.id;
+                handoffReason = 'No valid routing target. Responding directly.';
+                return { handoffTo: handoffTo, handoffReason };
+            }
+        }
+        handoffTo = target;
+        handoffReason = fullObject.reason ?? 'Routed by triage';
+    }
+    return { handoffTo: handoffTo, handoffReason };
+}
+// --- Tool enforcement wrapper ---
+function wrapToolsWithEnforcement(context, tools, services) {
+    const wrapped = {};
+    for (const [toolName, toolDef] of Object.entries(tools ?? {})) {
+        if (!('execute' in toolDef) || typeof toolDef.execute !== 'function') {
+            wrapped[toolName] = toolDef;
+            continue;
+        }
+        const exec = toolDef.execute;
+        wrapped[toolName] = {
+            ...toolDef,
+            execute: async (args, options) => {
+                const toolCallId = typeof options?.toolCallId === 'string'
+                    ? options.toolCallId
+                    : crypto.randomUUID();
+                const idempotencyKey = services.toolExecutor.buildIdempotencyKey({
+                    sessionId: context.session.id,
+                    agentId: context.agentId,
+                    step: context.stepCount,
+                    toolName,
+                    toolCallId,
+                });
+                const callRecord = {
+                    toolCallId,
+                    toolName,
+                    args,
+                    idempotencyKey,
+                    success: true,
+                    timestamp: Date.now(),
+                };
+                const enforcement = await services.enforcer.check(callRecord, {
+                    previousCalls: context.toolCallHistory,
+                    currentStep: context.stepCount,
+                    sessionState: context.session.state ?? {},
+                });
+                if (!enforcement.allowed) {
+                    const reason = enforcement.reason ?? 'Tool call blocked by enforcement';
+                    callRecord.success = false;
+                    callRecord.error = new Error(reason);
+                    context.toolCallHistory.push(callRecord);
+                    await services.hookRunner.onToolError(context, callRecord, callRecord.error);
+                    throw callRecord.error;
+                }
+                const enrichedOptions = withToolExecutionMetadata(options, context, toolName, toolCallId, idempotencyKey, services);
+                try {
+                    return await exec(args, enrichedOptions);
+                }
+                catch (error) {
+                    console.error(`[Runtime] Tool execution failed for ${toolName}:`, error);
+                    throw error;
+                }
+            },
+        };
+    }
+    return wrapped;
+}
+function withToolExecutionMetadata(options, context, toolName, toolCallId, idempotencyKey, services) {
+    const baseOptions = options ?? {};
+    const existingContext = isRecord(baseOptions.experimental_context)
+        ? baseOptions.experimental_context
+        : {};
+    return {
+        ...baseOptions,
+        toolCallId,
+        experimental_context: {
+            ...existingContext,
+            session: context.session,
+            sessionId: context.session.id,
+            agentId: context.agentId,
+            step: context.stepCount,
+            turn: services.conversationState.getSessionTurn(context.session),
+            toolName,
+            toolCallId,
+            idempotencyKey,
+            memoryService: services.memoryService,
+        },
+    };
+}
+// --- Handoff candidates ---
+function getHandoffCandidates(agent, services, activeRoutes) {
+    if (isTriageAgent(agent)) {
+        const routes = activeRoutes ?? agent.routes;
+        return routes
+            .map(route => services.agents.get(route.agentId))
+            .filter((candidate) => Boolean(candidate));
+    }
+    const targets = agent.canHandoffTo;
+    if (!targets || targets.length === 0)
+        return [];
+    return targets
+        .map(id => services.agents.get(id))
+        .filter((candidate) => Boolean(candidate));
+}
+// --- Circular handoff fallback ---
+function getCircularHandoffFallbackMessage(services) {
+    const configured = services.config.circularHandoffFallbackMessage?.trim();
+    if (configured)
+        return configured;
+    return 'I hit a routing issue between agents. I will continue here. Tell me the exact outcome you need in one sentence.';
+}
+async function* emitCircularHandoffFallback(context, services) {
+    const fallback = getCircularHandoffFallbackMessage(services);
+    appendSessionMessage(context.session, { role: 'assistant', content: fallback }, services.conversationState);
+    yield* services.streamEmitter.emit(context, { type: 'text-delta', text: fallback });
+}
+// --- onBeforeModelCall hook ---
+async function runBeforeModelCallHook(agent, context, system, services) {
+    try {
+        const messageTokens = context.session.messages.reduce((sum, m) => {
+            const txt = typeof m.content === 'string'
+                ? m.content
+                : Array.isArray(m.content)
+                    ? m.content
+                        .filter((p) => p.type === 'text')
+                        .map((p) => p.text)
+                        .join('')
+                    : '';
+            return sum + estimateTokenCount(txt);
+        }, 0);
+        const systemTokens = estimateTokenCount(system);
+        const budgetData = (context.session.workingMemory['__ariaContextBudget'] ?? {});
+        const allocations = (budgetData.allocations ?? {});
+        const hookData = {
+            systemPrompt: system,
+            messages: context.session.messages,
+            estimatedTokens: systemTokens + messageTokens,
+            agentId: agent.id,
+            tokenBreakdown: {
+                basePrompt: allocations.basePrompt ?? 0,
+                autoRetrieve: allocations.autoRetrieve ?? 0,
+                workingMemory: allocations.workingMemory ?? 0,
+                extraction: 0,
+                longTermMemory: allocations.longTermMemory ?? 0,
+                policyInjections: allocations.policyInjections ?? 0,
+                messageHistory: messageTokens,
+            },
+        };
+        const hookResult = await services.config.hooks.onBeforeModelCall(context, hookData);
+        if (hookResult?.systemPrompt !== undefined) {
+            system = hookResult.systemPrompt;
+        }
+        if (hookResult?.messages !== undefined) {
+            context.session.messages = hookResult.messages;
+        }
+    }
+    catch (err) {
+        console.warn('[AriaFlow] onBeforeModelCall hook failed, using originals:', err);
+    }
+    return system;
+}
+// --- FlowExecutorHelpers builder ---
+function matchesDetourRule(input, patterns) {
+    if (!patterns || patterns.length === 0)
+        return false;
+    for (const pattern of patterns) {
+        try {
+            const regex = new RegExp(pattern, 'i');
+            if (regex.test(input))
+                return true;
+        }
+        catch {
+            if (input.includes(pattern.toLowerCase()))
+                return true;
+        }
+    }
+    return false;
+}
+function buildFlowExecutorHelpers(services) {
+    return {
+        emit: (ctx, part) => services.streamEmitter.emit(ctx, part),
+        runOutputProcessing: (agent, ctx, text) => runOutputProcessing(agent, ctx, text, services.outputProcessors, services.outputRedactions),
+        appendSessionMessage: (s, m) => appendSessionMessage(s, m, services.conversationState),
+        appendSessionMessages: (s, ms) => appendSessionMessages(s, ms, services.conversationState),
+        postProcessPersistedAssistantMessages: (agent, ctx, start) => postProcessPersistedAssistantMessages(agent, ctx, start, services.outputProcessors, services.outputRedactions),
+        getAgentOutputProcessors: (agent) => getAgentOutputProcessors(agent, services.outputProcessors),
+        getSessionTurn: (s) => services.conversationState.getSessionTurn(s),
+        buildToolIdempotencyKey: (ctx, tn, tcid) => services.toolExecutor.buildIdempotencyKey({
+            sessionId: ctx.session.id,
+            agentId: ctx.agentId,
+            step: ctx.stepCount,
+            toolName: tn,
+            toolCallId: tcid,
+        }),
+        setFlowState: (s, id, st) => setFlowState(s, id, st, services.conversationState),
+        getFlowState: (s, id) => getFlowState(s, id),
+        updateFlowStateSnapshot: (s, id, st) => updateFlowStateSnapshot(s, id, st),
+        clearFlowState: (s, id) => clearFlowState(s, id, services.conversationState),
+        buildFlowWithHandoff: (a, ht, suppress) => buildFlowWithHandoff(a, ht, suppress),
+        getFlowNode: (a, nid) => a.flow.nodes.find(node => node.id === nid),
+        touchSession: (s) => services.conversationState.touchSession(s),
+        matchesDetourRule: (i, p) => matchesDetourRule(i, p),
+        enforcecheck: (call, ctx) => services.enforcer.check(call, {
+            previousCalls: ctx.toolCallHistory,
+            currentStep: ctx.stepCount,
+            sessionState: ctx.session.state ?? {},
+        }),
+        enforcecheckResult: (call, ctx) => services.enforcer.checkResult(call, {
+            previousCalls: ctx.toolCallHistory,
+            currentStep: ctx.stepCount,
+            sessionState: ctx.session.state ?? {},
+        }),
+        onToolCallHook: (ctx, call) => services.hookRunner.onToolCall(ctx, call),
+        onToolResultHook: (ctx, call) => services.hookRunner.onToolResult(ctx, call),
+        onToolErrorHook: (ctx, call, error) => services.hookRunner.onToolError(ctx, call, error),
+    };
+}
+// --- buildFlowWithHandoff (moved from Runtime) ---
+function buildFlowWithHandoff(agent, handoffTool, suppressAutoRespond) {
+    const needsInitialSuppression = suppressAutoRespond &&
+        agent.flow.nodes.some(n => n.id === agent.initialNode && n.autoRespond === undefined);
+    if (!handoffTool && !needsInitialSuppression)
+        return agent.flow;
+    return {
+        ...agent.flow,
+        nodes: agent.flow.nodes.map(node => {
+            const shouldSuppress = suppressAutoRespond
+                && node.id === agent.initialNode
+                && node.autoRespond === undefined;
+            const existingTools = node.tools;
+            if (typeof existingTools === 'function') {
+                return {
+                    ...node,
+                    tools: (ctx) => {
+                        const resolved = existingTools(ctx) ?? {};
+                        if (!handoffTool)
+                            return resolved;
+                        return resolved.handoff ? resolved : { ...resolved, handoff: handoffTool };
+                    },
+                    ...(shouldSuppress ? { autoRespond: false } : {}),
+                };
+            }
+            const toolSet = existingTools ?? {};
+            if (!handoffTool || toolSet.handoff) {
+                return shouldSuppress ? { ...node, autoRespond: false } : node;
+            }
+            return {
+                ...node,
+                tools: { ...toolSet, handoff: handoffTool },
+                ...(shouldSuppress ? { autoRespond: false } : {}),
+            };
+        }),
+    };
+}
+//# sourceMappingURL=AgentExecuteStage.js.map