@ariaflowagents/core 0.6.3 → 0.7.1

package/dist/runtime/Runtime.js

@@ -1,17 +1,26 @@
-import { streamText, generateText, streamObject, Output, stepCountIs } from 'ai';
+import crypto from 'node:crypto';
+import { streamText, generateText, Output, stepCountIs } from 'ai';
 import { z } from 'zod';
-import { FlowManager } from '../flows/FlowManager.js';
 import { createHandoffTool, isHandoffResult } from '../tools/handoff.js';
 import { isFinalResult } from '../tools/final.js';
-import { InjectionQueue, commonInjections } from './InjectionQueue.js';
+import { InjectionQueue, getPolicyProfileInjections } from './InjectionQueue.js';
 import { checkStopConditions, defaultStopConditions } from '../guards/StopConditions.js';
 import { HookRunner } from '../hooks/HookRunner.js';
 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 { createStreamCallbackAdapter } from '../callbacks/streamCallback.js';
+import { compileSanitizePattern } from '../flows/template.js';
 import { runInputProcessors, runOutputProcessors } from '../processors/ProcessorRunner.js';
+import { getChunkArgs, getChunkErrorMessage, getChunkResult, getChunkToolCallId } from '../utils/streamChunk.js';
+import { normalizeModelMessage } from '../utils/messageNormalization.js';
+import { isRecord } from '../utils/isRecord.js';
+import { ExtractionEngine } from './ExtractionEngine.js';
+import { SessionEventManager } from './SessionEventManager.js';
+import { SuggestionManager } from './SuggestionManager.js';
+import { FlowExecutor } from './FlowExecutor.js';
+import { SessionWorkingMemory } from './WorkingMemory.js';
 export class Runtime {
     config;
     agents = new Map();
@@ -32,9 +41,22 @@ export class Runtime {
     outputProcessors;
     outputProcessorMode;
     outputRedactions;
-    redactCarryBySession = new Map();
+    redactCarryKey = '__ariaRedactCarry';
     redactLookbehind = 64;
+    runtimeEventLogKey = 'runtimeEventLog';
+    runtimeSessionTurnKey = '__ariaSessionTurn';
+    runtimeEventLogMaxEntries = 2000;
+    checkpointEventTypes = new Set([
+        'tool-result',
+        'tool-error',
+        'flow-transition',
+    ]);
+    extractionEngine;
+    sessionEventManager;
+    suggestionManager;
+    flowExecutor;
     wrapToolsWithEnforcement(context, tools) {
+        console.log('[Runtime] Wrapping tools:', Object.keys(tools));
         const wrapped = {};
         for (const [toolName, toolDef] of Object.entries(tools ?? {})) {
             const exec = toolDef?.execute;
@@ -45,10 +67,15 @@ export class Runtime {
             wrapped[toolName] = {
                 ...toolDef,
                 execute: async (args, options) => {
+                    const toolCallId = typeof options?.toolCallId === 'string'
+                        ? options.toolCallId
+                        : crypto.randomUUID();
+                    const idempotencyKey = this.buildToolIdempotencyKey(context, toolName, toolCallId);
                     const callRecord = {
-                        toolCallId: options?.toolCallId ?? crypto.randomUUID(),
+                        toolCallId,
                         toolName,
                         args,
+                        idempotencyKey,
                         success: true,
                         timestamp: Date.now(),
                     };
@@ -66,7 +93,15 @@ export class Runtime {
                         throw callRecord.error;
                     }
                     // Preserve AI SDK tool execution context (toolCallId, messages, experimental_context, etc.).
-                    return exec(args, options);
+                    const enrichedOptions = this.withToolExecutionMetadata(options, context, toolName, toolCallId, idempotencyKey);
+                    try {
+                        console.log(`[Runtime] Executing tool ${toolName}...`);
+                        return await exec(args, enrichedOptions);
+                    }
+                    catch (error) {
+                        console.error(`[Runtime] Tool execution failed for ${toolName}:`, error);
+                        throw error;
+                    }
                 },
             };
         }
@@ -84,20 +119,31 @@ export class Runtime {
         this.stopConditions = config.stopConditions ?? defaultStopConditions;
         this._sessionStore = config.sessionStore ?? new MemoryStore();
         const hooks = { ...config.hooks };
-        if (config.callback) {
-            console.log('[Runtime] HTTP callback configured for:', config.callback.url);
-            console.log('[Runtime] Callback config:', JSON.stringify(config.callback, null, 2));
-            console.log('[Runtime] Hooks before wiring:', Object.keys(hooks));
-            const httpCallback = createHttpCallback(config.callback);
+        const appendOnStreamPart = (fn) => {
             const originalHook = hooks.onStreamPart;
             hooks.onStreamPart = async (context, part) => {
-                console.log('[Runtime] onStreamPart triggered for:', part.type);
                 if (originalHook) {
                     await originalHook(context, part);
                 }
-                await httpCallback(context, part);
+                await fn(context, part);
+            };
+        };
+        if (config.callback) {
+            const httpCallback = createHttpCallback(config.callback);
+            appendOnStreamPart(httpCallback);
+        }
+        if (config.streamCallback) {
+            const adapter = createStreamCallbackAdapter(config.streamCallback);
+            appendOnStreamPart(adapter.onStreamPart);
+            const originalOnEnd = hooks.onEnd;
+            hooks.onEnd = async (context, result) => {
+                if (originalOnEnd) {
+                    await originalOnEnd(context, result);
+                }
+                if (config.streamCallback?.flushOnEnd) {
+                    await adapter.flush(config.streamCallback.flushTimeoutMs ?? 2000);
+                }
             };
-            console.log('[Runtime] Hooks after wiring:', Object.keys(hooks));
         }
         this.hookRunner = new HookRunner(hooks);
         this.enforcer = new ToolEnforcer(config.enforcementRules ?? defaultEnforcementRules);
@@ -115,6 +161,16 @@ export class Runtime {
                 return { re, replacement: r.replacement };
             });
         }
+        this.extractionEngine = new ExtractionEngine({
+            defaultModel: this.defaultModel,
+            telemetry: config.telemetry,
+        });
+        this.sessionEventManager = new SessionEventManager({
+            touchSession: session => this.touchSession(session),
+            getSessionTurn: session => this.getSessionTurn(session),
+        });
+        this.suggestionManager = new SuggestionManager(config);
+        this.flowExecutor = new FlowExecutor(config);
     }
     get sessionStore() {
         return this._sessionStore;
@@ -176,12 +232,8 @@ export class Runtime {
             consecutiveErrors: 0,
             toolCallHistory: [],
         };
-        const injectionQueue = new InjectionQueue();
-        injectionQueue.add(commonInjections.professional);
-        injectionQueue.add(commonInjections.noGuessing);
-        injectionQueue.add(commonInjections.noSecrets);
-        injectionQueue.add(commonInjections.invisibleHandoffs);
-        injectionQueue.add(commonInjections.confirmDestructive);
+        this.bumpSessionTurn(session);
+        const injectionQueue = this.buildPolicyInjectionQueue();
         // 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();
@@ -190,11 +242,17 @@ export class Runtime {
             this.abortControllers.delete(session.id);
         };
         controller.signal.addEventListener('abort', abortHandler);
+        let externalAbortHandler;
         if (abortSignal) {
-            const externalAbortHandler = () => {
+            externalAbortHandler = () => {
                 controller.abort(abortSignal.reason ?? 'External abort');
             };
-            abortSignal.addEventListener('abort', externalAbortHandler);
+            if (abortSignal.aborted) {
+                controller.abort(abortSignal.reason ?? 'External abort');
+            }
+            else {
+                abortSignal.addEventListener('abort', externalAbortHandler);
+            }
         }
         await this.hookRunner.onStart(context);
         // Run input processors BEFORE persisting the user message.
@@ -210,6 +268,7 @@ export class Runtime {
                     session,
                     agentId: activeAgentId,
                     toolCallHistory: context.toolCallHistory,
+                    abortSignal: controller.signal,
                 };
                 const outcome = await runInputProcessors({
                     processors: turnInputProcessors,
@@ -233,18 +292,19 @@ export class Runtime {
                 processedInput = outcome.input;
             }
             // Persist the (possibly modified) user message after input processors.
-            session.messages.push({ role: 'user', content: processedInput });
+            this.appendSessionMessage(session, { 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, {
+                const compacted = await this.contextManager.beforeTurn(session.messages, {
                     turnCount: this.turnCount,
                     totalTokens,
                     sessionId: session.id,
                 });
+                session.messages = this.normalizeSessionHistory(compacted);
                 const messagesAfter = session.messages.length;
                 if (messagesBefore !== messagesAfter) {
                     yield* this.emit(context, {
@@ -261,86 +321,75 @@ export class Runtime {
             await this.hookRunner.onEnd(context, { success: true });
         }
         catch (error) {
-            await this.hookRunner.onError(context, error);
-            await this.hookRunner.onEnd(context, { success: false, error: error });
-            yield* this.emit(context, { type: 'error', error: error.message });
+            if (controller.signal.aborted) {
+                yield* this.emit(context, {
+                    type: 'interrupted',
+                    sessionId: context.session.id,
+                    reason: controller.signal.reason ?? 'Operation cancelled',
+                    timestamp: new Date(),
+                    lastAgentId: context.agentId,
+                    lastStep: context.stepCount,
+                });
+                await this.hookRunner.onEnd(context, { success: false });
+            }
+            else {
+                await this.hookRunner.onError(context, error);
+                await this.hookRunner.onEnd(context, { success: false, error: error });
+                yield* this.emit(context, { type: 'error', error: error.message });
+            }
         }
         finally {
             controller.signal.removeEventListener('abort', abortHandler);
+            if (abortSignal && externalAbortHandler) {
+                abortSignal.removeEventListener('abort', externalAbortHandler);
+            }
             this.abortControllers.delete(session.id);
-            await this._sessionStore.save(session);
+            await this.saveSessionCheckpoint(session);
             yield* this.emit(context, { type: 'done', sessionId: session.id });
+            await this.saveSessionCheckpoint(session);
         }
     }
     async *generateSuggestions(context) {
-        const suggestionModel = this.config.suggestionModel;
-        if (!suggestionModel)
-            return;
-        const count = this.config.suggestionCount ?? 3;
-        const prompt = this.config.suggestionPrompt ??
-            `Based on the conversation above, suggest ${count} short, relevant follow-up questions or actions the user might want to take next. 
-      Keep each suggestion under 5 words.
-      Return them as an array of strings.`;
-        try {
-            const result = streamObject({
-                model: suggestionModel,
-                schema: z.object({
-                    suggestions: z.array(z.string()).min(1).max(count),
-                }),
-                messages: [
-                    ...context.session.messages,
-                    { role: 'user', content: prompt }
-                ],
-            });
-            for await (const partialObject of result.partialObjectStream) {
-                if (partialObject.suggestions) {
-                    yield {
-                        type: 'suggested-questions',
-                        suggestions: partialObject.suggestions.filter((s) => !!s),
-                        isPartial: true
-                    };
-                }
-            }
-            const finalObject = await result.object;
-            yield {
-                type: 'suggested-questions',
-                suggestions: finalObject.suggestions,
-                isPartial: false
-            };
-        }
-        catch (error) {
-            console.error('[Runtime] Failed to generate suggestions:', error);
-            // Don't yield error to user, just skip suggestions
-        }
+        yield* this.suggestionManager.generateSuggestions(context);
     }
     async *chat(sessionId, input, userId) {
         yield* this.stream({ input, sessionId, userId });
     }
     async *runLoop(context, injectionQueue, input, abortController) {
         let currentInput = input;
+        const abortSignal = abortController?.signal;
+        let interruptionEmitted = false;
+        let circularRecoveryActive = false;
+        let circularRecoveryAttempts = 0;
         while (context.handoffStack.length < this.maxHandoffs) {
-            if (abortController?.signal.aborted) {
-                yield* this.emit(context, {
-                    type: 'interrupted',
-                    sessionId: context.session.id,
-                    reason: abortController.signal.reason ?? 'Operation cancelled',
-                    timestamp: new Date(),
-                    lastAgentId: context.agentId,
-                    lastStep: context.stepCount,
-                });
+            if (abortSignal?.aborted) {
+                if (!interruptionEmitted) {
+                    interruptionEmitted = true;
+                    yield* this.emit(context, {
+                        type: 'interrupted',
+                        sessionId: context.session.id,
+                        reason: abortSignal.reason ?? 'Operation cancelled',
+                        timestamp: new Date(),
+                        lastAgentId: context.agentId,
+                        lastStep: context.stepCount,
+                    });
+                }
                 return;
             }
             // 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) {
+            if (priorVisits >= 2 && !circularRecoveryActive) {
                 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;
+                circularRecoveryAttempts += 1;
+                if (circularRecoveryAttempts > 1) {
+                    yield* this.emitCircularHandoffFallback(context);
+                    return;
+                }
+                circularRecoveryActive = true;
+                // Reset path tracking for this turn and force a single in-agent recovery pass.
+                context.handoffStack = [];
             }
             context.handoffStack.push(context.agentId);
             const agent = this.agents.get(context.agentId);
@@ -355,6 +404,7 @@ export class Runtime {
                     session: context.session,
                     agentId: agent.id,
                     toolCallHistory: context.toolCallHistory,
+                    abortSignal,
                 };
                 const outcome = await runInputProcessors({
                     processors: agent.inputProcessors,
@@ -379,6 +429,7 @@ export class Runtime {
                     const last = context.session.messages[context.session.messages.length - 1];
                     if (last && last.role === 'user' && typeof last.content === 'string') {
                         last.content = currentInput;
+                        this.touchSession(context.session);
                     }
                 }
             }
@@ -388,10 +439,12 @@ export class Runtime {
             if (agent.autoRetrieve) {
                 const toolName = agent.autoRetrieve.toolName ?? 'auto_retrieve';
                 const toolCallId = crypto.randomUUID();
+                const idempotencyKey = this.buildToolIdempotencyKey(context, toolName, toolCallId);
                 const callRecord = {
                     toolCallId,
                     toolName,
                     args: { input: currentInput },
+                    idempotencyKey,
                     success: true,
                     timestamp: Date.now(),
                 };
@@ -410,7 +463,7 @@ export class Runtime {
                 });
                 let result = null;
                 try {
-                    result = await agent.autoRetrieve.run({ input: currentInput, context });
+                    result = await agent.autoRetrieve.run({ input: currentInput, context, abortSignal });
                     callRecord.result = result;
                 }
                 catch (error) {
@@ -449,8 +502,36 @@ export class Runtime {
                     };
                 }
             }
-            const system = this.buildSystemPrompt(agent, injectionQueue, autoContext, context);
-            const handoffCandidates = this.getHandoffCandidates(agent);
+            const extractionSnapshot = await this.runTurnExtraction(agent, context, currentInput, abortSignal);
+            let activeRoutes;
+            if (this.isTriageAgent(agent)) {
+                const agentContext = this.buildAgentContext(currentInput, context, abortSignal);
+                const results = await Promise.all(agent.routes.map(async (route) => {
+                    if (!route.condition)
+                        return { route, active: true };
+                    try {
+                        const active = await route.condition(currentInput, agentContext);
+                        return { route, active };
+                    }
+                    catch (error) {
+                        console.error(`Error evaluating condition for route ${route.agentId}:`, error);
+                        return { route, active: false }; // Fail-closed on error
+                    }
+                }));
+                activeRoutes = results.filter(r => r.active).map(r => r.route);
+            }
+            let system = this.buildSystemPrompt(agent, injectionQueue, autoContext, context, activeRoutes);
+            const turnToolErrors = [];
+            if (extractionSnapshot?.includeInSystemPrompt) {
+                system += this.extractionEngine.buildExtractionSystemBlock(extractionSnapshot);
+            }
+            if (circularRecoveryActive) {
+                system = `${system}\n\n## Routing Recovery
+A circular handoff was detected in this turn.
+Stay with the current agent and provide the best direct answer.
+Do not call or suggest handoff/transfer tools in this response.`;
+            }
+            const handoffCandidates = circularRecoveryActive ? [] : this.getHandoffCandidates(agent, activeRoutes);
             const handoffTool = handoffCandidates.length > 0
                 ? createHandoffTool(handoffCandidates, context.agentId)
                 : null;
@@ -475,7 +556,7 @@ export class Runtime {
                     for await (const part of this.runFlowAgent(agent, context, currentInput, system, handoffTool ?? undefined, (target, reason) => {
                         handoffTo = target;
                         handoffReason = reason ?? 'No reason provided';
-                    }, toolCalls)) {
+                    }, toolCalls, abortSignal)) {
                         yield part;
                     }
                     context.consecutiveErrors = 0;
@@ -491,6 +572,20 @@ export class Runtime {
                     });
                 }
                 catch (error) {
+                    if (abortSignal?.aborted) {
+                        if (!interruptionEmitted) {
+                            interruptionEmitted = true;
+                            yield* this.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 this.hookRunner.onError(context, error);
                     yield* this.emit(context, { type: 'error', error: error.message });
@@ -525,21 +620,27 @@ 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.'),
                             });
-                            // AI SDK v6+ recommended structured output approach.
-                            const { output: decision } = await generateText({
-                                model: model,
-                                output: Output.object({ schema }),
-                                system: this.buildStructuredTriagePrompt(agent),
-                                messages: context.session.messages,
-                                experimental_telemetry: agent.telemetry ?? this.config.telemetry,
-                            });
-                            const allowed = new Set(agent.routes.map(route => route.agentId));
-                            let target = decision.agentId;
-                            if (!allowed.has(target)) {
-                                target = agent.defaultAgent ?? agent.routes[0]?.agentId ?? agent.id;
+                            try {
+                                // AI SDK v6+ recommended structured output approach.
+                                const { output: decision } = await generateText({
+                                    model: model,
+                                    output: Output.object({ schema }),
+                                    system: this.buildStructuredTriagePrompt(agent, activeRoutes),
+                                    messages: context.session.messages,
+                                    abortSignal,
+                                    experimental_telemetry: agent.telemetry ?? this.config.telemetry,
+                                });
+                                const allowed = new Set(agent.routes.map(route => route.agentId));
+                                let target = decision.agentId;
+                                if (!allowed.has(target)) {
+                                    target = agent.defaultAgent ?? agent.routes[0]?.agentId ?? agent.id;
+                                }
+                                handoffTo = target;
+                                handoffReason = decision.reason ?? 'Routed by triage';
+                            }
+                            catch (err) {
+                                throw err;
                             }
-                            handoffTo = target;
-                            handoffReason = decision.reason ?? 'Routed by triage';
                             yield* this.emit(context, { type: 'step-end', step: context.stepCount, agentId: agent.id });
                             await this.hookRunner.onStepEnd(context, context.stepCount, {
                                 toolCalls: [],
@@ -554,6 +655,7 @@ export class Runtime {
                             system,
                             messages: context.session.messages,
                             tools,
+                            abortSignal,
                             // Let the AI SDK handle tool-calling steps internally.
                             // Default is stepCountIs(1), which ends right after tool-calls.
                             stopWhen: stepCountIs(agent.toolMaxSteps ?? 5),
@@ -576,6 +678,10 @@ export class Runtime {
                                 if (finalResult) {
                                     continue;
                                 }
+                                // Fail-closed: Suppress text delta if critical tool errors have occurred in this turn.
+                                if (turnToolErrors.length > 0) {
+                                    continue;
+                                }
                                 if (bufferOutput) {
                                     bufferedText += chunk.text;
                                 }
@@ -584,11 +690,12 @@ export class Runtime {
                                 }
                             }
                             if (chunk.type === 'tool-call') {
-                                const args = 'args' in chunk ? chunk.args : chunk.input;
+                                const args = getChunkArgs(chunk);
                                 const callRecord = {
                                     toolCallId: chunk.toolCallId,
                                     toolName: chunk.toolName,
                                     args,
+                                    idempotencyKey: this.buildToolIdempotencyKey(context, chunk.toolName, chunk.toolCallId),
                                     success: true,
                                     timestamp: Date.now(),
                                 };
@@ -612,11 +719,10 @@ export class Runtime {
                                 });
                             }
                             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);
+                                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);
@@ -624,17 +730,24 @@ export class Runtime {
                                         callRecord.args = args;
                                     context.toolCallHistory.push(callRecord);
                                     await this.hookRunner.onToolError(context, callRecord, callRecord.error);
+                                    // Fail-closed: Track critical tool errors to block turn finalization.
+                                    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* this.emit(context, {
                                     type: 'tool-error',
-                                    toolCallId: chunk.toolCallId,
+                                    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 = 'result' in chunk ? chunk.result : chunk.output;
+                                const toolResult = getChunkResult(chunk);
                                 const callRecord = toolCalls.find(call => call.toolCallId === chunk.toolCallId);
                                 if (callRecord) {
                                     callRecord.result = toolResult;
@@ -661,6 +774,8 @@ export class Runtime {
                                         callRecord.success = false;
                                         callRecord.error = new Error(reason);
                                         await this.hookRunner.onToolError(context, callRecord, callRecord.error);
+                                        // Fail-closed: Track enforcement failures as critical errors.
+                                        turnToolErrors.push(callRecord);
                                         yield* this.emit(context, {
                                             type: 'tool-error',
                                             toolCallId: chunk.toolCallId,
@@ -722,8 +837,17 @@ export class Runtime {
                         // 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;
+                        if (finalResult || (bufferOutput && finishReason !== 'tool-calls') || turnToolErrors.length > 0) {
+                            let rawText = finalResult ? finalResult.text : bufferedText;
+                            // Fail-closed: Suppress success message if critical tool failed.
+                            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* this.emit(context, {
+                                    type: 'error',
+                                    error: `Turn blocked by critical tool failures: ${failedTools}`,
+                                });
+                            }
                             const processed = await this.runOutputProcessing(agent, context, rawText);
                             if (processed.tripwire) {
                                 yield* this.emit(context, {
@@ -734,14 +858,14 @@ export class Runtime {
                                     message: processed.tripwire.message,
                                 });
                             }
-                            if (bufferOutput) {
+                            if (bufferOutput || turnToolErrors.length > 0) {
                                 yield* this.emit(context, { type: 'text-delta', text: processed.text });
                             }
-                            context.session.messages.push({ role: 'assistant', content: processed.text });
+                            this.appendSessionMessage(context.session, { role: 'assistant', content: processed.text });
                         }
                         else {
                             const beforeLen = context.session.messages.length;
-                            context.session.messages.push(...response.messages);
+                            this.appendSessionMessages(context.session, response.messages);
                             const tripwires = await this.postProcessPersistedAssistantMessages(agent, context, beforeLen);
                             for (const t of tripwires) {
                                 yield* this.emit(context, {
@@ -773,6 +897,21 @@ export class Runtime {
                         }
                     }
                     catch (error) {
+                        console.error('RUNTIME_LOOP_ERROR:', error);
+                        if (abortSignal?.aborted) {
+                            if (!interruptionEmitted) {
+                                interruptionEmitted = true;
+                                yield* this.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 this.hookRunner.onError(context, error);
                         yield* this.emit(context, { type: 'error', error: error.message });
@@ -784,6 +923,17 @@ export class Runtime {
             }
             yield* this.emit(context, { type: 'agent-end', agentId: agent.id });
             await this.hookRunner.onAgentEnd(context, agent.id);
+            if (circularRecoveryActive && handoffTo) {
+                yield* this.emit(context, {
+                    type: 'error',
+                    error: `Circular handoff recovery failed: attempted handoff ${context.agentId} -> ${handoffTo}`,
+                });
+                yield* this.emitCircularHandoffFallback(context);
+                return;
+            }
+            if (circularRecoveryActive) {
+                circularRecoveryActive = false;
+            }
             if (!handoffTo) {
                 break;
             }
@@ -810,12 +960,34 @@ export class Runtime {
             }
             context.session.activeAgentId = handoffTo;
             context.session.currentAgent = handoffTo;
+            await this.saveSessionCheckpoint(context.session);
             context.agentId = handoffTo;
         }
         if (context.handoffStack.length >= this.maxHandoffs) {
             yield* this.emit(context, { type: 'error', error: `Maximum handoffs (${this.maxHandoffs}) exceeded` });
         }
     }
+    getCircularHandoffFallbackMessage() {
+        const configured = this.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 *emitCircularHandoffFallback(context) {
+        const fallback = this.getCircularHandoffFallbackMessage();
+        this.appendSessionMessage(context.session, { role: 'assistant', content: fallback });
+        yield* this.emit(context, { type: 'text-delta', text: fallback });
+    }
+    buildPolicyInjectionQueue() {
+        const queue = new InjectionQueue();
+        const profile = this.config.policyProfile ?? 'minimal';
+        queue.addBatch(getPolicyProfileInjections(profile));
+        if (this.config.policyInjections && this.config.policyInjections.length > 0) {
+            queue.addBatch(this.config.policyInjections);
+        }
+        return queue;
+    }
     createSession(id, userId) {
         const now = new Date();
         return {
@@ -845,26 +1017,47 @@ export class Runtime {
     isTriageAgent(agent) {
         return agent.type === 'triage';
     }
-    buildSystemPrompt(agent, injectionQueue, autoContext, context) {
+    buildPromptMemoryView(session, agent) {
+        const memory = session.workingMemory ?? {};
+        const allowlist = agent.promptMemoryAllowlist ?? this.config.promptMemoryAllowlist;
+        const internalKeys = [
+            this.runtimeEventLogKey,
+            this.runtimeSessionTurnKey,
+            this.redactCarryKey,
+        ];
+        const filtered = {};
+        for (const [key, value] of Object.entries(memory)) {
+            if (internalKeys.includes(key)) {
+                continue;
+            }
+            if (allowlist && !allowlist.includes(key)) {
+                continue;
+            }
+            filtered[key] = value;
+        }
+        return filtered;
+    }
+    buildSystemPrompt(agent, injectionQueue, autoContext, context, activeRoutes) {
         const basePrompt = this.isTriageAgent(agent)
-            ? this.buildTriagePrompt(agent)
+            ? this.buildTriagePrompt(agent, activeRoutes)
             : agent.systemPrompt;
         const autoBlock = autoContext?.text?.trim()
             ? `\n\n## ${autoContext.label}\n${autoContext.text}`
             : '';
         const systemInjections = injectionQueue.getFor('system');
-        const memory = context?.session?.workingMemory ?? {};
+        const memory = context?.session ? this.buildPromptMemoryView(context.session, agent) : {};
         const memoryBlock = Object.keys(memory).length > 0
             ? `\n\n## Known Information\n${JSON.stringify(memory, null, 2)}`
             : '';
         const merged = `${basePrompt}${autoBlock}${memoryBlock}`;
         return systemInjections ? `${merged}\n\n${systemInjections}` : merged;
     }
-    buildStructuredTriagePrompt(agent) {
-        const routeDescriptions = agent.routes
+    buildStructuredTriagePrompt(agent, activeRoutes) {
+        const routes = activeRoutes ?? agent.routes;
+        const routeDescriptions = routes
             .map(route => `- ${route.agentId}: ${route.description}`)
             .join('\n');
-        const allowed = agent.routes.map(route => route.agentId);
+        const allowed = routes.map(route => route.agentId);
         const defaultNote = agent.defaultAgent ? `Default: ${agent.defaultAgent}` : 'Default: none';
         return `${agent.systemPrompt}
 
@@ -879,8 +1072,9 @@ Return a JSON object with:
 - stayWithCurrent: boolean (true only if current agent is best fit)
 ${defaultNote}`;
     }
-    buildTriagePrompt(agent) {
-        const routeDescriptions = agent.routes
+    buildTriagePrompt(agent, activeRoutes) {
+        const routes = activeRoutes ?? agent.routes;
+        const routeDescriptions = routes
             .map(route => `- **${route.agentId}**: ${route.description}`)
             .join('\n');
         const defaultNote = agent.defaultAgent
@@ -896,9 +1090,10 @@ ${routeDescriptions}
 - When the customer needs specialized help, use the handoff tool
 - Always provide a brief reason for the handoff${defaultNote}`;
     }
-    getHandoffCandidates(agent) {
+    getHandoffCandidates(agent, activeRoutes) {
         if (this.isTriageAgent(agent)) {
-            return agent.routes
+            const routes = activeRoutes ?? agent.routes;
+            return routes
                 .map(route => this.agents.get(route.agentId))
                 .filter((candidate) => Boolean(candidate));
         }
@@ -918,15 +1113,45 @@ ${routeDescriptions}
         }
         return stored;
     }
+    buildAgentContext(input, context, abortSignal) {
+        return {
+            session: context.session,
+            messages: context.session.messages,
+            workingMemory: new SessionWorkingMemory(context.session),
+            currentAgent: context.agentId,
+            turnCount: this.turnCount,
+            metadata: context.session.metadata,
+            abortSignal,
+        };
+    }
     setFlowState(session, agentId, state) {
         session.agentStates[agentId] = {
             agentId,
             state: state,
             lastActive: new Date(),
         };
+        this.updateFlowStateSnapshot(session, agentId, state);
+        this.touchSession(session);
     }
     clearFlowState(session, agentId) {
         delete session.agentStates[agentId];
+        this.touchSession(session);
+    }
+    updateFlowStateSnapshot(session, agentId, state) {
+        const existing = session.workingMemory.flowStateByAgent;
+        const byAgent = typeof existing === 'object' && existing !== null
+            ? { ...existing }
+            : {};
+        byAgent[agentId] = {
+            currentNode: state.context.currentNode,
+            collectedData: state.context.collectedData,
+            nodeHistory: state.context.nodeHistory,
+            initialized: state.initialized,
+            flowEnded: state.flowEnded,
+            updatedAt: new Date().toISOString(),
+        };
+        session.workingMemory.flowStateByAgent = byAgent;
+        this.touchSession(session);
     }
     buildFlowWithHandoff(agent, handoffTool, suppressAutoRespond) {
         // If we don't need to inject a handoff tool and we don't need to suppress the initial autoRespond,
@@ -976,64 +1201,74 @@ ${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) {
-            return true;
-        }
-        const rules = agent.detourRules;
-        if (rules) {
-            const normalized = input.trim().toLowerCase();
-            if (rules.allowShortAffirmations !== false &&
-                /^(yes|yep|yeah|ok|okay|sure|great|thanks|thank you|please|proceed|go ahead)\b/.test(normalized)) {
-                return true;
-            }
-            if (rules.allowDateTime !== false &&
-                (/\b20\d{2}-\d{2}-\d{2}\b/.test(normalized) || /\b\d{1,2}:\d{2}\b/.test(normalized))) {
-                return true;
+    getExtractionConfig(agent, session) {
+        if (this.isFlowAgent(agent)) {
+            const flowState = this.getFlowState(session, agent.id);
+            const nodeId = flowState?.context.currentNode ?? agent.initialNode;
+            const node = this.getFlowNode(agent, nodeId);
+            const config = node?.extraction ?? agent.extraction;
+            if (!config) {
+                return null;
             }
-            if (this.matchesDetourRule(normalized, rules.deny)) {
-                return false;
-            }
-            if (this.matchesDetourRule(normalized, rules.allow)) {
-                return true;
-            }
-        }
-        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:
-${renderedNodePrompt}
-
-Collected data:
-${JSON.stringify(collectedData, null, 2)}
-
-Return only one word: "flow" if the input should be handled by the flow step, or "detour" if it should be answered outside the flow then resume.`;
-        const result = await generateText({
-            model: (agent.model ?? this.defaultModel),
-            system: routerPrompt,
-            prompt: input,
-            experimental_telemetry: agent.telemetry ?? this.config.telemetry,
-        });
-        const decision = result.text.trim().toLowerCase();
-        if (decision.startsWith('detour')) {
-            return false;
+            return { config, nodeId };
         }
-        if (decision.startsWith('flow')) {
-            return true;
+        if (!agent.extraction) {
+            return null;
         }
-        return true;
+        return { config: agent.extraction };
+    }
+    async runTurnExtraction(agent, context, input, abortSignal) {
+        return this.extractionEngine.runTurnExtraction(agent, context, input, {
+            getFlowState: (s, id) => this.getFlowState(s, id),
+            setFlowState: (s, id, st) => this.setFlowState(s, id, st),
+            getFlowNode: (a, nid) => this.getFlowNode(a, nid),
+            isFlowAgent: (a) => this.isFlowAgent(a),
+            touchSession: (s) => this.touchSession(s),
+        }, abortSignal);
+    }
+    async shouldHandleFlowInput(agent, input, flowState, abortSignal) {
+        return this.flowExecutor.shouldHandleFlowInput(agent, input, flowState, this.getFlowExecutorHelpers(), abortSignal);
+    }
+    async *runDetourResponse(agent, context, input, flowState, handoffTool, onHandoff, abortSignal) {
+        yield* this.flowExecutor.runDetourResponse(agent, context, input, flowState, handoffTool, onHandoff, this.getFlowExecutorHelpers(), abortSignal);
+    }
+    async *runFlowAgent(agent, context, input, systemPrompt, handoffTool, onHandoff, toolCalls, abortSignal) {
+        yield* this.flowExecutor.runFlowAgent(agent, context, input, systemPrompt, handoffTool, onHandoff, toolCalls, this.getFlowExecutorHelpers(), abortSignal);
     }
-    matchesDetourRule(input, patterns) {
+    getFlowExecutorHelpers() {
+        return {
+            emit: (ctx, part) => this.emit(ctx, part),
+            runOutputProcessing: (agent, ctx, text) => this.runOutputProcessing(agent, ctx, text),
+            appendSessionMessage: (s, m) => this.appendSessionMessage(s, m),
+            appendSessionMessages: (s, ms) => this.appendSessionMessages(s, ms),
+            postProcessPersistedAssistantMessages: (agent, ctx, start) => this.postProcessPersistedAssistantMessages(agent, ctx, start),
+            getAgentOutputProcessors: (agent) => this.getAgentOutputProcessors(agent),
+            getSessionTurn: (s) => this.getSessionTurn(s),
+            buildToolIdempotencyKey: (ctx, tn, tcid) => this.buildToolIdempotencyKey(ctx, tn, tcid),
+            setFlowState: (s, id, st) => this.setFlowState(s, id, st),
+            getFlowState: (s, id) => this.getFlowState(s, id),
+            updateFlowStateSnapshot: (s, id, st) => this.updateFlowStateSnapshot(s, id, st),
+            clearFlowState: (s, id) => this.clearFlowState(s, id),
+            buildFlowWithHandoff: (a, ht, s) => this.buildFlowWithHandoff(a, ht, s),
+            getFlowNode: (a, ni) => this.getFlowNode(a, ni),
+            touchSession: (s) => this.touchSession(s),
+            matchesDetourRule: (i, p) => this.matchesDetourRuleHelper(i, p),
+            enforcecheck: (call, ctx) => this.enforcer.check(call, {
+                previousCalls: ctx.toolCallHistory,
+                currentStep: ctx.stepCount,
+                sessionState: ctx.session.state ?? {},
+            }),
+            enforcecheckResult: (call, ctx) => this.enforcer.checkResult(call, {
+                previousCalls: ctx.toolCallHistory,
+                currentStep: ctx.stepCount,
+                sessionState: ctx.session.state ?? {},
+            }),
+            onToolCallHook: (ctx, call) => this.hookRunner.onToolCall(ctx, call),
+            onToolResultHook: (ctx, call) => this.hookRunner.onToolResult(ctx, call),
+            onToolErrorHook: (ctx, call, error) => this.hookRunner.onToolError(ctx, call, error),
+        };
+    }
+    matchesDetourRuleHelper(input, patterns) {
         if (!patterns || patterns.length === 0) {
             return false;
         }
@@ -1052,426 +1287,6 @@ Return only one word: "flow" if the input should be handled by the flow step, or
         }
         return false;
     }
-    async *runDetourResponse(agent, context, input, flowState, handoffTool, onHandoff) {
-        const nodeId = flowState?.context.currentNode ?? agent.initialNode;
-        const node = this.getFlowNode(agent, nodeId);
-        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. ${handoffLine} Then ask the user to continue with the current flow step.
-
-Current flow step:
-${nodePrompt}
-
-Collected data:
-${JSON.stringify(collectedData, null, 2)}
-
-Do not change the flow requirements. Keep the reply concise.`;
-        const result = streamText({
-            model: (agent.model ?? this.defaultModel),
-            system: detourPrompt,
-            messages: context.session.messages,
-            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;
-                }
-                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;
-                yield* this.emit(context, {
-                    type: 'tool-call',
-                    toolCallId: chunk.toolCallId,
-                    toolName: chunk.toolName,
-                    args,
-                });
-            }
-            if (chunk.type === 'tool-result') {
-                const toolResult = 'result' in chunk ? chunk.result : chunk.output;
-                yield* this.emit(context, {
-                    type: 'tool-result',
-                    toolCallId: chunk.toolCallId,
-                    toolName: chunk.toolName,
-                    result: toolResult,
-                });
-                if (isHandoffResult(toolResult)) {
-                    const targetAgent = toolResult.targetAgent ?? toolResult.targetAgentId;
-                    onHandoff(targetAgent, toolResult.reason);
-                    handoffTriggered = true;
-                    break;
-                }
-            }
-        }
-        const response = await result.response;
-        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;
-        if (context.session.metadata) {
-            context.session.metadata.totalTokens += totalTokens;
-            context.session.metadata.totalSteps += 1;
-        }
-        if (!handoffTriggered) {
-            yield* this.emit(context, { type: 'turn-end' });
-        }
-    }
-    async *runFlowAgent(agent, context, input, systemPrompt, handoffTool, onHandoff, toolCalls) {
-        const model = agent.model ?? this.defaultModel;
-        if (!model) {
-            throw new Error(`Agent "${agent.id}" is missing a model`);
-        }
-        const detourRules = agent.detourRules;
-        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.';
-            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');
-            }
-            return;
-        }
-        const flowState = this.getFlowState(context.session, agent.id);
-        if (agent.mode === 'hybrid') {
-            const shouldRunFlow = await this.shouldHandleFlowInput(agent, input, flowState);
-            if (!shouldRunFlow) {
-                yield* this.runDetourResponse(agent, context, input, flowState, handoffTool, onHandoff);
-                return;
-            }
-        }
-        const suppressAutoRespond = !flowState?.initialized;
-        const flow = this.buildFlowWithHandoff(agent, handoffTool, suppressAutoRespond);
-        const flowManager = new FlowManager({
-            flow,
-            initialNode: agent.initialNode,
-            model: model,
-            defaultRolePrompt: systemPrompt,
-            contextMessages: flowState?.context.messages ?? [],
-            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) {
-                    case 'text-delta':
-                        yield* this.emit(context, { type: 'text-delta', text: part.text });
-                        break;
-                    case 'tool-call': {
-                        const toolCallId = part.toolCallId ?? crypto.randomUUID();
-                        const callRecord = {
-                            toolCallId,
-                            toolName: part.toolName,
-                            args: part.args,
-                            success: true,
-                            timestamp: Date.now(),
-                        };
-                        toolCalls.push(callRecord);
-                        await this.hookRunner.onToolCall(context, callRecord);
-                        yield* this.emit(context, {
-                            type: 'tool-call',
-                            toolCallId,
-                            toolName: part.toolName,
-                            args: part.args,
-                        });
-                        break;
-                    }
-                    case 'tool-result': {
-                        const toolCallId = part.toolCallId
-                            ?? toolCalls.find(call => call.toolName === part.toolName && call.result === undefined)?.toolCallId
-                            ?? crypto.randomUUID();
-                        const callRecord = toolCalls.find(call => call.toolCallId === toolCallId);
-                        if (callRecord) {
-                            callRecord.result = part.result;
-                            callRecord.durationMs = Date.now() - callRecord.timestamp;
-                            context.toolCallHistory.push(callRecord);
-                            await this.hookRunner.onToolResult(context, callRecord);
-                            const enforcement = await this.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 this.hookRunner.onToolError(context, callRecord, callRecord.error);
-                                yield* this.emit(context, {
-                                    type: 'tool-error',
-                                    toolCallId,
-                                    toolName: part.toolName,
-                                    error: reason,
-                                });
-                                yield* this.emit(context, { type: 'error', error: reason });
-                                return;
-                            }
-                        }
-                        yield* this.emit(context, {
-                            type: 'tool-result',
-                            toolCallId,
-                            toolName: part.toolName,
-                            result: part.result,
-                        });
-                        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;
-                    case 'node-enter':
-                        yield* this.emit(context, { type: 'node-enter', nodeName: part.nodeName });
-                        break;
-                    case 'node-exit':
-                        yield* this.emit(context, { type: 'node-exit', nodeName: part.nodeName });
-                        break;
-                    case 'flow-transition':
-                        yield* this.emit(context, { type: 'flow-transition', from: part.from, to: part.to });
-                        break;
-                    case 'flow-end':
-                        yield* this.emit(context, { type: 'flow-end', reason: part.reason });
-                        break;
-                    case 'turn-end':
-                        yield* this.emit(context, { type: 'turn-end' });
-                        break;
-                    case 'error':
-                        yield* this.emit(context, { type: 'error', error: part.error });
-                        break;
-                    default:
-                        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) {
-                case 'text-delta':
-                    yield* this.emit(context, { type: 'text-delta', text: part.text });
-                    break;
-                case 'tool-call': {
-                    const toolCallId = part.toolCallId ?? crypto.randomUUID();
-                    const callRecord = {
-                        toolCallId,
-                        toolName: part.toolName,
-                        args: part.args,
-                        success: true,
-                        timestamp: Date.now(),
-                    };
-                    toolCalls.push(callRecord);
-                    await this.hookRunner.onToolCall(context, callRecord);
-                    yield* this.emit(context, {
-                        type: 'tool-call',
-                        toolCallId,
-                        toolName: part.toolName,
-                        args: part.args,
-                    });
-                    break;
-                }
-                case 'tool-result': {
-                    const toolCallId = part.toolCallId
-                        ?? toolCalls.find(call => call.toolName === part.toolName && call.result === undefined)?.toolCallId
-                        ?? crypto.randomUUID();
-                    const callRecord = toolCalls.find(call => call.toolCallId === toolCallId);
-                    if (callRecord) {
-                        callRecord.result = part.result;
-                        callRecord.durationMs = Date.now() - callRecord.timestamp;
-                        context.toolCallHistory.push(callRecord);
-                        await this.hookRunner.onToolResult(context, callRecord);
-                        const enforcement = await this.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 this.hookRunner.onToolError(context, callRecord, callRecord.error);
-                            yield* this.emit(context, {
-                                type: 'tool-error',
-                                toolCallId,
-                                toolName: part.toolName,
-                                error: reason,
-                            });
-                            yield* this.emit(context, { type: 'error', error: reason });
-                            return;
-                        }
-                    }
-                    yield* this.emit(context, {
-                        type: 'tool-result',
-                        toolCallId,
-                        toolName: part.toolName,
-                        result: part.result,
-                    });
-                    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;
-                case 'node-enter':
-                    yield* this.emit(context, { type: 'node-enter', nodeName: part.nodeName });
-                    break;
-                case 'node-exit':
-                    yield* this.emit(context, { type: 'node-exit', nodeName: part.nodeName });
-                    break;
-                case 'flow-transition':
-                    yield* this.emit(context, { type: 'flow-transition', from: part.from, to: part.to });
-                    break;
-                case 'flow-end':
-                    yield* this.emit(context, { type: 'flow-end', reason: part.reason });
-                    break;
-                case 'turn-end':
-                    yield* this.emit(context, { type: 'turn-end' });
-                    break;
-                case 'error':
-                    yield* this.emit(context, { type: 'error', error: part.error });
-                    break;
-                default:
-                    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);
-        }
-        else {
-            this.setFlowState(context.session, agent.id, flowManager.getState());
-        }
-    }
     async getSession(id) {
         return this.sessionStore.get(id);
     }
@@ -1484,11 +1299,89 @@ Do not change the flow requirements. Keep the reply concise.`;
     getAllAgents() {
         return Array.from(this.agents.values());
     }
-    buildProcessorContext(context) {
+    normalizeSessionMessage(message) {
+        return normalizeModelMessage(message);
+    }
+    normalizeSessionHistory(messages) {
+        const normalized = [];
+        for (const message of messages) {
+            const next = this.normalizeSessionMessage(message);
+            if (next) {
+                normalized.push(next);
+            }
+        }
+        return normalized;
+    }
+    appendSessionMessage(session, message) {
+        const normalized = this.normalizeSessionMessage(message);
+        if (!normalized) {
+            return;
+        }
+        session.messages.push(normalized);
+        this.touchSession(session);
+    }
+    appendSessionMessages(session, messages) {
+        for (const message of messages) {
+            this.appendSessionMessage(session, message);
+        }
+    }
+    touchSession(session) {
+        const now = new Date();
+        session.updatedAt = now;
+        if (session.metadata) {
+            session.metadata.lastActiveAt = now;
+        }
+    }
+    getSessionTurn(session) {
+        const value = session.workingMemory[this.runtimeSessionTurnKey];
+        return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+    }
+    bumpSessionTurn(session) {
+        const next = this.getSessionTurn(session) + 1;
+        session.workingMemory[this.runtimeSessionTurnKey] = next;
+        this.touchSession(session);
+        return next;
+    }
+    async saveSessionCheckpoint(session) {
+        this.touchSession(session);
+        await this._sessionStore.save(session);
+    }
+    shouldCheckpointAfterPart(part) {
+        return this.checkpointEventTypes.has(part.type);
+    }
+    recordRuntimeEvent(context, part) {
+        this.sessionEventManager.recordRuntimeEvent(context, part);
+    }
+    buildToolIdempotencyKey(context, toolName, toolCallId) {
+        return `${context.session.id}:${context.agentId}:${context.stepCount}:${toolName}:${toolCallId}`;
+    }
+    withToolExecutionMetadata(options, context, toolName, toolCallId, idempotencyKey) {
+        const baseOptions = isRecord(options) ? 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: this.getSessionTurn(context.session),
+                toolName,
+                toolCallId,
+                idempotencyKey,
+            },
+        };
+    }
+    buildProcessorContext(context, abortSignal) {
         return {
             session: context.session,
             agentId: context.agentId,
             toolCallHistory: context.toolCallHistory,
+            abortSignal,
         };
     }
     getAgentOutputProcessors(agent) {
@@ -1510,11 +1403,12 @@ Do not change the flow requirements. Keep the reply concise.`;
         const processors = this.getAgentOutputProcessors(agent);
         let cur = text;
         if (processors.length > 0) {
+            const abortSignal = this.getActiveAbortController(context.session.id)?.signal;
             const outcome = await runOutputProcessors({
                 processors,
                 text: cur,
                 messages: context.session.messages,
-                context: this.buildProcessorContext(context),
+                context: this.buildProcessorContext(context, abortSignal),
             });
             if (outcome.blocked) {
                 const msg = this.applyRedactionsToText(outcome.message);
@@ -1548,46 +1442,53 @@ Do not change the flow requirements. Keep the reply concise.`;
         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);
+                const next = this.applyOutputRedactions(context.session, part.text, false);
                 if (next) {
                     const redacted = { ...part, text: next };
-                    await this.hookRunner.onStreamPart(context, redacted);
-                    yield redacted;
+                    yield* this.emitWithHooks(context, redacted);
                 }
                 return;
             }
             if (part.type === 'turn-end' || part.type === 'done') {
-                const flushed = this.applyOutputRedactions(sessionId, '', true);
+                const flushed = this.applyOutputRedactions(context.session, '', true);
                 if (flushed) {
                     const carryPart = { type: 'text-delta', text: flushed };
-                    await this.hookRunner.onStreamPart(context, carryPart);
-                    yield carryPart;
+                    yield* this.emitWithHooks(context, carryPart);
                 }
-                this.redactCarryBySession.delete(sessionId);
+                delete context.session.workingMemory[this.redactCarryKey];
             }
         }
+        yield* this.emitWithHooks(context, part);
+    }
+    async *emitWithHooks(context, part) {
+        this.recordRuntimeEvent(context, part);
         await this.hookRunner.onStreamPart(context, part);
+        if (this.shouldCheckpointAfterPart(part)) {
+            await this.saveSessionCheckpoint(context.session);
+        }
         yield part;
     }
-    applyOutputRedactions(sessionId, text, flush) {
+    applyOutputRedactions(session, text, flush) {
         if (!this.outputRedactions || this.outputRedactions.length === 0)
             return text;
-        const carry = this.redactCarryBySession.get(sessionId) ?? '';
+        const carry = typeof session.workingMemory[this.redactCarryKey] === 'string'
+            ? session.workingMemory[this.redactCarryKey]
+            : '';
         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, '');
+            session.workingMemory[this.redactCarryKey] = '';
             return combined;
         }
         if (combined.length <= keep) {
-            this.redactCarryBySession.set(sessionId, combined);
+            session.workingMemory[this.redactCarryKey] = combined;
             return '';
         }
         const out = combined.slice(0, combined.length - keep);
-        this.redactCarryBySession.set(sessionId, combined.slice(-keep));
+        session.workingMemory[this.redactCarryKey] = combined.slice(-keep);
         return out;
     }
 }