@falai/agent 2.6.1 → 3.0.0

package/dist/core/ResponsePipeline.js

@@ -1,13 +1,13 @@
 /**
  * Response processing utilities shared between respond() and respondStream() methods
  */
-import { createSession, enterStep, mergeCollected, logger, historyToEvents, eventsToHistory, getLastMessageFromHistory, } from "../utils";
-import { enterFlow } from "../utils/session";
-import { createTemplateContext } from "../utils/template";
-import { FlowConfigurationError } from "../core/Step";
-import { evaluateBranches, createAiConditionEvaluator } from "./BranchEvaluator";
-import { DirectiveChainTracker } from "./DirectiveChainTracker";
-import { ResponseGenerationError } from "./ResponseGenerationError";
+import { createSession, enterStep, mergeCollected, logger, historyToEvents, eventsToHistory, getLastMessageFromHistory, } from "../utils/index.js";
+import { enterFlow } from "../utils/session.js";
+import { createTemplateContext } from "../utils/template.js";
+import { FlowConfigurationError } from "../core/Step.js";
+import { evaluateBranches, createAiConditionEvaluator } from "./BranchEvaluator.js";
+import { DirectiveChainTracker } from "./DirectiveChainTracker.js";
+import { ResponseGenerationError } from "./ResponseGenerationError.js";
 /**
  * Position fields on a Directive that represent a navigation decision.
  * When any of these is set, the directive "wins" the turn's position decision
@@ -25,6 +25,23 @@ export function hasDirectivePositionField(directive) {
         return false;
     return DIRECTIVE_POSITION_FIELDS.some((field) => directive[field] !== undefined);
 }
+/**
+ * Compute the per-key data writes the signal phase applied to a session.
+ * The signal phase and routing start from the same input session, so any
+ * key whose value differs between the input and the signal output was
+ * written by the signal phase alone (handler `updateData` calls).
+ */
+function diffSignalDataWrites(before, after) {
+    const beforeData = (before ?? {});
+    const afterData = (after ?? {});
+    const writes = {};
+    for (const key of Object.keys(afterData)) {
+        if (afterData[key] !== beforeData[key]) {
+            writes[key] = afterData[key];
+        }
+    }
+    return writes;
+}
 /**
  * Shared response processing logic between respond() and respondStream() methods
  */
@@ -85,7 +102,7 @@ export class ResponsePipeline {
      * Handle routing and step selection logic
      */
     async handleRoutingAndStepSelection(params) {
-        const { session, history, context, signal } = params;
+        const { session, history, context, signal, allowedFlows } = params;
         // PHASE 2: ROUTING + STEP SELECTION - Determine which flow and step to use (combined)
         let selectedFlow;
         let responseDirectives;
@@ -93,8 +110,19 @@ export class ResponsePipeline {
         let isFlowComplete = false;
         let completedFlows = [];
         let targetSession = session;
+        // Flows exited this turn via pendingDirective redirect/reset
+        const endedFlows = [];
+        let exitPrevFlowId;
+        let exitPrevFlowTitle;
+        let exitReason;
         // Get flows early since we need them for pending directives
         const flows = this.getFlows();
+        // Routing candidates may be narrowed for this turn (entry pins); the
+        // pendingDirective applier below still resolves targets against the FULL
+        // registry so declared redirects always resolve.
+        const routingFlows = allowedFlows && allowedFlows.length > 0
+            ? flows.filter((f) => allowedFlows.includes(f.id) || allowedFlows.includes(f.title))
+            : flows;
         // Check for pending directive from previous flow completion or external dispatch
         if (targetSession.pendingDirective) {
             const directive = targetSession.pendingDirective;
@@ -114,8 +142,15 @@ export class ResponsePipeline {
                 ...targetSession,
                 pendingDirective: nextDirective,
             };
+            // Capture the flow we're leaving so directive-driven exits surface on
+            // the response (endedFlows).
+            exitPrevFlowId = targetSession.currentFlow?.id;
+            exitPrevFlowTitle = exitPrevFlowId
+                ? flows.find((f) => f.id === exitPrevFlowId)?.title
+                : undefined;
             // Apply the directive: resolve position field to a flow/step
             if (directive.goTo) {
+                exitReason = 'goto';
                 const flowTarget = typeof directive.goTo === 'string'
                     ? directive.goTo
                     : directive.goTo.flow;
@@ -181,6 +216,7 @@ export class ResponsePipeline {
                 }
             }
             else if (directive.reset) {
+                exitReason = 'reset';
                 // Reset current flow
                 if (targetSession.currentFlow) {
                     const currentFlow = flows.find(r => r.id === targetSession.currentFlow?.id);
@@ -212,10 +248,16 @@ export class ResponsePipeline {
             }
             // Skip FlowRouter.decideFlowAndStep — the directive resolved the position
         }
-        // If no pending transition or transition handled, do normal routing
-        if (flows.length > 0 && !selectedFlow) {
+        if (exitReason &&
+            exitPrevFlowId &&
+            (!selectedFlow || selectedFlow.id !== exitPrevFlowId)) {
+            endedFlows.push({ flowId: exitPrevFlowId, title: exitPrevFlowTitle, reason: exitReason });
+        }
+        // If no pending transition or transition handled, do normal routing.
+        // Candidates honor allowedFlows; completion scoring runs over the same set.
+        if (routingFlows.length > 0 && !selectedFlow) {
             const orchestration = await this.flowRouter.decideFlowAndStep({
-                flows: flows,
+                flows: routingFlows,
                 session: targetSession,
                 history,
                 agentOptions: this.options,
@@ -241,15 +283,36 @@ export class ResponsePipeline {
             session: targetSession,
             isFlowComplete,
             completedFlows,
+            ...(endedFlows.length > 0 ? { endedFlows } : {}),
         };
     }
+    /**
+     * Combine a routing-derived session with the signal phase's non-position
+     * mutations. The routing session is the base — it owns position state AND
+     * data merges such as flow initialData and directive-carried writes; the
+     * signal phase's mutations (trigger recording under `signals`, handler
+     * data writes) are re-applied on top. Both phases start from the same
+     * input session, so their mutations cannot silently collide.
+     */
+    combineRoutingAndSignalSessions(params) {
+        const { inputSession, signalSession, routingSession } = params;
+        let combined = routingSession;
+        if (signalSession.signals !== inputSession.signals) {
+            combined = { ...combined, signals: signalSession.signals };
+        }
+        const signalWrites = diffSignalDataWrites(inputSession.data, signalSession.data);
+        if (Object.keys(signalWrites).length > 0) {
+            combined = mergeCollected(combined, signalWrites);
+        }
+        return combined;
+    }
     /**
      * Determine next step and update session
      */
     async determineNextStep(params) {
         const { selectedFlow, selectedStep, session, isFlowComplete, context, busDirective } = params;
         if (!selectedFlow) {
-            return { nextStep: undefined, session };
+            return { nextStep: undefined, session, isFlowComplete };
         }
         // ─── GUARD: directive bus winner with a position field preempts branches ───
         // Resolution precedence (design.md): bus > branches > linear > AI.
@@ -258,7 +321,7 @@ export class ResponsePipeline {
         // branches or linear/AI selection — the caller applies the bus directive.
         if (hasDirectivePositionField(busDirective)) {
             logger.debug(`[ResponsePipeline] Directive bus winner has position field — skipping branch evaluation and linear/AI selection`);
-            return { nextStep: undefined, session };
+            return { nextStep: undefined, session, isFlowComplete };
         }
         // STEP 1 (Algorithm 1): branches win over linear chain AND flow completion.
         // Evaluate branches before checking isFlowComplete — a branch can redirect
@@ -270,13 +333,20 @@ export class ResponsePipeline {
             if (currentStep?.branches && currentStep.branches.length > 0) {
                 const branchResult = await this.evaluateStepBranches(currentStep, selectedFlow, session, context);
                 if (branchResult) {
-                    return branchResult;
+                    // A branch that resolved a position overrides the router's completion
+                    // proposal. Without this, a branch that parks on a step of its own
+                    // flow (`then: '<stepId>'`, `then: { reset: true }`) keeps
+                    // isFlowComplete=true, the caller drops the step it just resolved,
+                    // and the turn ends as a silent completion — no LLM call, empty
+                    // reply, flow marked completed for the rest of the session.
+                    const resolvedPosition = Boolean(branchResult.nextStep || branchResult.flowChanged);
+                    return { ...branchResult, isFlowComplete: resolvedPosition ? false : isFlowComplete };
                 }
                 // undefined → fall through to linear/AI selection or flow completion
             }
         }
         if (isFlowComplete) {
-            return { nextStep: undefined, session };
+            return { nextStep: undefined, session, isFlowComplete: true };
         }
         let nextStep;
         // If we have a selected step from the combined routing decision, use it
@@ -315,13 +385,13 @@ export class ResponsePipeline {
                         nextStep = currentStepInstance;
                     }
                 }
-                return { nextStep, session };
+                return { nextStep, session, isFlowComplete: false };
             }
         }
         // Update session with next step
         const updatedSession = enterStep(session, nextStep.id, nextStep.description);
         logger.debug(`[ResponsePipeline] Entered step: ${nextStep.id}`);
-        return { nextStep, session: updatedSession };
+        return { nextStep, session: updatedSession, isFlowComplete: false };
     }
     /**
      * Evaluate branches on a step and resolve the `then` value.
@@ -481,17 +551,20 @@ export class ResponsePipeline {
             // Create a fresh chain tracker for this turn (Requirement 22.1)
             this.createChainTracker();
             // ROUTING SKIP OPTIMIZATION (Requirements 20.1, 20.2, 20.3):
-            // When the current step has collect fields AND pre-extraction populates at least
-            // one of those fields, skip FlowRouter.decideFlowAndStep for this turn.
-            const routingSkipResult = await this.attemptRoutingSkipForCollect(params);
-            if (routingSkipResult) {
+            // When the current step has collect fields AND step-scoped pre-extraction
+            // populates at least one of those fields, skip FlowRouter.decideFlowAndStep
+            // for this turn. The check's extraction result is reused by the fallthrough
+            // paths below so a turn costs at most ONE extraction LLM call.
+            const routingSkipCheck = await this.attemptRoutingSkipForCollect(params);
+            if (routingSkipCheck.skipResult) {
+                const skipResult = routingSkipCheck.skipResult;
                 // Even when routing is skipped, run pre-signal phase if processor is present
                 if (this.signalCoordinator.enabled) {
                     const signalResult = await this.signalCoordinator.runPrePhase(params.session, params.context, params.history);
                     // If signal halts, override the routing skip result
                     if (signalResult.mergedDirective?.halt) {
                         return {
-                            ...routingSkipResult,
+                            ...skipResult,
                             session: signalResult.updatedSession,
                             signalFirings: signalResult.firings,
                             signalHalted: true,
@@ -502,15 +575,20 @@ export class ResponsePipeline {
                     if (hasDirectivePositionField(signalResult.mergedDirective)) {
                         return this.signalCoordinator.applyPositionDirective(signalResult);
                     }
-                    // Non-position directive: propagate for pre-LLM augmentation
+                    // Non-position directive: keep the skip result (extraction merges,
+                    // step entry) and re-apply the signal phase's non-position mutations
                     return {
-                        ...routingSkipResult,
-                        session: signalResult.updatedSession,
+                        ...skipResult,
+                        session: this.combineRoutingAndSignalSessions({
+                            inputSession: params.session,
+                            signalSession: signalResult.updatedSession,
+                            routingSession: skipResult.session,
+                        }),
                         signalFirings: signalResult.firings,
                         signalPreDirective: signalResult.mergedDirective || undefined,
                     };
                 }
-                return routingSkipResult;
+                return skipResult;
             }
             // ── PARALLEL PRE-SIGNAL PHASE + ROUTING (Algorithm 5) ────────────────
             // When signalProcessor is present, run pre-signals in parallel with routing.
@@ -524,6 +602,7 @@ export class ResponsePipeline {
                         history: params.history,
                         context: params.context,
                         signal: params.signal,
+                        allowedFlows: params.allowedFlows,
                     }),
                 ]);
                 // ── Requirement 8.2: halt → discard routing, skip LLM ────────────
@@ -544,38 +623,41 @@ export class ResponsePipeline {
                 }
                 // ── Requirement 8.4: non-position directive → use routing, propagate augmentation ──
                 // ── Requirement 8.5: no directive → use routing as-is ─────────────
-                let updatedSession = signalResult.updatedSession;
-                // Apply data/context updates from signal to the routed session
+                // Base = routed session (position state AND router data merges such as
+                // flow initialData survive); the signal phase's non-position mutations
+                // (trigger state, handler data writes) are re-applied on top.
+                let updatedSession = this.combineRoutingAndSignalSessions({
+                    inputSession: params.session,
+                    signalSession: signalResult.updatedSession,
+                    routingSession: routingResult.session,
+                });
+                // Explicit dataUpdate from the signal's merged directive lands last
                 if (signalResult.mergedDirective?.dataUpdate) {
                     updatedSession = mergeCollected(updatedSession, signalResult.mergedDirective.dataUpdate);
                 }
-                // Use routing result for flow/step, but carry signal session state
-                // Merge routing session changes on top of signal session
-                const routingSession = routingResult.session;
-                updatedSession = {
-                    ...updatedSession,
-                    currentFlow: routingSession.currentFlow,
-                    currentStep: routingSession.currentStep,
-                    flowHistory: routingSession.flowHistory,
-                    pendingDirective: routingSession.pendingDirective,
-                };
                 const isFlowComplete = routingResult.isFlowComplete;
-                // PRE-EXTRACTION: same logic as below — extract data from user message
+                // PRE-EXTRACTION: same logic as below — extract data from user message.
+                // Reuses the routing-skip check's step-scoped extraction when it already
+                // ran this turn (at most ONE extraction LLM call per turn).
                 if (routingResult.selectedFlow && !isFlowComplete) {
-                    if (this.shouldPreExtractData(routingResult.selectedFlow)) {
+                    let extractedData;
+                    if (routingSkipCheck.extractionRan) {
+                        extractedData = routingSkipCheck.extractedData;
+                    }
+                    else if (this.shouldPreExtractData(routingResult.selectedFlow)) {
                         logger.debug(`[ResponsePipeline] Pre-extracting data for flow: ${routingResult.selectedFlow.title}`);
-                        const extractedData = await this.preExtractFlowData({
+                        extractedData = await this.preExtractFlowData({
                             route: routingResult.selectedFlow,
                             history: params.history,
                             context: params.context,
                             session: updatedSession,
                             signal: params.signal,
                         });
-                        if (extractedData && Object.keys(extractedData).length > 0) {
-                            logger.debug(`[ResponsePipeline] Pre-extracted data:`, extractedData);
-                            updatedSession = mergeCollected(updatedSession, extractedData);
-                            await this.updateCollectedData(extractedData);
-                        }
+                    }
+                    if (extractedData && Object.keys(extractedData).length > 0) {
+                        logger.debug(`[ResponsePipeline] Pre-extracted data:`, extractedData);
+                        updatedSession = mergeCollected(updatedSession, extractedData);
+                        await this.updateCollectedData(extractedData);
                     }
                 }
                 // Determine next step
@@ -591,9 +673,10 @@ export class ResponsePipeline {
                     selectedStep: stepResult.nextStep,
                     responseDirectives: routingResult.responseDirectives,
                     session: stepResult.session,
-                    isFlowComplete: stepResult.flowChanged ? false : isFlowComplete,
+                    isFlowComplete: stepResult.isFlowComplete,
                     signalFirings: signalResult.firings,
                     signalPreDirective: signalResult.mergedDirective || undefined,
+                    endedFlows: routingResult.endedFlows,
                 };
             }
             // ── No signal processor: existing behavior (zero overhead) ────────────
@@ -602,30 +685,37 @@ export class ResponsePipeline {
                 history: params.history,
                 context: params.context,
                 signal: params.signal,
+                allowedFlows: params.allowedFlows,
             });
             let updatedSession = routingResult.session;
             const isFlowComplete = routingResult.isFlowComplete;
             // PRE-EXTRACTION: If entering a flow that collects data, extract data from user message first
-            // This allows us to skip steps whose data is already provided
+            // This allows us to skip steps whose data is already provided.
+            // Reuses the routing-skip check's step-scoped extraction when it already
+            // ran this turn — at most ONE extraction LLM call per turn.
             if (routingResult.selectedFlow && !isFlowComplete) {
                 // Always pre-extract when flow collects data (not just on new flow entry)
                 // This ensures step selection has the most up-to-date data
-                if (this.shouldPreExtractData(routingResult.selectedFlow)) {
+                let extractedData;
+                if (routingSkipCheck.extractionRan) {
+                    extractedData = routingSkipCheck.extractedData;
+                }
+                else if (this.shouldPreExtractData(routingResult.selectedFlow)) {
                     logger.debug(`[ResponsePipeline] Pre-extracting data for flow: ${routingResult.selectedFlow.title}`);
-                    const extractedData = await this.preExtractFlowData({
+                    extractedData = await this.preExtractFlowData({
                         route: routingResult.selectedFlow,
                         history: params.history,
                         context: params.context,
                         session: updatedSession,
                         signal: params.signal,
                     });
-                    if (extractedData && Object.keys(extractedData).length > 0) {
-                        logger.debug(`[ResponsePipeline] Pre-extracted data:`, extractedData);
-                        // Merge pre-extracted data into session before step selection
-                        updatedSession = mergeCollected(updatedSession, extractedData);
-                        // Also update agent's collected data
-                        await this.updateCollectedData(extractedData);
-                    }
+                }
+                if (extractedData && Object.keys(extractedData).length > 0) {
+                    logger.debug(`[ResponsePipeline] Pre-extracted data:`, extractedData);
+                    // Merge pre-extracted data into session before step selection
+                    updatedSession = mergeCollected(updatedSession, extractedData);
+                    // Also update agent's collected data
+                    await this.updateCollectedData(extractedData);
                 }
             }
             // Determine next step using pipeline method for consistency
@@ -641,8 +731,10 @@ export class ResponsePipeline {
                 selectedStep: stepResult.nextStep, // Use the determined next step
                 responseDirectives: routingResult.responseDirectives,
                 session: stepResult.session,
-                // If a branch changed the flow, the original isFlowComplete no longer applies
-                isFlowComplete: stepResult.flowChanged ? false : isFlowComplete,
+                // determineNextStep owns the verdict: a branch that resolved a position
+                // (new flow, or a step of this one) overrides the router's proposal.
+                isFlowComplete: stepResult.isFlowComplete,
+                endedFlows: routingResult.endedFlows,
             };
         }
         catch (error) {
@@ -737,61 +829,80 @@ export class ResponsePipeline {
         return { nextStep, session, flowTransition: false };
     }
     /**
-     * Routing skip optimization (Requirements 20.1, 20.2, 20.3):
-     * When the current step declares `collect` fields AND pre-extraction populates
-     * at least one of those fields from the user's message, skip routing for this turn.
+     * Routing skip check (Requirements 20.1, 20.2, 20.3):
+     * When the current step declares `collect` fields AND step-scoped extraction
+     * populates at least one of those fields from the user's message, the caller
+     * skips routing for this turn (`skipResult`).
+     *
+     * The extraction is scoped to EXACTLY this step's collect fields — incidental
+     * mentions of other (e.g. other-flow) fields cannot pin the routing decision.
+     * It is skipped entirely when every collect field is already populated.
      *
-     * Returns the routing result if the skip applies, or undefined to fall through
-     * to normal routing.
+     * Always returns what the check did so the caller can reuse the single
+     * extraction result in its normal path instead of extracting twice:
+     * - `extractionRan` — whether an extraction LLM call was made this turn.
+     * - `extractedData` — that call's result (empty when nothing found / not run).
      */
     async attemptRoutingSkipForCollect(params) {
         const { session } = params;
+        const notApplicable = { extractionRan: false, extractedData: {} };
         // Only applies when we already have a current flow and step
         if (!session.currentFlow || !session.currentStep) {
-            return undefined;
+            return notApplicable;
         }
         // Also skip this optimization if there's a pending directive (it takes priority)
         if (session.pendingDirective) {
-            return undefined;
+            return notApplicable;
         }
         // Look up the actual Flow and Step objects to access `collect`
         const currentFlow = this.getFlows().find((f) => f.id === session.currentFlow?.id);
         if (!currentFlow) {
-            return undefined;
+            return notApplicable;
         }
         const currentStep = currentFlow.getStep(session.currentStep.id);
         if (!currentStep || !currentStep.collect || currentStep.collect.length === 0) {
-            return undefined;
+            return notApplicable;
         }
-        // We have a step with collect fields. Run pre-extraction to see if the
-        // user's message populates any of them.
         const collectFields = currentStep.collect;
+        // Every relevant field already set — the skip cannot fire; don't spend
+        // an extraction LLM call probing for it.
+        const sessionRecord = (session.data ?? {});
+        const allPopulated = collectFields.every((field) => {
+            const value = sessionRecord[String(field)];
+            return value !== undefined && value !== null;
+        });
+        if (allPopulated) {
+            return notApplicable;
+        }
         // Snapshot current data for comparison
-        const dataBefore = { ...session.data };
-        // Run pre-extraction against the current flow
+        const dataBefore = { ...sessionRecord };
+        // Step-scoped pre-extraction: see if the user's message populates any of
+        // THIS step's collect fields.
         const extractedData = await this.preExtractFlowData({
             route: currentFlow,
             history: params.history,
             context: params.context,
             session,
             signal: params.signal,
+            restrictToFields: collectFields.map(String),
         });
         if (!extractedData || Object.keys(extractedData).length === 0) {
-            return undefined;
+            return { extractionRan: true, extractedData: {} };
         }
         // Determine which collect fields were newly populated by pre-extraction
+        const extractedRecord = extractedData;
         const populatedCollectFields = [];
         for (const field of collectFields) {
-            const key = field;
-            const hadValue = dataBefore[field] !== undefined && dataBefore[field] !== null;
-            const hasNewValue = extractedData[field] !== undefined && extractedData[field] !== null;
+            const key = String(field);
+            const hadValue = dataBefore[key] !== undefined && dataBefore[key] !== null;
+            const hasNewValue = extractedRecord[key] !== undefined && extractedRecord[key] !== null;
             if (hasNewValue && !hadValue) {
                 populatedCollectFields.push(key);
             }
         }
         if (populatedCollectFields.length === 0) {
             // Pre-extraction didn't populate any declared collect field — no skip
-            return undefined;
+            return { extractionRan: true, extractedData };
         }
         // ROUTING SKIP: pre-extraction populated collect fields → retain current flow/step
         logger.debug(`[ResponsePipeline] Routing skip: pre-extraction populated collect fields [${populatedCollectFields.join(', ')}] for step "${currentStep.id}" — skipping FlowRouter`);
@@ -808,11 +919,15 @@ export class ResponsePipeline {
             context: params.context,
         });
         return {
-            selectedFlow: stepResult.flowChanged || currentFlow,
-            selectedStep: stepResult.nextStep,
-            responseDirectives: undefined,
-            session: stepResult.session,
-            isFlowComplete: false,
+            extractionRan: true,
+            extractedData,
+            skipResult: {
+                selectedFlow: stepResult.flowChanged || currentFlow,
+                selectedStep: stepResult.nextStep,
+                responseDirectives: undefined,
+                session: stepResult.session,
+                isFlowComplete: stepResult.isFlowComplete,
+            },
         };
     }
     /**
@@ -831,18 +946,41 @@ export class ResponsePipeline {
         const hasDataCollectionSteps = steps.some(step => step.collect && step.collect.length > 0);
         return hasDataCollectionSteps;
     }
+    /**
+     * Build an extraction schema limited to the given subset of agent schema
+     * fields. Used by the routing-skip probe so only the current step's collect
+     * fields are visible to the extractor.
+     */
+    buildFieldRestrictedSchema(agentSchema, fields) {
+        const properties = {};
+        for (const field of fields) {
+            const prop = agentSchema.properties?.[field];
+            if (prop) {
+                properties[field] = prop;
+            }
+        }
+        return {
+            type: "object",
+            description: `Extraction restricted to these fields: ${fields.join(', ')}`,
+            properties,
+            additionalProperties: false,
+        };
+    }
     /**
      * Pre-extract data from user message when entering a flow
      * This allows skipping steps whose data is already provided
      */
     async preExtractFlowData(params) {
-        const { route: flow, history, signal } = params;
+        const { route: flow, history, signal, restrictToFields } = params;
         // Build a schema for data extraction based on flow's fields
-        const extractionSchema = this.getSchema();
-        if (!extractionSchema) {
+        const agentSchema = this.getSchema();
+        if (!agentSchema) {
             logger.warn(`[ResponsePipeline] No schema available for pre-extraction`);
             return {};
         }
+        const extractionSchema = restrictToFields
+            ? this.buildFieldRestrictedSchema(agentSchema, restrictToFields)
+            : agentSchema;
         // Get last user message
         const lastMessage = getLastMessageFromHistory(history);
         // Build extraction prompt
@@ -855,11 +993,16 @@ export class ResponsePipeline {
             `Extract data for these fields if present:`,
         ];
         // Add field descriptions
-        if (flow.requiredFields) {
-            extractionPrompt.push(`Required fields: ${flow.requiredFields.join(', ')}`);
+        if (restrictToFields) {
+            extractionPrompt.push(`Only these fields: ${restrictToFields.join(', ')}`);
         }
-        if (flow.optionalFields) {
-            extractionPrompt.push(`Optional fields: ${flow.optionalFields.join(', ')}`);
+        else {
+            if (flow.requiredFields) {
+                extractionPrompt.push(`Required fields: ${flow.requiredFields.join(', ')}`);
+            }
+            if (flow.optionalFields) {
+                extractionPrompt.push(`Optional fields: ${flow.optionalFields.join(', ')}`);
+            }
         }
         extractionPrompt.push(``, `Return ONLY the extracted data as JSON. If no data can be extracted, return an empty object {}.`);
         // Convert Event[] to HistoryItem[] for provider call