@ariaflowagents/core 0.5.1 → 0.5.3

package/dist/runtime/Runtime.js

@@ -1,4 +1,4 @@
-import { streamText, generateText, generateObject } from 'ai';
+import { streamText, generateText, Output, stepCountIs } from 'ai';
 import { z } from 'zod';
 import { FlowManager } from '../flows/FlowManager.js';
 import { createHandoffTool, isHandoffResult } from '../tools/handoff.js';
@@ -10,6 +10,8 @@ import { ToolEnforcer } from '../guards/ToolEnforcer.js';
 import { defaultEnforcementRules } from '../guards/rules.js';
 import { MemoryStore } from '../session/stores/MemoryStore.js';
 import { createHttpCallback } from '../callbacks/httpCallback.js';
+import { compileSanitizePattern, renderFlowTemplate } from '../flows/template.js';
+import { runInputProcessors, runOutputProcessors } from '../processors/ProcessorRunner.js';
 export class Runtime {
     config;
     agents = new Map();
@@ -18,7 +20,7 @@ export class Runtime {
     maxSteps;
     maxHandoffs;
     stopConditions;
-    sessionStore;
+    _sessionStore;
     hookRunner;
     enforcer;
     contextManager;
@@ -26,6 +28,50 @@ export class Runtime {
     abortControllers = new Map();
     alwaysRouteThroughTriage;
     triageAgentId;
+    inputProcessors;
+    outputProcessors;
+    outputProcessorMode;
+    outputRedactions;
+    redactCarryBySession = new Map();
+    redactLookbehind = 64;
+    wrapToolsWithEnforcement(context, tools) {
+        const wrapped = {};
+        for (const [toolName, toolDef] of Object.entries(tools ?? {})) {
+            const exec = toolDef?.execute;
+            if (typeof exec !== 'function') {
+                wrapped[toolName] = toolDef;
+                continue;
+            }
+            wrapped[toolName] = {
+                ...toolDef,
+                execute: async (args, options) => {
+                    const callRecord = {
+                        toolCallId: options?.toolCallId ?? crypto.randomUUID(),
+                        toolName,
+                        args,
+                        success: true,
+                        timestamp: Date.now(),
+                    };
+                    const enforcement = await this.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 this.hookRunner.onToolError(context, callRecord, callRecord.error);
+                        throw callRecord.error;
+                    }
+                    // Preserve AI SDK tool execution context (toolCallId, messages, experimental_context, etc.).
+                    return exec(args, options);
+                },
+            };
+        }
+        return wrapped;
+    }
     constructor(config) {
         this.config = config;
         for (const agent of config.agents) {
@@ -36,7 +82,7 @@ export class Runtime {
         this.maxSteps = config.maxSteps ?? 20;
         this.maxHandoffs = config.maxHandoffs ?? 10;
         this.stopConditions = config.stopConditions ?? defaultStopConditions;
-        this.sessionStore = config.sessionStore ?? new MemoryStore();
+        this._sessionStore = config.sessionStore ?? new MemoryStore();
         const hooks = { ...config.hooks };
         if (config.callback) {
             console.log('[Runtime] HTTP callback configured for:', config.callback.url);
@@ -58,6 +104,20 @@ export class Runtime {
         this.contextManager = config.contextManager;
         this.alwaysRouteThroughTriage = config.alwaysRouteThroughTriage ?? false;
         this.triageAgentId = config.triageAgentId;
+        this.inputProcessors = config.inputProcessors ?? [];
+        this.outputProcessors = config.outputProcessors ?? [];
+        this.outputProcessorMode = config.outputProcessorMode ?? 'stream';
+        if (config.outputRedaction && config.outputRedaction.length > 0) {
+            this.outputRedactions = config.outputRedaction.map(r => {
+                const base = compileSanitizePattern(r.pattern);
+                const flags = base.flags.includes('g') ? base.flags : `${base.flags}g`;
+                const re = new RegExp(base.source, flags);
+                return { re, replacement: r.replacement };
+            });
+        }
+    }
+    get sessionStore() {
+        return this._sessionStore;
     }
     getActiveAbortController(sessionId) {
         return this.abortControllers.get(sessionId);
@@ -74,49 +134,34 @@ export class Runtime {
         let session;
         const effectiveSessionId = sessionId ?? crypto.randomUUID();
         if (sessionId) {
-            const existing = await this.sessionStore.get(sessionId);
+            const existing = await this._sessionStore.get(sessionId);
             session = existing ?? this.createSession(effectiveSessionId, userId);
         }
         else {
             session = this.createSession(effectiveSessionId, userId);
         }
-        session.messages.push({ role: 'user', content: input });
-        if (this.contextManager) {
-            const messagesBefore = session.messages.length;
-            const totalTokens = session.messages.reduce((sum, m) => {
-                const text = typeof m.content === 'string' ? m.content : '';
-                return sum + Math.ceil(text.length / 4);
-            }, 0);
-            session.messages = this.contextManager.beforeTurn(session.messages, {
-                turnCount: this.turnCount,
-                totalTokens,
-                sessionId: session.id,
-            });
-            const messagesAfter = session.messages.length;
-            if (messagesBefore !== messagesAfter) {
-                // NOTE: This is the only yield that bypasses emit() because RunContext
-                // doesn't exist yet at this point. The onStreamPart hook will NOT fire
-                // for context-compacted events. This is intentional - context compaction
-                // occurs before the agent loop begins.
-                yield {
-                    type: 'context-compacted',
-                    messagesBefore,
-                    messagesAfter,
-                };
-            }
-        }
-        this.turnCount++;
         if (this.alwaysRouteThroughTriage) {
-            const triageId = this.triageAgentId ?? this.defaultAgentId;
-            const triageAgent = this.agents.get(triageId);
-            if (triageAgent && this.isTriageAgent(triageAgent)) {
-                session.activeAgentId = triageId;
-                session.currentAgent = triageId;
+            // If a flow agent is currently active and has an initialized, non-ended flow state,
+            // keep routing to it so multi-turn flows can complete without triage interference.
+            const currentAgentId = session.activeAgentId ?? session.currentAgent;
+            const currentAgent = currentAgentId ? this.agents.get(currentAgentId) : undefined;
+            const hasActiveFlow = Boolean(currentAgent) &&
+                this.isFlowAgent(currentAgent) &&
+                Boolean(this.getFlowState(session, currentAgent.id)?.initialized) &&
+                !Boolean(this.getFlowState(session, currentAgent.id)?.flowEnded);
+            if (!hasActiveFlow) {
+                const triageId = this.triageAgentId ?? this.defaultAgentId;
+                const triageAgent = this.agents.get(triageId);
+                if (triageAgent && this.isTriageAgent(triageAgent)) {
+                    session.activeAgentId = triageId;
+                    session.currentAgent = triageId;
+                }
             }
         }
         const activeAgentId = session.activeAgentId ?? session.currentAgent ?? this.defaultAgentId;
         session.activeAgentId = activeAgentId;
         session.currentAgent = activeAgentId;
+        this.turnCount++;
         const context = {
             session,
             agentId: activeAgentId,
@@ -129,10 +174,12 @@ export class Runtime {
         };
         const injectionQueue = new InjectionQueue();
         injectionQueue.add(commonInjections.professional);
-        // Yield initial input through emit so hooks see it
-        yield* this.emit(context, { type: 'input', text: input, userId: session.userId || undefined });
         injectionQueue.add(commonInjections.noGuessing);
+        injectionQueue.add(commonInjections.noSecrets);
+        injectionQueue.add(commonInjections.invisibleHandoffs);
         injectionQueue.add(commonInjections.confirmDestructive);
+        // Yield input through emit so hooks see it (once).
+        yield* this.emit(context, { type: 'input', text: input, userId: session.userId || undefined });
         const controller = new AbortController();
         this.abortControllers.set(session.id, controller);
         const abortHandler = () => {
@@ -146,9 +193,64 @@ export class Runtime {
             abortSignal.addEventListener('abort', externalAbortHandler);
         }
         await this.hookRunner.onStart(context);
-        yield* this.emit(context, { type: 'input', text: input, userId: session.userId });
+        // Run input processors BEFORE persisting the user message.
+        let processedInput = input;
         try {
-            yield* this.runLoop(context, injectionQueue, input, controller);
+            const turnInputProcessors = [...this.inputProcessors];
+            if (turnInputProcessors.length > 0) {
+                const candidateMessages = [
+                    ...session.messages,
+                    { role: 'user', content: processedInput },
+                ];
+                const procCtx = {
+                    session,
+                    agentId: activeAgentId,
+                    toolCallHistory: context.toolCallHistory,
+                };
+                const outcome = await runInputProcessors({
+                    processors: turnInputProcessors,
+                    input: processedInput,
+                    messages: candidateMessages,
+                    context: procCtx,
+                });
+                if (outcome.blocked) {
+                    yield* this.emit(context, {
+                        type: 'tripwire',
+                        phase: 'input',
+                        processorId: outcome.processorId,
+                        reason: outcome.reason,
+                        message: outcome.message,
+                    });
+                    yield* this.emit(context, { type: 'text-delta', text: outcome.message });
+                    yield* this.emit(context, { type: 'turn-end' });
+                    await this.hookRunner.onEnd(context, { success: true });
+                    return;
+                }
+                processedInput = outcome.input;
+            }
+            // Persist the (possibly modified) user message after input processors.
+            session.messages.push({ role: 'user', content: processedInput });
+            if (this.contextManager) {
+                const messagesBefore = session.messages.length;
+                const totalTokens = session.messages.reduce((sum, m) => {
+                    const text = typeof m.content === 'string' ? m.content : '';
+                    return sum + Math.ceil(text.length / 4);
+                }, 0);
+                session.messages = this.contextManager.beforeTurn(session.messages, {
+                    turnCount: this.turnCount,
+                    totalTokens,
+                    sessionId: session.id,
+                });
+                const messagesAfter = session.messages.length;
+                if (messagesBefore !== messagesAfter) {
+                    yield* this.emit(context, {
+                        type: 'context-compacted',
+                        messagesBefore,
+                        messagesAfter,
+                    });
+                }
+            }
+            yield* this.runLoop(context, injectionQueue, processedInput, controller);
             await this.hookRunner.onEnd(context, { success: true });
         }
         catch (error) {
@@ -159,7 +261,7 @@ export class Runtime {
         finally {
             controller.signal.removeEventListener('abort', abortHandler);
             this.abortControllers.delete(session.id);
-            await this.sessionStore.save(session);
+            await this._sessionStore.save(session);
             yield* this.emit(context, { type: 'done', sessionId: session.id });
         }
     }
@@ -167,6 +269,7 @@ export class Runtime {
         yield* this.stream({ input, sessionId, userId });
     }
     async *runLoop(context, injectionQueue, input, abortController) {
+        let currentInput = input;
         while (context.handoffStack.length < this.maxHandoffs) {
             if (abortController?.signal.aborted) {
                 yield* this.emit(context, {
@@ -179,11 +282,16 @@ export class Runtime {
                 });
                 return;
             }
-            if (context.handoffStack.includes(context.agentId)) {
-                yield* this.emit(context, {
-                    type: 'error',
-                    error: `Circular handoff detected: ${context.handoffStack.join(' -> ')} -> ${context.agentId}`,
-                });
+            // Allow a single "bounce back" (A -> B -> A) for detours and multi-intent turns.
+            // Stop only when an agent would be visited a third time in the same user turn.
+            const priorVisits = context.handoffStack.filter(id => id === context.agentId).length;
+            if (priorVisits >= 2) {
+                const err = `Circular handoff detected: ${context.handoffStack.join(' -> ')} -> ${context.agentId}`;
+                yield* this.emit(context, { type: 'error', error: err });
+                const fallback = "I ran into an internal routing issue. Please rephrase your request in one sentence. " +
+                    "For security, don't share passwords, API keys, or card numbers/CVV here.";
+                context.session.messages.push({ role: 'assistant', content: fallback });
+                yield* this.emit(context, { type: 'text-delta', text: fallback });
                 return;
             }
             context.handoffStack.push(context.agentId);
@@ -192,6 +300,40 @@ export class Runtime {
                 yield* this.emit(context, { type: 'error', error: `Agent "${context.agentId}" not found` });
                 return;
             }
+            // Agent-specific input processors. These run after the user message is in history and
+            // before the agent gets a chance to call the model/tools.
+            if (agent.inputProcessors && agent.inputProcessors.length > 0) {
+                const procCtx = {
+                    session: context.session,
+                    agentId: agent.id,
+                    toolCallHistory: context.toolCallHistory,
+                };
+                const outcome = await runInputProcessors({
+                    processors: agent.inputProcessors,
+                    input: currentInput,
+                    messages: context.session.messages,
+                    context: procCtx,
+                });
+                if (outcome.blocked) {
+                    yield* this.emit(context, {
+                        type: 'tripwire',
+                        phase: 'input',
+                        processorId: outcome.processorId,
+                        reason: outcome.reason,
+                        message: outcome.message,
+                    });
+                    yield* this.emit(context, { type: 'text-delta', text: outcome.message });
+                    yield* this.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;
+                    }
+                }
+            }
             yield* this.emit(context, { type: 'agent-start', agentId: agent.id });
             await this.hookRunner.onAgentStart(context, agent.id);
             let autoContext;
@@ -201,7 +343,7 @@ export class Runtime {
                 const callRecord = {
                     toolCallId,
                     toolName,
-                    args: { input },
+                    args: { input: currentInput },
                     success: true,
                     timestamp: Date.now(),
                 };
@@ -220,7 +362,7 @@ export class Runtime {
                 });
                 let result = null;
                 try {
-                    result = await agent.autoRetrieve.run({ input, context });
+                    result = await agent.autoRetrieve.run({ input: currentInput, context });
                     callRecord.result = result;
                 }
                 catch (error) {
@@ -261,7 +403,9 @@ export class Runtime {
             }
             const system = this.buildSystemPrompt(agent, injectionQueue, autoContext, context);
             const handoffCandidates = this.getHandoffCandidates(agent);
-            const handoffTool = createHandoffTool(handoffCandidates, context.agentId);
+            const handoffTool = handoffCandidates.length > 0
+                ? createHandoffTool(handoffCandidates, context.agentId)
+                : null;
             let handoffTo = null;
             let handoffReason = 'No reason provided';
             if (this.isFlowAgent(agent)) {
@@ -280,7 +424,7 @@ export class Runtime {
                 await this.hookRunner.onStepStart(context, context.stepCount);
                 const toolCalls = [];
                 try {
-                    for await (const part of this.runFlowAgent(agent, context, input, system, handoffTool, (target, reason) => {
+                    for await (const part of this.runFlowAgent(agent, context, currentInput, system, handoffTool ?? undefined, (target, reason) => {
                         handoffTo = target;
                         handoffReason = reason ?? 'No reason provided';
                     }, toolCalls)) {
@@ -308,7 +452,7 @@ export class Runtime {
                 }
             }
             else {
-                const tools = { ...agent.tools, handoff: handoffTool };
+                const tools = this.wrapToolsWithEnforcement(context, handoffTool ? { ...agent.tools, handoff: handoffTool } : { ...agent.tools });
                 let agentSteps = 0;
                 const agentMaxSteps = agent.maxSteps ?? agent.maxTurns ?? this.maxSteps;
                 while (agentSteps < agentMaxSteps) {
@@ -333,14 +477,14 @@ export class Runtime {
                                 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 = await generateObject({
+                            // AI SDK v6+ recommended structured output approach.
+                            const { output: decision } = await generateText({
                                 model: model,
-                                schema,
+                                output: Output.object({ schema }),
                                 system: this.buildStructuredTriagePrompt(agent),
                                 messages: context.session.messages,
                                 experimental_telemetry: agent.telemetry ?? this.config.telemetry,
                             });
-                            const decision = result.object;
                             const allowed = new Set(agent.routes.map(route => route.agentId));
                             let target = decision.agentId;
                             if (!allowed.has(target)) {
@@ -362,17 +506,34 @@ export class Runtime {
                             system,
                             messages: context.session.messages,
                             tools,
+                            // Let the AI SDK handle tool-calling steps internally.
+                            // Default is stepCountIs(1), which ends right after tool-calls.
+                            stopWhen: stepCountIs(agent.toolMaxSteps ?? 5),
+                            // Tool execution can read this via options.experimental_context.
+                            experimental_context: {
+                                session: context.session,
+                                agentId: agent.id,
+                            },
                             experimental_telemetry: agent.telemetry ?? this.config.telemetry,
                         });
                         const toolCalls = [];
                         let finalResult = null;
                         let finalEmitted = false;
+                        const outputProcessors = this.getAgentOutputProcessors(agent);
+                        const bufferOutput = this.outputProcessorMode === 'buffer' && outputProcessors.length > 0;
+                        let bufferedText = '';
+                        let stoppedByGuard = false;
                         for await (const chunk of result.fullStream) {
                             if (chunk.type === 'text-delta') {
                                 if (finalResult) {
                                     continue;
                                 }
-                                yield* this.emit(context, { type: 'text-delta', text: chunk.text });
+                                if (bufferOutput) {
+                                    bufferedText += chunk.text;
+                                }
+                                else {
+                                    yield* this.emit(context, { type: 'text-delta', text: chunk.text });
+                                }
                             }
                             if (chunk.type === 'tool-call') {
                                 const args = 'args' in chunk ? chunk.args : chunk.input;
@@ -402,6 +563,27 @@ export class Runtime {
                                     args,
                                 });
                             }
+                            if (chunk.type === 'tool-error') {
+                                const errText = typeof chunk.error === 'string'
+                                    ? chunk.error
+                                    : chunk.error?.message ?? 'Tool execution error';
+                                const args = chunk.input ?? chunk.args;
+                                const callRecord = toolCalls.find(call => call.toolCallId === chunk.toolCallId);
+                                if (callRecord) {
+                                    callRecord.success = false;
+                                    callRecord.error = new Error(errText);
+                                    if (args !== undefined)
+                                        callRecord.args = args;
+                                    context.toolCallHistory.push(callRecord);
+                                    await this.hookRunner.onToolError(context, callRecord, callRecord.error);
+                                }
+                                yield* this.emit(context, {
+                                    type: 'tool-error',
+                                    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 = 'result' in chunk ? chunk.result : chunk.output;
@@ -440,7 +622,12 @@ export class Runtime {
                                         finalResult = { type: 'final', text: reason };
                                         if (!finalEmitted) {
                                             finalEmitted = true;
-                                            yield* this.emit(context, { type: 'text-delta', text: reason });
+                                            if (bufferOutput) {
+                                                bufferedText += reason;
+                                            }
+                                            else {
+                                                yield* this.emit(context, { type: 'text-delta', text: reason });
+                                            }
                                         }
                                         continue;
                                     }
@@ -451,11 +638,23 @@ export class Runtime {
                                     toolName: chunk.toolName,
                                     result: toolResult,
                                 });
+                                // Stop as soon as a stop condition triggers, even mid-stream.
+                                const stopResult = checkStopConditions(context, this.stopConditions);
+                                if (stopResult.shouldStop) {
+                                    yield* this.emit(context, { type: 'error', error: `Stopped: ${stopResult.reason}` });
+                                    stoppedByGuard = true;
+                                    break;
+                                }
                                 if (isFinalResult(toolResult)) {
                                     finalResult = toolResult;
                                     if (!finalEmitted) {
                                         finalEmitted = true;
-                                        yield* this.emit(context, { type: 'text-delta', text: toolResult.text });
+                                        if (bufferOutput) {
+                                            bufferedText += toolResult.text;
+                                        }
+                                        else {
+                                            yield* this.emit(context, { type: 'text-delta', text: toolResult.text });
+                                        }
                                     }
                                     continue;
                                 }
@@ -466,12 +665,45 @@ export class Runtime {
                                 }
                             }
                         }
+                        if (stoppedByGuard) {
+                            return;
+                        }
                         const response = await result.response;
-                        if (finalResult) {
-                            context.session.messages.push({ role: 'assistant', content: finalResult.text });
+                        const finishReason = finalResult ? 'final' : await result.finishReason;
+                        // Only finalize buffered output when the model has completed a non-tool finish.
+                        // If the model ended on tool-calls, we must persist the tool messages and
+                        // continue the loop (or let AI SDK continue in maxSteps) instead of emitting
+                        // synthetic assistant text, which can duplicate responses.
+                        if (finalResult || (bufferOutput && finishReason !== 'tool-calls')) {
+                            const rawText = finalResult ? finalResult.text : bufferedText;
+                            const processed = await this.runOutputProcessing(agent, context, rawText);
+                            if (processed.tripwire) {
+                                yield* this.emit(context, {
+                                    type: 'tripwire',
+                                    phase: 'output',
+                                    processorId: processed.tripwire.processorId,
+                                    reason: processed.tripwire.reason,
+                                    message: processed.tripwire.message,
+                                });
+                            }
+                            if (bufferOutput) {
+                                yield* this.emit(context, { type: 'text-delta', text: processed.text });
+                            }
+                            context.session.messages.push({ role: 'assistant', content: processed.text });
                         }
                         else {
+                            const beforeLen = context.session.messages.length;
                             context.session.messages.push(...response.messages);
+                            const tripwires = await this.postProcessPersistedAssistantMessages(agent, context, beforeLen);
+                            for (const t of tripwires) {
+                                yield* this.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;
@@ -481,7 +713,6 @@ export class Runtime {
                             context.session.metadata.totalSteps += 1;
                         }
                         context.consecutiveErrors = 0;
-                        const finishReason = finalResult ? 'final' : await result.finishReason;
                         yield* this.emit(context, { type: 'step-end', step: context.stepCount, agentId: agent.id });
                         await this.hookRunner.onStepEnd(context, context.stepCount, {
                             toolCalls,
@@ -623,7 +854,14 @@ ${routeDescriptions}
                 .map(route => this.agents.get(route.agentId))
                 .filter((candidate) => Boolean(candidate));
         }
-        return Array.from(this.agents.values());
+        // Production default: only triage routes by default. Other agents can handoff only if explicitly configured.
+        const targets = agent.canHandoffTo;
+        if (!targets || targets.length === 0) {
+            return [];
+        }
+        return targets
+            .map(id => this.agents.get(id))
+            .filter((candidate) => Boolean(candidate));
     }
     getFlowState(session, agentId) {
         const stored = session.agentStates?.[agentId]?.state;
@@ -643,20 +881,40 @@ ${routeDescriptions}
         delete session.agentStates[agentId];
     }
     buildFlowWithHandoff(agent, handoffTool, suppressAutoRespond) {
+        // If we don't need to inject a handoff tool and we don't need to suppress the initial autoRespond,
+        // we can return the flow as-is. Otherwise we must clone nodes to apply changes.
+        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 (existingTools.handoff) {
+                const existingTools = node.tools;
+                // Support tool factories (tools: (ctx) => ToolSet) as well as static ToolSets.
+                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: {
-                        ...existingTools,
+                        ...toolSet,
                         handoff: handoffTool,
                     },
                     ...(shouldSuppress ? { autoRespond: false } : {}),
@@ -671,6 +929,12 @@ ${routeDescriptions}
         return agent.flow.nodes.find(node => node.id === nodeId);
     }
     async shouldHandleFlowInput(agent, input, flowState) {
+        // Before the flow is initialized, be conservative: run the flow.
+        // This avoids misrouting the very first user message after a handoff into "detour",
+        // which can lead to unnecessary specialist handoffs and handoff loops.
+        if (!flowState?.initialized) {
+            return true;
+        }
         const nodeId = flowState?.context.currentNode ?? agent.initialNode;
         const node = this.getFlowNode(agent, nodeId);
         if (!node) {
@@ -695,11 +959,12 @@ ${routeDescriptions}
             }
         }
         const collectedData = flowState?.context.collectedData ?? {};
+        const renderedNodePrompt = renderFlowTemplate(node.prompt, collectedData, { missing: 'keep' });
         const routerPrompt = `You are routing a message for a structured conversation flow.
 Decide if the user input is answering the current flow step or is a side question.
 
 Current flow step:
-${node.prompt}
+${renderedNodePrompt}
 
 Collected data:
 ${JSON.stringify(collectedData, null, 2)}
@@ -742,10 +1007,15 @@ Return only one word: "flow" if the input should be handled by the flow step, or
     async *runDetourResponse(agent, context, input, flowState, handoffTool, onHandoff) {
         const nodeId = flowState?.context.currentNode ?? agent.initialNode;
         const node = this.getFlowNode(agent, nodeId);
-        const nodePrompt = node?.prompt ?? 'Continue the flow.';
         const collectedData = flowState?.context.collectedData ?? {};
+        const nodePrompt = node
+            ? renderFlowTemplate(node.prompt, collectedData, { missing: 'keep' })
+            : 'Continue the flow.';
+        const handoffLine = handoffTool
+            ? 'If the request should be handled by a specialist agent, use the handoff tool instead of answering.'
+            : 'Do not attempt to route to other agents. Handle the detour here and then resume the flow.';
         const detourPrompt = `You are handling a short detour during a structured flow.
-Answer the user's question clearly and briefly. If the request should be handled by a specialist agent, use the handoff tool instead of answering. Then ask the user to continue with the current flow step.
+Answer the user's question clearly and briefly. ${handoffLine} Then ask the user to continue with the current flow step.
 
 Current flow step:
 ${nodePrompt}
@@ -758,16 +1028,24 @@ Do not change the flow requirements. Keep the reply concise.`;
             model: (agent.model ?? this.defaultModel),
             system: detourPrompt,
             messages: context.session.messages,
-            tools: { handoff: handoffTool },
+            tools: handoffTool ? { handoff: handoffTool } : undefined,
             experimental_telemetry: agent.telemetry ?? this.config.telemetry,
         });
         let handoffTriggered = false;
+        const outputProcessors = this.getAgentOutputProcessors(agent);
+        const bufferOutput = this.outputProcessorMode === 'buffer' && outputProcessors.length > 0;
+        let bufferedText = '';
         for await (const chunk of result.fullStream) {
             if (chunk.type === 'text-delta') {
                 if (handoffTriggered) {
                     continue;
                 }
-                yield* this.emit(context, { type: 'text-delta', text: chunk.text });
+                if (bufferOutput) {
+                    bufferedText += chunk.text;
+                }
+                else {
+                    yield* this.emit(context, { type: 'text-delta', text: chunk.text });
+                }
             }
             if (chunk.type === 'tool-call') {
                 const args = 'args' in chunk ? chunk.args : chunk.input;
@@ -795,7 +1073,34 @@ Do not change the flow requirements. Keep the reply concise.`;
             }
         }
         const response = await result.response;
-        context.session.messages.push(...response.messages);
+        if (bufferOutput) {
+            const processed = await this.runOutputProcessing(agent, context, bufferedText);
+            if (processed.tripwire) {
+                yield* this.emit(context, {
+                    type: 'tripwire',
+                    phase: 'output',
+                    processorId: processed.tripwire.processorId,
+                    reason: processed.tripwire.reason,
+                    message: processed.tripwire.message,
+                });
+            }
+            yield* this.emit(context, { type: 'text-delta', text: processed.text });
+            context.session.messages.push({ role: 'assistant', content: processed.text });
+        }
+        else {
+            const beforeLen = context.session.messages.length;
+            context.session.messages.push(...response.messages);
+            const tripwires = await this.postProcessPersistedAssistantMessages(agent, context, beforeLen);
+            for (const t of tripwires) {
+                yield* this.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;
@@ -816,8 +1121,18 @@ Do not change the flow requirements. Keep the reply concise.`;
         if (detourRules?.emergency && this.matchesDetourRule(input, detourRules.emergency)) {
             const emergencyText = detourRules.emergencyMessage
                 ?? 'This sounds urgent. Please call local emergency services immediately or go to the nearest emergency room.';
-            context.session.messages.push({ role: 'assistant', content: emergencyText });
-            yield* this.emit(context, { type: 'text-delta', text: emergencyText });
+            const processed = await this.runOutputProcessing(agent, context, emergencyText);
+            if (processed.tripwire) {
+                yield* this.emit(context, {
+                    type: 'tripwire',
+                    phase: 'output',
+                    processorId: processed.tripwire.processorId,
+                    reason: processed.tripwire.reason,
+                    message: processed.tripwire.message,
+                });
+            }
+            context.session.messages.push({ role: 'assistant', content: processed.text });
+            yield* this.emit(context, { type: 'text-delta', text: processed.text });
             yield* this.emit(context, { type: 'turn-end' });
             if (detourRules.emergencyHandoffAgent) {
                 onHandoff(detourRules.emergencyHandoffAgent, 'Emergency pattern matched');
@@ -843,7 +1158,26 @@ Do not change the flow requirements. Keep the reply concise.`;
             sessionMessages: context.session.messages,
             state: flowState,
             telemetry: agent.telemetry ?? this.config.telemetry,
+            toolCallGuard: async ({ toolName, args }) => {
+                const callRecord = {
+                    toolCallId: crypto.randomUUID(),
+                    toolName,
+                    args,
+                    success: true,
+                    timestamp: Date.now(),
+                };
+                const enforcement = await this.enforcer.check(callRecord, {
+                    previousCalls: context.toolCallHistory,
+                    currentStep: context.stepCount,
+                    sessionState: context.session.state ?? {},
+                });
+                if (!enforcement.allowed) {
+                    return { allowed: false, reason: enforcement.reason ?? 'Tool call blocked by enforcement' };
+                }
+                return { allowed: true };
+            },
         });
+        let persistedStartIndex = context.session.messages.length;
         if (!flowState?.initialized) {
             for await (const part of flowManager.initialize()) {
                 switch (part.type) {
@@ -907,6 +1241,26 @@ Do not change the flow requirements. Keep the reply concise.`;
                         });
                         break;
                     }
+                    case 'tool-error': {
+                        const toolCallId = part.toolCallId
+                            ?? toolCalls.find(call => call.toolName === part.toolName && call.error === undefined)?.toolCallId
+                            ?? crypto.randomUUID();
+                        const callRecord = toolCalls.find(call => call.toolCallId === toolCallId);
+                        if (callRecord) {
+                            callRecord.success = false;
+                            callRecord.error = new Error(part.error);
+                            callRecord.durationMs = Date.now() - callRecord.timestamp;
+                            context.toolCallHistory.push(callRecord);
+                            await this.hookRunner.onToolError(context, callRecord, callRecord.error);
+                        }
+                        yield* this.emit(context, {
+                            type: 'tool-error',
+                            toolCallId,
+                            toolName: part.toolName,
+                            error: part.error,
+                        });
+                        break;
+                    }
                     case 'handoff':
                         onHandoff(part.targetAgent, part.reason);
                         break;
@@ -932,6 +1286,18 @@ Do not change the flow requirements. Keep the reply concise.`;
                         break;
                 }
             }
+            // Sanitize/redact anything FlowManager persisted during initialization.
+            const tripwires = await this.postProcessPersistedAssistantMessages(agent, context, persistedStartIndex);
+            for (const t of tripwires) {
+                yield* this.emit(context, {
+                    type: 'tripwire',
+                    phase: 'output',
+                    processorId: t.processorId,
+                    reason: t.reason,
+                    message: t.message,
+                });
+            }
+            persistedStartIndex = context.session.messages.length;
         }
         for await (const part of flowManager.process(input, { appendUserToSession: false })) {
             switch (part.type) {
@@ -995,6 +1361,26 @@ Do not change the flow requirements. Keep the reply concise.`;
                     });
                     break;
                 }
+                case 'tool-error': {
+                    const toolCallId = part.toolCallId
+                        ?? toolCalls.find(call => call.toolName === part.toolName && call.error === undefined)?.toolCallId
+                        ?? crypto.randomUUID();
+                    const callRecord = toolCalls.find(call => call.toolCallId === toolCallId);
+                    if (callRecord) {
+                        callRecord.success = false;
+                        callRecord.error = new Error(part.error);
+                        callRecord.durationMs = Date.now() - callRecord.timestamp;
+                        context.toolCallHistory.push(callRecord);
+                        await this.hookRunner.onToolError(context, callRecord, callRecord.error);
+                    }
+                    yield* this.emit(context, {
+                        type: 'tool-error',
+                        toolCallId,
+                        toolName: part.toolName,
+                        error: part.error,
+                    });
+                    break;
+                }
                 case 'handoff':
                     onHandoff(part.targetAgent, part.reason);
                     break;
@@ -1020,6 +1406,17 @@ Do not change the flow requirements. Keep the reply concise.`;
                     break;
             }
         }
+        // Sanitize/redact anything FlowManager persisted during this user turn.
+        const tripwires = await this.postProcessPersistedAssistantMessages(agent, context, persistedStartIndex);
+        for (const t of tripwires) {
+            yield* this.emit(context, {
+                type: 'tripwire',
+                phase: 'output',
+                processorId: t.processorId,
+                reason: t.reason,
+                message: t.message,
+            });
+        }
         if (flowManager.hasEnded) {
             this.clearFlowState(context.session, agent.id);
         }
@@ -1039,10 +1436,112 @@ Do not change the flow requirements. Keep the reply concise.`;
     getAllAgents() {
         return Array.from(this.agents.values());
     }
+    buildProcessorContext(context) {
+        return {
+            session: context.session,
+            agentId: context.agentId,
+            toolCallHistory: context.toolCallHistory,
+        };
+    }
+    getAgentOutputProcessors(agent) {
+        return [
+            ...this.outputProcessors,
+            ...(agent.outputProcessors ?? []),
+        ];
+    }
+    applyRedactionsToText(text) {
+        if (!this.outputRedactions || this.outputRedactions.length === 0)
+            return text;
+        let out = text;
+        for (const r of this.outputRedactions) {
+            out = out.replace(r.re, r.replacement);
+        }
+        return out;
+    }
+    async runOutputProcessing(agent, context, text) {
+        const processors = this.getAgentOutputProcessors(agent);
+        let cur = text;
+        if (processors.length > 0) {
+            const outcome = await runOutputProcessors({
+                processors,
+                text: cur,
+                messages: context.session.messages,
+                context: this.buildProcessorContext(context),
+            });
+            if (outcome.blocked) {
+                const msg = this.applyRedactionsToText(outcome.message);
+                return {
+                    text: msg,
+                    tripwire: { processorId: outcome.processorId, reason: outcome.reason, message: msg },
+                };
+            }
+            cur = outcome.text;
+        }
+        cur = this.applyRedactionsToText(cur);
+        return { text: cur };
+    }
+    async postProcessPersistedAssistantMessages(agent, context, startIndex) {
+        const tripwires = [];
+        const msgs = context.session.messages;
+        for (let i = startIndex; i < msgs.length; i++) {
+            const m = msgs[i];
+            if (!m || m.role !== 'assistant' || typeof m.content !== 'string')
+                continue;
+            const res = await this.runOutputProcessing(agent, context, m.content);
+            msgs[i] = { ...m, content: res.text };
+            if (res.tripwire) {
+                tripwires.push(res.tripwire);
+            }
+        }
+        return tripwires;
+    }
     async *emit(context, part) {
+        // Defense-in-depth redaction of streamed assistant output.
+        if (this.outputRedactions && this.outputRedactions.length > 0) {
+            const sessionId = context.session.id;
+            if (part.type === 'text-delta') {
+                const next = this.applyOutputRedactions(sessionId, part.text, false);
+                if (next) {
+                    const redacted = { ...part, text: next };
+                    await this.hookRunner.onStreamPart(context, redacted);
+                    yield redacted;
+                }
+                return;
+            }
+            if (part.type === 'turn-end' || part.type === 'done') {
+                const flushed = this.applyOutputRedactions(sessionId, '', true);
+                if (flushed) {
+                    const carryPart = { type: 'text-delta', text: flushed };
+                    await this.hookRunner.onStreamPart(context, carryPart);
+                    yield carryPart;
+                }
+                this.redactCarryBySession.delete(sessionId);
+            }
+        }
         await this.hookRunner.onStreamPart(context, part);
         yield part;
     }
+    applyOutputRedactions(sessionId, text, flush) {
+        if (!this.outputRedactions || this.outputRedactions.length === 0)
+            return text;
+        const carry = this.redactCarryBySession.get(sessionId) ?? '';
+        let combined = `${carry}${text}`;
+        for (const r of this.outputRedactions) {
+            combined = combined.replace(r.re, r.replacement);
+        }
+        const keep = flush ? 0 : this.redactLookbehind;
+        if (keep === 0) {
+            this.redactCarryBySession.set(sessionId, '');
+            return combined;
+        }
+        if (combined.length <= keep) {
+            this.redactCarryBySession.set(sessionId, combined);
+            return '';
+        }
+        const out = combined.slice(0, combined.length - keep);
+        this.redactCarryBySession.set(sessionId, combined.slice(-keep));
+        return out;
+    }
 }
 export function createRuntime(config) {
     return new Runtime(config);