jsfe 1.10.9 → 1.11.1

package/dist/index.js

@@ -28,6 +28,7 @@ DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 **/
 import { buildFlowStage, buildParameterStage, hasStageParameters } from './host/intent-stages.js';
+import { buildReplyRank, REPLY_OPTIONS } from './host/reply-rank.js';
 /*
   // Deploy new version to NPM:
   npm version patch -m "chore(release): %s"
@@ -137,6 +138,7 @@ const DEFAULT_MESSAGE_REGISTRY = {
         flow_switch_general_error: "I encountered an error while switching flows: {{errorMessage}}. Please try again or contact support if the issue persists.",
         // System Commands
         cmd_flow_exited: "Successfully exited {{flowName}}. How can I help you with something else?",
+        cmd_request_aborted: "The process has been cancelled at your request - how can I help you?",
         cmd_help_title: "Flow Help - {{flowName}}",
         cmd_help_available_commands: "Available commands while in this flow:",
         cmd_help_cancel: "• \"cancel flow\" - Exit this flow completely",
@@ -182,6 +184,7 @@ const DEFAULT_MESSAGE_REGISTRY = {
         flow_switch_general_error: "Encontré un error al cambiar flujos: {{errorMessage}}. Por favor intente de nuevo o contacte soporte si el problema persiste.",
         // System Commands
         cmd_flow_exited: "Salió exitosamente de {{flowName}}. ¿Cómo puedo ayudarle con algo más?",
+        cmd_request_aborted: "El proceso fue cancelado a petición suya - ¿cómo puedo ayudarle?",
         cmd_help_title: "Ayuda del Flujo - {{flowName}}",
         cmd_help_available_commands: "Comandos disponibles en este flujo:",
         cmd_help_cancel: "• \"cancelar flujo\" - Salir completamente de este flujo",
@@ -448,8 +451,8 @@ export class TransactionManager {
 function finalizeFlowTransaction(engine, frame, endedBy) {
     const declared = frame.declaredOutcome;
     if (declared) {
-        if (declared.outcome === 'unresolved') {
-            TransactionManager.fail(frame.transaction, declared.reason || 'unresolved');
+        if (declared.outcome === 'unresolved' || declared.outcome === 'user_aborted') {
+            TransactionManager.fail(frame.transaction, declared.reason || declared.outcome);
         }
         else if (declared.outcome === 'pending') {
             TransactionManager.yield(frame.transaction);
@@ -2169,8 +2172,8 @@ async function detectLanguage(input, engine) {
     }
 }
 // === FLOW EXECUTION ENGINE WITH ENHANCED ERROR HANDLING ===
-async function isFlowActivated(input, engine, userId = 'anonymous', detected) {
-    const result = detected === undefined ? await detectFlowWithParameters(input, engine) : detected;
+async function isFlowActivated(input, engine, userId = 'anonymous') {
+    const result = await detectFlowWithParameters(input, engine);
     if (result && result.flow) {
         const flow = result.flow;
         const parameters = result.parameters;
@@ -2495,8 +2498,8 @@ async function playFlowFrame(engine) {
             }
             // DISPATCH ended every flow; processActivity routes this turn's input (see handleDispatchStep)
             if (step.type === 'DISPATCH' && step.onResponse === 'continue') {
-                // ContinueCurrent retains the stack; a workflow replaces it; None hands off to the host.
-                if (engine.pendingDispatchFrom !== null)
+                // An answer retains the stack; abort (a RETURN) and a new request (intent detection) end every flow.
+                if (engine.pendingDispatchFrom !== null || getCurrentStackLength(engine) === 0)
                     return result;
                 continue;
             }
@@ -2882,7 +2885,7 @@ function enforceParameterTypes(flow, parameters) {
     return result;
 }
 /** The structured form of the intent-detection call, passed to aiCallback as its 4th argument. */
-function buildDetectFlowRequest(input, lastChatTurn, flows, responseContext) {
+function buildDetectFlowRequest(input, lastChatTurn, flows) {
     const conversation = [];
     for (const entry of [lastChatTurn?.user, lastChatTurn?.assistant]) {
         if (entry && (entry.role === 'user' || entry.role === 'assistant')) {
@@ -2892,8 +2895,6 @@ function buildDetectFlowRequest(input, lastChatTurn, flows, responseContext) {
             // absent, or a role the conversation cannot carry
         }
     }
-    if (responseContext !== undefined)
-        conversation.push({ role: 'assistant', content: responseContext });
     return {
         task: 'detect_flow',
         input: String(sanitizeInput(input)),
@@ -2919,8 +2920,8 @@ function buildDetectFlowRequest(input, lastChatTurn, flows, responseContext) {
  * ({ flowName } / { parameters }). A stage-1 failure reaches the host as before; a stage-2 failure starts the flow
  * without its parameters (it asks for them) rather than losing the turn.
  */
-async function detectFlowInTwoStages(input, engine, flows, responseContext) {
-    const { input: cleanInput, conversation } = buildDetectFlowRequest(input, engine.lastChatTurn, [], responseContext);
+async function detectFlowInTwoStages(input, engine, flows) {
+    const { input: cleanInput, conversation } = buildDetectFlowRequest(input, engine.lastChatTurn, []);
     const stage1 = buildFlowStage(cleanInput, conversation, flows.map(f => ({ id: f.id, name: f.name, description: String(f.description ?? '') })));
     const reply1 = parseStageReply(await fetchAiResponse(stage1.llm.system, stage1.llm.user, engine.aiCallback, engine.aiTimeOut, stageSchema('detect_flow', stage1.llm.schema), stage1));
     const said = String(reply1.flowName ?? 'None');
@@ -2944,13 +2945,50 @@ async function detectFlowInTwoStages(input, engine, flows, responseContext) {
             return { flow, parameters: enforceParameterEnums(flow, enforceParameterTypes(flow, ownParametersOnly(flow, given))) };
         }
         catch (error) {
-            if (flow.id === '__jsfe_continue_current__' && responseContext !== undefined)
-                throw error;
             logger.warn(`detectFlowWithParameters: stage 2 failed for "${flow.name}" (${error.message}) - the flow starts without its parameters`);
             return { flow, parameters: {} };
         }
     }
 }
+/**
+ * The reply ranker (jsfe/host reply-rank): what the latest message does with the question a contextual DISPATCH
+ * asked — `answers`, `abort` or `new_request`. ONE aiCallback call whose 4th argument carries both executors'
+ * instructions; the host answers with System One and covers it with a text model (its aiCallbackRank). A reply that
+ * is not an offered option throws, and the pending step stays for the caller's error policy. `confident` is false only
+ * when the host says `answers` is the default because no option cleared its cut (`fallback: true`); an answer
+ * without that flag (a text model's pick, or a host that does not send it) is a confident one.
+ */
+async function rankReply(input, engine, question) {
+    const { input: cleanInput, conversation } = buildDetectFlowRequest(input, engine.lastChatTurn, []);
+    const request = buildReplyRank(cleanInput, conversation, question);
+    const reply = parseStageReply(await fetchAiResponse(request.llm.system, request.llm.user, engine.aiCallback, engine.aiTimeOut, stageSchema('rank_reply', request.llm.schema), request));
+    const option = String(reply.option ?? '');
+    if (!REPLY_OPTIONS.includes(option))
+        throw new Error(`rank_reply: "${option.slice(0, 40)}" is not an offered option`);
+    const confident = reply.fallback !== true;
+    logger.info(`rank_reply: ${option}${confident ? '' : ' (default: no option cleared the cut)'} for ${JSON.stringify(cleanInput)}`);
+    return { option, confident };
+}
+/**
+ * The field a confidently ranked answer carries as said when extraction finds nothing: the ONE parameter of a
+ * declaration that marks it `verbatim: true` (an open answer whose words are the value, such as a reason). Opt-in:
+ * a field that names a thing to look up (a product, a city) needs a real extraction, never the whole reply.
+ */
+function verbatimReplyField(parameters) {
+    return parameters.length === 1 && parameters[0].verbatim === true ? parameters[0].name : null;
+}
+/**
+ * A typed contextual response: the reply answers the question, so its declared fields are extracted with the
+ * intent stage-2 request (the question is the assistant's last turn). Missing fields stay missing; a failure throws.
+ */
+async function extractReplyParameters(input, engine, question, parameters) {
+    const { input: cleanInput, conversation } = buildDetectFlowRequest(input, engine.lastChatTurn, []);
+    const reply = { id: '__jsfe_reply__', name: 'CurrentQuestion', version: '1.0.0', description: 'The reply to the current question', steps: [], parameters: parameters.map(({ verbatim, ...parameter }) => parameter) };
+    const stage2 = buildParameterStage(cleanInput, conversation.concat([{ role: 'assistant', content: question }]), reply);
+    const answer = parseStageReply(await fetchAiResponse(stage2.llm.system, stage2.llm.user, engine.aiCallback, engine.aiTimeOut, stageSchema('extract_parameters', stage2.llm.schema), stage2));
+    const given = answer.parameters && typeof answer.parameters === 'object' ? answer.parameters : {};
+    return structuredClone(enforceParameterEnums(reply, enforceParameterTypes(reply, ownParametersOnly(reply, given))));
+}
 /** The OpenAI-compatible response_format wrapper a host already reads from the 3rd argument. */
 function stageSchema(name, schema) {
     return JSON.stringify({ type: 'json_schema', json_schema: { name, strict: true, schema } });
@@ -2966,7 +3004,7 @@ export async function getFlowForInput(input, engine) {
     const result = await detectFlowWithParameters(input, engine);
     return result ? result.flow : null;
 }
-export async function detectFlowWithParameters(input, engine, continuation, responseContext) {
+export async function detectFlowWithParameters(input, engine) {
     // CRITICAL: This function requires AI access via engine.aiCallback
     // Without AI, the engine cannot detect user intent and activate flows
     // Sessions would never be activated as no workflows could be triggered
@@ -2984,7 +3022,7 @@ export async function detectFlowWithParameters(input, engine, continuation, resp
         }
         // Filter to only primary flows for AI intent detection
         const primaryFlows = flowsMenu.filter(flow => flow.primary === true);
-        const flowsForIntentDetection = (primaryFlows.length > 0 ? primaryFlows : flowsMenu).concat(continuation ? [continuation] : []);
+        const flowsForIntentDetection = primaryFlows.length > 0 ? primaryFlows : flowsMenu;
         logger.debug(`Using ${flowsForIntentDetection.length} flows for intent detection (${primaryFlows.length} primary flows available)`);
         // A host start (ContextEntry.start) answers detection for this turn: that flow, with its arguments.
         if (engine.hostStart) {
@@ -3014,7 +3052,7 @@ export async function detectFlowWithParameters(input, engine, continuation, resp
             return null;
         }
         if (engine.intentDetection === 'two-stage') {
-            return await detectFlowInTwoStages(input, engine, flowsForIntentDetection, responseContext);
+            return await detectFlowInTwoStages(input, engine, flowsForIntentDetection);
         }
         else {
             // the original single call, below
@@ -3046,12 +3084,10 @@ export async function detectFlowWithParameters(input, engine, continuation, resp
        </chat-history>\n\n`;
         }
         // Let AI errors (timeout, communication failures) propagate to the host
-        if (responseContext !== undefined)
-            context += `<current-response-context>\n${responseContext}\n</current-response-context>\n`;
-        const request = buildDetectFlowRequest(input, engine.lastChatTurn, flowsForIntentDetection, responseContext);
+        const request = buildDetectFlowRequest(input, engine.lastChatTurn, flowsForIntentDetection);
         const aiResponse = await fetchAiTask(task, rules, context, input, flowsForIntentDetection, jsonSchema, engine.aiCallback, engine.aiTimeOut, request);
         if (aiResponse && aiResponse.flowName && aiResponse.flowName !== 'None' && aiResponse.flowName !== 'null') {
-            const flow = flowsMenu.concat(continuation ? [continuation] : []).find(flow => flow.name.toLowerCase() === aiResponse.flowName.toLowerCase() || flow.id === aiResponse.flowName);
+            const flow = flowsMenu.find(flow => flow.name.toLowerCase() === aiResponse.flowName.toLowerCase() || flow.id === aiResponse.flowName);
             if (flow) {
                 // Defensive: strip empty-string keys from AI-generated parameters.
                 // AI occasionally emits { "": value } which would cascade into flow
@@ -4123,6 +4159,21 @@ async function handleDispatchStep(currentFlowFrame, engine) {
     }
     return terminateForDispatch(currentFlowFrame, engine);
 }
+/** A withdrawn request ends as a RETURN does: the DISPATCH step is consumed and every flow finalizes and ends. */
+function terminateForAbort(currentFlowFrame, engine) {
+    const step = currentFlowFrame.flowStepsStack.pop();
+    // The caller chose to stop: `user_aborted`, whatever the step declared for an unanswered question; its reason says where.
+    const declared = step.outcome !== undefined ? resolveDeclaredOutcome(step, currentFlowFrame, engine) : currentFlowFrame.declaredOutcome;
+    currentFlowFrame.declaredOutcome = { outcome: 'user_aborted', reason: declared?.reason || 'request_withdrawn' };
+    while (engine.flowStacks.length > 0) {
+        const poppedStack = engine.flowStacks.pop();
+        for (const flow of poppedStack || []) {
+            finalizeFlowTransaction(engine, flow, 'return');
+            auditLogger.logFlowExit(flow.flowName, currentFlowFrame.userId, flow.transaction.id, 'request_withdrawn');
+        }
+    }
+    initializeFlowStacks(engine);
+}
 function terminateForDispatch(currentFlowFrame, engine) {
     // DISPATCH = forget every flow and treat THIS turn's input as if no flow had been active:
     // processActivity runs intent detection on the input the turn started with (never a flow
@@ -5685,22 +5736,11 @@ async function handleIntentInterruption(input, engine, userId) {
         currentFlowFrame.lastSayMessage ||
         currentFlowFrame.flowStepsStack.length > 0;
     logger.debug(`Interrupt intent analysis for: ${input} pendingVariable: ${currentFlowFrame.pendingVariable}, lastSayMessage: ${!!currentFlowFrame.lastSayMessage}, stepsLeft: ${currentFlowFrame.flowStepsStack.length}`);
-    // Use AI to detect if this is a strong intent for a different flow
-    let intentAnalysis = null;
-    if (engine.aiCallback) {
-        intentAnalysis = await analyzeIntentStrength(input, engine);
-        logger.debug(`Intent analysis result:`, JSON.stringify(intentAnalysis));
-    }
-    else {
-        // Fallback to exact match for non-AI environments
-        const flowsMenu = engine.flowsMenu || [];
-        const matchingFlow = flowsMenu.find(flow => flow.id.toLowerCase() === input.toLowerCase() || flow.name.toLowerCase() === input.toLowerCase());
-        intentAnalysis = {
-            isStrongIntent: !!matchingFlow,
-            targetFlow: matchingFlow ? matchingFlow.id : null
-        };
-        logger.info(`Intent analysis (no AI):`, intentAnalysis);
-    }
+    // The same intent detection as a new request (two-stage when the host configured it): a detected flow interrupts,
+    // started with the arguments detection extracted.
+    const detected = await detectFlowWithParameters(input, engine);
+    const intentAnalysis = { isStrongIntent: !!detected, targetFlow: detected ? detected.flow.name : null, parameters: detected?.parameters || {}, originalInput: input };
+    logger.debug(`Interruption detection: ${JSON.stringify({ targetFlow: intentAnalysis.targetFlow, parameters: intentAnalysis.parameters })}`);
     if (intentAnalysis.isStrongIntent && intentAnalysis.targetFlow) {
         // Check if the target flow is different from current flow
         if (intentAnalysis.targetFlow !== currentFlowName) {
@@ -5713,76 +5753,6 @@ async function handleIntentInterruption(input, engine, userId) {
     return null; // No strong intent interruption detected
 }
 // Analyze intent strength using AI
-async function analyzeIntentStrength(input, engine) {
-    const currentFlowFrame = getCurrentFlowFrame(engine);
-    const currentFlowName = currentFlowFrame.flowName;
-    const flowsMenu = engine.flowsMenu || [];
-    // Use the enhanced fetchAiTask worker with JSON schema
-    const task = "Analyze the user input within the current flow context to determine if it represents a STRONG intent to switch to a completely different workflow, or if it's a response to the current flow.";
-    const rules = `Critical Analysis Framework:
-1. Examine the flow history to understand what question or prompt the current flow is expecting
-2. Determine if the user input is:
-   - A STRONG intent for a new workflow (clear, specific action request)
-   - A response to the current flow's prompt (continue current flow)
-   - A clarification or question about the current flow (continue current flow)
-
-STRONG intent indicators (switch to new flow):
-- Explicit action requests: "I want to make a payment", "Check my account balance"
-- Complete topic changes: "What's the weather?" when in a payment flow
-- New service requests: "I need to transfer money" when in account verification
-
-WEAK intent indicators (continue current flow):
-- Direct responses to prompts: "1", "2", "Yes", "No", specific values
-- Follow-up questions: "What does that mean?", "Can you clarify?"
-- Partial information: Single words, numbers, or brief phrases that answer the current question
-- Corrections: "Actually, it's 123-456-7890" when asked for a phone number
-
-Consider the flow context carefully - if the flow just asked a specific question, treat the input as a response unless it's clearly unrelated.`;
-    // Use flow context when analyzing intent (we're already in a flow)
-    let context = `CURRENT SITUATION: User is in "${currentFlowName}" flow. Analyze if their input is a response to this flow or a request for a different workflow.
-
-IMPORTANT: Be very conservative about interrupting flows - only classify as STRONG intent if the input is clearly unrelated to what the current flow is asking for.`;
-    if (currentFlowFrame.contextStack && currentFlowFrame.contextStack.length > 0) {
-        const flowContext = flattenContextStack(currentFlowFrame.contextStack, true);
-        context = `<flow-history>
-${flowContext}
-</flow-history>
-
-${context}`;
-    }
-    const jsonSchema = JSON.stringify({
-        type: "json_schema",
-        json_schema: {
-            name: "intent_analysis",
-            strict: true,
-            schema: {
-                type: "object",
-                properties: {
-                    isStrongIntent: { type: "boolean" },
-                    targetFlow: { type: ["string", "null"] },
-                    confidence: { type: "number" },
-                    reasoning: { type: "string" }
-                },
-                required: ["isStrongIntent", "targetFlow", "confidence", "reasoning"],
-                additionalProperties: false
-            }
-        }
-    });
-    try {
-        const analysis = await fetchAiTask(task, rules, context, input, flowsMenu, jsonSchema, engine.aiCallback, engine.aiTimeOut);
-        // Ensure analysis is an object and add originalInput
-        if (typeof analysis === 'object' && analysis !== null) {
-            analysis.originalInput = input; // Preserve the original input
-        }
-        logger.info(`Intent analysis:`, analysis);
-        return analysis;
-    }
-    catch (error) {
-        logger.warn(`Intent analysis error:`, error.message);
-        logger.info(`Stack trace:`, error.stack);
-        return { isStrongIntent: false, targetFlow: null, confidence: 0, reasoning: `Error: ${error.message}`, originalInput: input };
-    }
-}
 // Handle confirmed switch from pending interruption
 async function handlePendingInterruptionSwitch(engine, userId) {
     const currentFlowFrame = getCurrentFlowFrame(engine);
@@ -5875,7 +5845,7 @@ async function handleRegularFlowInterruption(intentAnalysis, engine, userId) {
                 flowStepsStack: cloneFlowValue(targetFlowDefinition.steps).reverse(),
                 contextStack: [], // Start with empty context - don't use interruption input
                 inputStack: [], // Start with empty input stack - new flow will get proper input next
-                variables: getInitialVariables(engine, targetFlowDefinition), // Fresh variables for interrupting flow activation
+                variables: { ...getInitialVariables(engine, targetFlowDefinition), ...(intentAnalysis.parameters || {}) }, // fresh variables + the arguments detection extracted
                 transaction: newTransaction,
                 userId: userId,
                 startTime: Date.now()
@@ -5941,26 +5911,16 @@ async function processActivity(input, userId, engine) {
         logger.debug(`Current stack length: ${getCurrentStackLength(engine)}`);
         // A DISPATCH is consumed within the call that raised it; never carry one into another turn.
         engine.pendingDispatchFrom = null;
-        // One routing decision for the original turn, shared by guarded and ordinary dispatch.
-        let detected;
         let activatedThisTurn = false;
-        let detectedResponseContext;
+        // The reply ranker's verdict this turn. Only a new request is routed: after `answers` a later ordinary DISPATCH
+        // (e.g. an answer with nothing usable in it) hands the turn to the host, so an answer never restarts its own flow.
+        let ranked = null;
+        // `abort` is a RETURN: every flow ends and this is the turn's reply.
+        let abortReply = null;
         let guardedRoutingFailed = false;
-        const route = async (continuation, responseContext) => {
-            if (detected === undefined) {
-                detected = await detectFlowWithParameters(String(sanitizedInput), engine, continuation, responseContext);
-                detectedResponseContext = responseContext;
-            }
-            else if (continuation?.parameters?.length && (responseContext !== detectedResponseContext || JSON.stringify(continuation.parameters) !== JSON.stringify(detected?.flow.parameters))) {
-                throw new Error('A typed contextual response cannot reuse an incompatible routing decision this turn');
-            }
-            return detected;
-        };
         engine.dispatchIfMatched = async (frame, step) => {
             if (activatedThisTurn && step.responseParameters === undefined && step.responseVariable === undefined)
                 return false;
-            if (engine.flowsMenu.some(flow => flow.name.toLowerCase() === 'continuecurrent' || flow.id.toLowerCase() === '__jsfe_continue_current__'))
-                throw new Error('ContinueCurrent is reserved for contextual dispatch');
             let declaration;
             try {
                 declaration = validateContextualResponseStep(step, engine.flowsMenu.find(flow => flow.id === frame.flowId));
@@ -5971,7 +5931,7 @@ async function processActivity(input, userId, engine) {
                 guardedRoutingFailed = true;
                 throw error;
             }
-            const context = interpolateMessage(step.responseContext, frame.contextStack, frame.variables, engine).trim();
+            const question = interpolateMessage(step.responseContext, frame.contextStack, frame.variables, engine).trim();
             if (declaration) {
                 declaration.parameters = declaration.parameters.map((parameter) => ({ ...parameter, description: interpolateMessage(parameter.description, frame.contextStack, frame.variables, engine).trim() }));
                 if (declaration.parameters.some((parameter) => !parameter.description)) {
@@ -5979,36 +5939,65 @@ async function processActivity(input, userId, engine) {
                     throw new Error('Contextual response parameter description resolved empty');
                 }
             }
-            const continuation = { id: '__jsfe_continue_current__', name: 'ContinueCurrent', version: '1.0.0', primary: true, steps: [], ...(declaration ? { parameters: declaration.parameters } : {}), description: `The caller is responding to the requested ${context} or reports that the requested information is invalid, unknown or unavailable; datos incorrectos o inválidos, no lo sé, no lo tengo, no puedo dar el dato. Includes asking how to provide the requested information. Not a different service request or unrelated question; choose its workflow when offered, otherwise None for the host.` };
-            let selected;
+            // A model error leaves this live continuation pending for the caller's error policy.
+            let option;
+            let confident;
             try {
-                selected = await route(continuation, context);
+                ({ option, confident } = await rankReply(String(sanitizedInput), engine, question));
             }
             catch (error) {
                 guardedRoutingFailed = true;
                 throw error;
             }
-            // A contextual handoff must not restart its own live workflow without new input.
-            // The host has the broader dialogue needed to clarify this otherwise empty re-entry.
-            if (selected && selected.flow.id !== continuation.id && !Object.keys(selected.parameters || {}).length && engine.flowStacks.flat().some(active => active.flowId === selected.flow.id)) {
-                selected = null;
-                detected = null;
-            }
-            if (selected?.flow.id === continuation.id) {
-                if (declaration)
-                    frame.variables[declaration.variable] = structuredClone(selected.parameters || {});
+            ranked = option;
+            if (option === 'answers') {
+                if (declaration) {
+                    // A confident answer is never lost: when extraction finds nothing (or fails) in a `verbatim` field, the
+                    // field is the reply as said. A default `answers` keeps extraction as the judge, so an empty field
+                    // stays empty and the flow asks again.
+                    const verbatim = confident ? verbatimReplyField(declaration.parameters) : null;
+                    let extracted;
+                    try {
+                        extracted = await extractReplyParameters(String(sanitizedInput), engine, question, declaration.parameters);
+                    }
+                    catch (error) {
+                        if (verbatim) {
+                            logger.warn(`Contextual DISPATCH in '${frame.flowName}': extraction failed (${error?.message}); the confident answer is kept as said`);
+                            extracted = {};
+                        }
+                        else {
+                            guardedRoutingFailed = true;
+                            throw error;
+                        }
+                    }
+                    if (verbatim && !(typeof extracted[verbatim] === 'string' && extracted[verbatim].trim())) {
+                        logger.info(`Contextual DISPATCH in '${frame.flowName}': nothing extracted from a confident answer; '${verbatim}' is the reply as said`);
+                        extracted = { ...extracted, [verbatim]: String(sanitizedInput) };
+                    }
+                    else {
+                        // extraction carried the field, or the answer was not confident or not open
+                    }
+                    frame.variables[declaration.variable] = extracted;
+                }
+                else {
+                    // no typed response: the flow reads the reply itself
+                }
+                logger.info(`Contextual DISPATCH in '${frame.flowName}': the reply answers the current question; the flow continues`);
                 return false;
             }
-            stampStepRecovery(step, frame, engine);
-            terminateForDispatch(frame, engine);
-            if (!selected)
-                return true; // Real host handoff: ordinary dispatch consumes the cached None below.
-            engine.pendingDispatchFrom = null;
-            engine.recordDispatch({ fromFlow: frame.flowName, matchedFlow: selected.flow.name });
-            engine.clearFlowOutcome();
-            activatedThisTurn = true;
-            await isFlowActivated(String(sanitizedInput), engine, userId, selected);
-            return true;
+            else if (option === 'abort') {
+                // No recovery stamp: the caller chose to stop, so the host has nothing to resume or post-mortem.
+                abortReply = getSystemMessage(engine, 'cmd_request_aborted');
+                terminateForAbort(frame, engine);
+                logger.info(`Contextual DISPATCH in '${frame.flowName}': the caller withdrew the request; every flow ended`);
+                return true;
+            }
+            else {
+                stampStepRecovery(step, frame, engine);
+                terminateForDispatch(frame, engine);
+                logger.info(`Contextual DISPATCH in '${frame.flowName}': a new request; this turn's input goes to intent detection`);
+                return true;
+            }
         };
         // Check if we're already in a flow (using new stack-of-stacks)
         if (getCurrentStackLength(engine) > 0) {
@@ -6056,7 +6045,11 @@ async function processActivity(input, userId, engine) {
             logger.info(`Flow context updated. inputStack: ${JSON.stringify(currentFlowFrame.inputStack)}, contextStack length: ${currentFlowFrame.contextStack.length}`);
             try {
                 const response = await playFlowFrame(engine);
-                if (engine.pendingDispatchFrom === null) {
+                if (abortReply !== null) {
+                    logger.info(`Flow response (request withdrawn): ${abortReply}`);
+                    return abortReply;
+                }
+                else if (engine.pendingDispatchFrom === null) {
                     logger.info(`Flow response: ${response}`);
                     return response;
                 }
@@ -6083,8 +6076,7 @@ async function processActivity(input, userId, engine) {
         const dispatchedFrom = engine.pendingDispatchFrom;
         engine.pendingDispatchFrom = null;
         try {
-            const routed = await route();
-            const activatedFlow = activatedThisTurn || routed?.flow.id === '__jsfe_continue_current__' ? null : await isFlowActivated(String(sanitizedInput), engine, userId, routed);
+            const activatedFlow = activatedThisTurn || (ranked !== null && ranked !== 'new_request') ? null : await isFlowActivated(String(sanitizedInput), engine, userId);
             if (activatedFlow)
                 activatedThisTurn = true;
             if (dispatchedFrom !== null) {

package/dist/runtime-identity.js

@@ -1 +1 @@
-export const JSFE_RUNTIME_FINGERPRINT = "sha256:747832e9ef9aa989fff3e0af1692ca56be68abc6c591ea3112e86ea1d1e99bec";
+export const JSFE_RUNTIME_FINGERPRINT = "sha256:25d1acd637baced87978aa81eb3c47112eb8d82d1021dfb3fedc68aba0b8c988";

package/docs/copilot-reference.md

@@ -247,11 +247,11 @@ The loop skips accepted data and asks the first ready missing required field. Co
 
 ### Retry, yield and recovery
 
-`max_misses` defaults to two consecutive unreadable answers: clarify the first with explicit retry text or a localized “Sorry, I didn't catch that.” prefix; yield the second utterance to DISPATCH while preserving the draft. Deterministic uncertainty may yield earlier, especially unrecognized monetary instructions. Validator failures use a separate `max_attempts` budget. An out-of-order accepted answer is not a miss. On exhaustion the nearest declared `on_exhausted` receives `{form,input,failed_form,failed_input,reason:"attempts_exhausted"}` and must deliberately recover that branch; it does not receive consent.
+`max_misses` defaults to two consecutive unreadable answers: clarify the first with explicit retry text or a localized “Sorry, I didn't catch that.” prefix; yield the second utterance to DISPATCH while preserving the draft. An unreadable answer of three or more words (any words at an amount) goes to the reply ranker instead: `answers` takes the offered choice it picks, else asks again (counted against `max_attempts`); only `abort` or `new_request` leaves the form. Validator failures use a separate `max_attempts` budget. An out-of-order accepted answer is not a miss. On exhaustion the nearest declared `on_exhausted` receives `{form,input,failed_form,failed_input,reason:"attempts_exhausted"}` and must deliberately recover that branch; it does not receive consent.
 
 `must_complete:true` on a form (inherited by every field of it and of the forms nested in it) or on one field (`false` on a field opts out): an unreadable answer is never yielded to DISPATCH, however long, and neither is a confirmation miss or an unresolved ambiguity — the question is asked again, acknowledged. Use it where leaving would strand an effect in progress (a payment's card, its billing-ZIP correction). Exits stay explicit: the form's stop words, `max_attempts` with `on_exhausted`, and whatever the host intercepts before the engine. The form runaway guard counts passes without a caller answer only.
 
-Use `response:{description}` for open descriptions that need the existing intent/extraction model's interpretation. The prepared question and field description become contextual DISPATCH context. An extracted answer still passes deterministic validation; missing usable data yields with progress saved. A supported different intent routes to that flow; otherwise the host can answer with its full context. No separate field classifier/model role is needed. Do not attempt exhaustive conversational inference with keyword lists.
+Use `response:{description}` for open descriptions that need a model's interpretation. The prepared question and field description become the contextual DISPATCH question, and the reply ranker decides what the reply does: an answer is extracted and still passes deterministic validation (missing usable data yields with progress saved); a withdrawal leaves for the host; a new request routes through intent detection. No separate field classifier/model role is needed. Do not attempt exhaustive conversational inference with keyword lists.
 
 Ordinary DISPATCH is the default uncertainty escape. An explicit contextual DISPATCH may additionally declare the following step fragment (its surrounding flow must declare the response object and supply its own input/recovery steps):
 
@@ -264,7 +264,7 @@ Ordinary DISPATCH is the default uncertainty escape. An explicit contextual DISP
 }
 ```
 
-Declare `response` as a local object variable. Contextual routing offers `ContinueCurrent` along with primaries and `None`. ContinueCurrent retains the live continuation and runs following recovery steps; an optional typed response writes a cloned normalized object before continuing. A named primary replaces the continuation; None hands off. Neither writes that response object. Typed contextual v1 permits primitive string/boolean/number/integer fields, not object/array/jsonSchema. Missing fields remain missing. Errors preserve the pending step and prior object. Context is supplied to that decision without overwriting saved conversation history. This is existing configured intent/extraction, not authorization and not a snapshot restore.
+Declare `response` as a local object variable. A single open string parameter whose words are the value (a reason, a description) may add `"verbatim":true`: a confident `answers` then keeps the reply as said when extraction finds nothing. Never mark a field that names something to look up (a product, a city). The reply ranker answers `answers`, `abort` or `new_request` (nothing clear is `answers`). `answers` retains the live continuation and runs the following recovery steps; an optional typed response writes a cloned normalized object before continuing. `new_request` routes the input through intent detection; `abort` ends every flow as a RETURN with the reply `cmd_request_aborted` and outcome `user_aborted` (no recovery stamp). Neither writes that response object. Typed contextual v1 permits primitive string/boolean/number/integer fields, not object/array/jsonSchema. Missing fields remain missing. Errors preserve the pending step and prior object. Context is supplied to that decision without overwriting saved conversation history. This is existing configured intent/extraction, not authorization and not a snapshot restore.
 
 ## 7. Providers
 

package/docs/development-release.md

@@ -207,3 +207,38 @@ The 1.7.10 publication workflow was stopped before publication after the host-co
 Correct four OTP decision expressions to reference the renamed `otp_phrases` catalog. The incomplete rename in 1.7.11 prevented resend, lost-phone, later and some invalid-code recovery branches from executing correctly. Consent, authentication, action persistence and tool permissions are unchanged. A focused runtime regression executes the actual shared validator for English/Spanish lost-phone answers, resend, later and a short code, requiring no expression failures and no authentication. Tenant execution checks cover the affected account, identity, statement-delivery and proposal paths.
 
 This corrective release follows the same authorized dev-only rollout: exact consumer pins, matched shared and ai-ar-ql definitions in all three session-only dev configurations, and production unchanged. Broader execution and model results are retained separately and must be reported as observed.
+
+## 1.11.0 — the reply ranker replaces ContinueCurrent
+
+A contextual DISPATCH (`onResponse: "continue"`) now asks one question: what does the reply do with the step's question? The reply ranker (`jsfe/host` `buildReplyRank`, task `rank_reply`, 4th aiCallback argument with `llm` and `systemOne` instructions) answers `answers`, `abort` or `new_request`; nothing clear is `answers`. `answers` continues the flow, extracting declared `responseParameters` with a stage-2 request; `abort` is a RETURN: every flow ends and the reply is the new system message `cmd_request_aborted` ("The process has been cancelled at your request - how can I help you?"; es: "El proceso fue cancelado a petición suya - ¿cómo puedo ayudarle?"), outcome `user_aborted` (new: transaction failed, never a post-mortem), no recovery stamp; `new_request` ends them and routes the input through intent detection. Only a new request is routed: after `answers` a later ordinary DISPATCH in the same turn goes to the host unrouted, so an answer never restarts its own flow.
+
+Removed: the synthetic `ContinueCurrent` flow offered beside the primaries, its reserved name, and the per-turn routing cache shared between contextual and ordinary dispatch. Flow attributes and the `jsfe:contextual-responses:v1` protocol are unchanged. A host that does not know `rank_reply` answers its `llm` instructions with a text model. ReadFormResponse's question no longer sends uncertain replies to the host.
+
+## 1.11.1 — interruption uses the primary intent detection
+
+In a flow with `interruptable: true`, a reply is checked with the same intent detection as a new request (`detectFlowWithParameters`: two-stage when `engine.intentDetection = 'two-stage'`, so Jev with its LLM hedge): a detected primary interrupts on a new stack, started with the arguments stage 2 extracted. Removed: the separate `intent_analysis` call (`analyzeIntentStrength`).
+
+**EXIT is the whole answer.** Every EXIT in the authentication flows (the contact prompt, the verification code, the
+retry menus, the email prompt) now uses `isExitRequest`: the whole answer is exit, quit, abort, salir, cancel or cancelar
+(with "please" / "por favor"), or `*`. A sentence that contains one ("Cancelar el pedido" at the code prompt) is not an
+exit; at the code prompt it gets the "Let me explain" re-ask. Before, any answer containing the word (or, at the contact
+prompt, any answer of at most two words containing it) ended the authentication in contact-support.
+
+**A confident answer is never lost.** The host may add `fallback: true` to a `rank_reply` reply that is `answers` only
+because no option cleared the cut. Without it the answer is confident: when the step declares one parameter marked `verbatim: true` (new, an open
+string only; ReadFormResponse's answer is marked) and the stage-2 extraction finds nothing, or fails, the field is the
+reply as said. An unmarked field always needs a real extraction (prod
+2026-10-26: a cancellation reason ranked `answers`, extracted empty and went to the host,
+whose guru answered it). A `fallback` answer leaves extraction as the judge; ReadFormResponse then rejects the reading
+quietly and the form asks its question again, instead of handing the turn to the host.
+
+**"asesor" / "asesora" are AGENT words.**
+
+**A form gives up only for a new intent.** An answer a field's reader cannot read (three or more words, or any words at an
+amount) no longer goes straight to the host with a plain DISPATCH: the reply ranker decides (`read-form-choice` for a
+choice field, `read-form-reply` otherwise). `answers`: a choice takes the offered key the reply picks (stage-2 extraction
+of `key`, checked against the offered keys), else the question is asked again with "Sorry, I didn't catch that.",
+counted as an attempt, so `max_attempts` still bounds it; `abort` ends every flow; `new_request` goes to intent
+detection. A host fixture that answered such turns with intent detection only must now also answer `rank_reply`.
+
+**A press verb before a key picks it:** "ya oprimí el uno", "I already pressed one", "marqué el 2" (not after a negation).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsfe",
-  "version": "1.10.9",
+  "version": "1.11.1",
   "description": "TypeScript workflow engine for conversational/automation apps: multi-flow orchestration, interrupt/resume, stack-based control, robust errors, and flexible tool/REST integration.",
   "license": "MIT",
   "author": "Ron Pinkas",