@ariaflowagents/core 0.8.1 → 0.9.0

package/dist/flows/FlowManager.js

@@ -1,12 +1,15 @@
 import { streamText, generateText, tool } from 'ai';
 import { z } from 'zod';
+import { isExtractionNode, } from '../types/index.js';
 import { createFlowTransition, isFlowTransition, isFlowUpdate } from './transitions.js';
+import { extractStructuredFields, mergeExtractionData, computeMissingFields, toNullableSchema } from './extraction.js';
 import { validateFlowConfig } from './validation.js';
 import { isHandoffResult } from '../tools/handoff.js';
 import { isFinalResult } from '../tools/final.js';
 import { compileSanitizePattern, renderNodePrompt } from './template.js';
 import { normalizeModelMessage } from '../utils/messageNormalization.js';
 import { processAIStream } from '../utils/aiStream.js';
+import { FlowCapability } from '../capabilities/FlowCapability.js';
 const implicitTransitionToolInputSchema = z.object({
     data: z.record(z.unknown()).optional(),
     message: z.string().optional(),
@@ -24,6 +27,13 @@ export class FlowManager {
     deferredActions = [];
     flowEnded = false;
     sessionMessages;
+    /**
+     * Headless FlowCapability used to share state-management code with
+     * CapabilityCallWorker. FlowManager rebuilds this lazily from its own
+     * authoritative state (context/initialized/flowEnded) whenever a getter
+     * or resolveTools() needs it — keeping streaming logic untouched.
+     */
+    flowCapability;
     /**
      * Tracks transition edges (from->to) within a single process() call.
      * Reset at the start of each user turn. Used to detect oscillation
@@ -32,6 +42,18 @@ export class FlowManager {
     turnTransitionCounts = new Map();
     /** Maximum times the same from->to edge can fire in one turn before being blocked. */
     maxOscillations;
+    pendingMetrics = [];
+    emitMetric(name, data) {
+        this.pendingMetrics.push({ name, data });
+        this.config.metricsEmitter?.(name, data);
+    }
+    /** Drain queued metrics as custom stream events. Call from any generator. */
+    *drainMetrics() {
+        while (this.pendingMetrics.length > 0) {
+            const metric = this.pendingMetrics.shift();
+            yield { type: 'custom', name: metric.name, data: metric.data, timestamp: new Date() };
+        }
+    }
     constructor(config) {
         this.config = config;
         validateFlowConfig(config.flow, config.initialNode);
@@ -72,6 +94,7 @@ export class FlowManager {
             yield* this.runInference(false);
         }
         yield* this.flushDeferredActions();
+        yield* this.drainMetrics();
     }
     async *process(userInput) {
         if (!this.initialized) {
@@ -96,6 +119,7 @@ export class FlowManager {
         }
         yield* this.runInference(true);
         yield* this.flushDeferredActions();
+        yield* this.drainMetrics();
     }
     async transitionTo(nodeId, data) {
         for await (const _part of this.transitionToGenerator(nodeId, data)) {
@@ -108,6 +132,7 @@ export class FlowManager {
         }
     }
     async *transitionToGenerator(nodeId, data, dynamicNode) {
+        const transitionStart = Date.now();
         if (!this.nodes.has(nodeId) && dynamicNode) {
             this.nodes.set(nodeId, dynamicNode);
         }
@@ -133,6 +158,16 @@ export class FlowManager {
                 return;
             }
         }
+        // Output contract validation: validate exiting node's outputSchema
+        if (previousNode?.outputSchema) {
+            const result = previousNode.outputSchema.safeParse(this.context.collectedData);
+            if (!result.success) {
+                this.emitMetric('flow.contract.validation_fail', { nodeId: previousNode.id, direction: 'output' });
+                yield { type: 'error', error: `Output contract violation on node "${previousNode.id}": ${result.error.message}` };
+                return;
+            }
+            this.emitMetric('flow.contract.validation_pass', { nodeId: previousNode.id, direction: 'output' });
+        }
         if (previousNode) {
             yield* this.runActions(previousNode.postActions ?? []);
             if (this.flowEnded) {
@@ -147,6 +182,16 @@ export class FlowManager {
             Object.assign(this.context.collectedData, data);
         }
         await this.applyContextStrategy(nextNode);
+        // Input contract validation: validate entering node's inputSchema
+        if (nextNode.inputSchema) {
+            const result = nextNode.inputSchema.safeParse(this.context.collectedData);
+            if (!result.success) {
+                this.emitMetric('flow.contract.validation_fail', { nodeId: nextNode.id, direction: 'input' });
+                yield { type: 'error', error: `Input contract violation on node "${nextNode.id}": ${result.error.message}` };
+                return;
+            }
+            this.emitMetric('flow.contract.validation_pass', { nodeId: nextNode.id, direction: 'input' });
+        }
         yield { type: 'node-enter', nodeName: nextNode.name ?? nextNode.id };
         yield* this.runActions(nextNode.preActions ?? []);
         if (this.flowEnded) {
@@ -155,28 +200,59 @@ export class FlowManager {
         if (previousNode) {
             yield { type: 'flow-transition', from: previousNode.id, to: nextNode.id };
         }
+        this.emitMetric('flow.transition.duration', {
+            durationMs: Date.now() - transitionStart,
+            from: previousNode?.id ?? '__init__',
+            to: nodeId,
+        });
     }
     get collectedData() {
-        return this.context.collectedData;
+        return this.rebuildCapability().collectedData;
     }
     get currentNode() {
-        return this.currentNodeConfig?.id;
+        return this.rebuildCapability().currentNode;
     }
     get hasEnded() {
-        return this.flowEnded;
+        return this.rebuildCapability().hasEnded;
     }
     getState() {
+        const capState = this.rebuildCapability().getState();
         return {
+            context: capState.context,
+            initialized: capState.initialized,
+            flowEnded: capState.flowEnded,
+        };
+    }
+    /**
+     * Build a FlowCapability snapshot from FlowManager's current authoritative state.
+     * FlowManager owns transitions/streaming; FlowCapability owns state-query logic.
+     * Rebuilding on each call is cheap (pure in-memory graph traversal, no I/O).
+     */
+    rebuildCapability() {
+        const state = {
             context: this.context,
             initialized: this.initialized,
             flowEnded: this.flowEnded,
         };
+        this.flowCapability = new FlowCapability({
+            flow: this.config.flow,
+            initialNode: this.config.initialNode,
+            defaultRolePrompt: this.config.defaultRolePrompt,
+            state,
+        });
+        return this.flowCapability;
     }
     async *runInference(triggeredByUserTurn) {
         if (this.flowEnded || !this.currentNodeConfig) {
             return;
         }
+        const inferenceStart = Date.now();
         const node = this.currentNodeConfig;
+        // Delegate to extraction node handler if applicable
+        if (isExtractionNode(node)) {
+            yield* this.runExtractionNodeInference(node, triggeredByUserTurn);
+            return;
+        }
         const systemPrompt = this.buildSystemPrompt(node);
         const tools = this.resolveTools(node);
         const maxSteps = node.maxSteps ?? this.config.maxSteps ?? this.config.flow.maxSteps ?? 25;
@@ -207,12 +283,21 @@ export class FlowManager {
         let finalEmitted = false;
         let hadToolResult = false;
         let pendingToolMessage = null;
+        let ttftEmitted = false;
         for await (const part of processAIStream(result.fullStream)) {
             // In buffered mode, hold text-delta tokens until we decide whether to emit.
             // This allows transition/handoff turns to stay silent in routing nodes.
             if (!(shouldBuffer && part.type === 'text-delta')) {
                 yield part;
             }
+            // Emit TTFT metric on first text-delta
+            if (part.type === 'text-delta' && !ttftEmitted) {
+                ttftEmitted = true;
+                this.emitMetric('flow.inference.ttft', {
+                    durationMs: Date.now() - inferenceStart,
+                    nodeId: node.id,
+                });
+            }
             if (part.type === 'text-delta') {
                 if (finalResult) {
                     continue;
@@ -274,6 +359,20 @@ export class FlowManager {
             }
         }
         const response = await result.response;
+        // Emit inference duration and cache metrics
+        this.emitMetric('flow.inference.duration', {
+            durationMs: Date.now() - inferenceStart,
+            nodeId: node.id,
+        });
+        const anthropicMeta = response.providerMetadata?.anthropic;
+        if (anthropicMeta) {
+            if (typeof anthropicMeta.cacheReadInputTokens === 'number' && anthropicMeta.cacheReadInputTokens > 0) {
+                this.emitMetric('flow.cache.hit_tokens', { tokens: anthropicMeta.cacheReadInputTokens, nodeId: node.id });
+            }
+            if (typeof anthropicMeta.cacheCreationInputTokens === 'number' && anthropicMeta.cacheCreationInputTokens > 0) {
+                this.emitMetric('flow.cache.miss_tokens', { tokens: anthropicMeta.cacheCreationInputTokens, nodeId: node.id });
+            }
+        }
         let safeText = responseText;
         if (shouldBuffer && node.output?.sanitize?.pattern && node.output?.sanitize?.message) {
             const re = compileSanitizePattern(node.output.sanitize.pattern);
@@ -370,15 +469,25 @@ export class FlowManager {
             yield { type: 'flow-end', reason: 'post-action' };
         }
     }
+    /**
+     * Builds the system prompt as an array of SystemModelMessage objects.
+     * Layer 1 (role prompt) is marked with Anthropic cache_control for prompt caching.
+     * Uses AI SDK SystemModelMessage format: { role: 'system', content: string, providerOptions? }.
+     */
     buildSystemPrompt(node) {
         const includeGlobalPrompt = node.addGlobalPrompt !== false;
         const rolePrompt = includeGlobalPrompt
             ? (this.config.defaultRolePrompt ?? this.config.flow.defaultRolePrompt ?? '')
             : '';
         const renderedPrompt = renderNodePrompt(node.prompt, this.context);
-        const dataKeys = Object.keys(this.context.collectedData);
+        // Filter collectedData to relevantFields if specified (Phase 3: selective data inclusion)
+        const allData = this.context.collectedData;
+        const filteredData = node.relevantFields
+            ? Object.fromEntries(Object.entries(allData).filter(([k]) => node.relevantFields.includes(k)))
+            : allData;
+        const dataKeys = Object.keys(filteredData);
         const dataContext = dataKeys.length > 0
-            ? `\n\n## Collected Information\n${JSON.stringify(this.context.collectedData, null, 2)}`
+            ? `\n\n## Collected Information\n${JSON.stringify(filteredData, null, 2)}`
             : '';
         const historyContext = this.context.nodeHistory.length > 1
             ? `\n\n## Progress\n${this.context.nodeHistory.slice(0, -1).join(' -> ')} -> **${node.name ?? node.id}**`
@@ -389,13 +498,22 @@ ${renderedPrompt}${dataContext}${historyContext}`;
 - Focus only on the current task
 - Use the available tools to progress the conversation
 - Do not attempt tasks outside your current scope`;
-        const sections = [];
+        const blocks = [];
+        // Layer 1: Role prompt (cacheable -- stable across all turns and nodes)
         if (rolePrompt.trim().length > 0) {
-            sections.push(rolePrompt.trim());
+            blocks.push({
+                role: 'system',
+                content: rolePrompt.trim(),
+                providerOptions: {
+                    anthropic: { cacheControl: { type: 'ephemeral' } },
+                },
+            });
         }
-        sections.push(currentTaskSection);
-        sections.push(instructionsSection);
-        return sections.join('\n\n');
+        // Layer 2: Node-specific task context (changes per node)
+        blocks.push({ role: 'system', content: currentTaskSection });
+        // Layer 3: Fixed instructions
+        blocks.push({ role: 'system', content: instructionsSection });
+        return blocks;
     }
     async applyContextStrategy(node) {
         const strategy = node.contextStrategy ?? this.config.flow.contextStrategy ?? 'append';
@@ -419,6 +537,7 @@ ${renderedPrompt}${dataContext}${historyContext}`;
         }
     }
     async generateSummary(node) {
+        const summaryStart = Date.now();
         const prompt = node.summaryPrompt
             ?? this.config.flow.summaryPrompt
             ?? 'Summarize the key points from this conversation in 2-3 sentences.';
@@ -436,20 +555,33 @@ ${renderedPrompt}${dataContext}${historyContext}`;
                 });
                 return result.text;
             };
+            let summary;
             if (timeoutMs <= 0) {
-                return await generate();
+                summary = await generate();
             }
-            let timeoutHandle;
-            const timeout = new Promise(resolve => {
-                timeoutHandle = setTimeout(() => resolve(null), timeoutMs);
-            });
-            const summary = await Promise.race([generate().catch(() => null), timeout]);
-            if (timeoutHandle) {
-                clearTimeout(timeoutHandle);
+            else {
+                let timeoutHandle;
+                const timeout = new Promise(resolve => {
+                    timeoutHandle = setTimeout(() => resolve(null), timeoutMs);
+                });
+                summary = await Promise.race([generate().catch(() => null), timeout]);
+                if (timeoutHandle) {
+                    clearTimeout(timeoutHandle);
+                }
             }
+            this.emitMetric('flow.summary.duration', {
+                durationMs: Date.now() - summaryStart,
+                nodeId: node.id,
+                timedOut: summary === null,
+            });
             return summary;
         }
         catch {
+            this.emitMetric('flow.summary.duration', {
+                durationMs: Date.now() - summaryStart,
+                nodeId: node.id,
+                error: true,
+            });
             return null;
         }
     }
@@ -508,23 +640,26 @@ ${renderedPrompt}${dataContext}${historyContext}`;
                 },
             };
         }
+        // When multiple transitions are requested in the same turn, take the first one.
+        // The LLM calls tools in order of intent -- the first tool call is the primary action.
+        // Conflicting targets or payloads are warned, not errored, to avoid leaving the user
+        // with no response. The first transition is the safest bet because it corresponds
+        // to the LLM's first (and usually correct) tool call.
         const firstTransition = transitions[0];
         for (let i = 1; i < transitions.length; i++) {
             const next = transitions[i];
             if (next.targetNode !== firstTransition.targetNode) {
-                return {
-                    conflict: `Conflicting transitions requested in the same turn: "${firstTransition.targetNode}" and "${next.targetNode}".`,
-                };
+                console.warn(`[AriaFlow] Conflicting transitions in the same turn: "${firstTransition.targetNode}" (tool: ${firstTransition.toolName}) ` +
+                    `vs "${next.targetNode}" (tool: ${next.toolName}). Taking the first transition "${firstTransition.targetNode}".`);
+                break;
             }
             if (!this.isEquivalentPayload(next.data, firstTransition.data)) {
-                return {
-                    conflict: `Conflicting transition payloads for node "${firstTransition.targetNode}" in the same turn.`,
-                };
+                console.warn(`[AriaFlow] Conflicting transition payloads for node "${firstTransition.targetNode}" in the same turn. Using the first payload.`);
+                break;
             }
             if ((next.node?.id ?? null) !== (firstTransition.node?.id ?? null)) {
-                return {
-                    conflict: `Conflicting dynamic node definitions for transition target "${firstTransition.targetNode}" in the same turn.`,
-                };
+                console.warn(`[AriaFlow] Conflicting dynamic node definitions for transition target "${firstTransition.targetNode}" in the same turn. Using the first definition.`);
+                break;
             }
         }
         return {
@@ -536,13 +671,25 @@ ${renderedPrompt}${dataContext}${historyContext}`;
         };
     }
     resolveTools(node) {
-        const implicitTools = this.buildImplicitTransitionTools(node);
-        let explicitTools = {};
-        if (node.tools) {
-            explicitTools =
-                typeof node.tools === 'function'
-                    ? (node.tools(this.context) ?? {})
-                    : node.tools;
+        // Resolve explicit node tools first so we know which names to exclude.
+        const explicitTools = node.tools
+            ? (typeof node.tools === 'function' ? (node.tools(this.context) ?? {}) : node.tools)
+            : {};
+        const explicitNames = new Set(Object.keys(explicitTools));
+        // Use FlowCapability to generate implicit transition tool declarations.
+        // This shares tool-building logic with CapabilityCallWorker; FlowManager
+        // wraps each ToolDeclaration in the AI SDK tool() format for streamText.
+        const cap = this.rebuildCapability();
+        const implicitTools = {};
+        for (const decl of cap.getTools()) {
+            // Skip explicit node tools — they will be merged in below with higher priority.
+            if (explicitNames.has(decl.name))
+                continue;
+            implicitTools[decl.name] = tool({
+                description: decl.description,
+                inputSchema: decl.parameters,
+                execute: decl.execute,
+            });
         }
         // Explicit node tools win on name collision to preserve backwards compatibility.
         return this.wrapTools({
@@ -742,6 +889,292 @@ ${renderedPrompt}${dataContext}${historyContext}`;
         }
         return {};
     }
+    /**
+     * Extraction node inference: loops until a Zod schema is fully satisfied.
+     * Replaces both the ExtractionEngine's generateObject call and the standard
+     * streamText inference -- single LLM call per turn.
+     *
+     * Three key correctness properties:
+     *   1. safeParse uses nullified collectedData (undefined -> null) so nullable
+     *      schema fields don't fail on absent keys.
+     *   2. The follow-up prompt only mentions REQUIRED missing fields, not optional ones.
+     *   3. On auto-transition, if the next node is also an extraction node, the last
+     *      user message is re-extracted against the new schema (cross-node carry-forward).
+     */
+    async *runExtractionNodeInference(node, triggeredByUserTurn) {
+        const extractionStart = Date.now();
+        const turnCount = this.context.nodeTurnCounts[node.id] ?? 0;
+        // Check if extraction is already complete from prior turns.
+        // Fill undefined schema keys with null so .nullable() fields pass safeParse.
+        if (this.isExtractionComplete(node)) {
+            this.emitMetric('flow.extraction.complete', { nodeId: node.id, turns: turnCount });
+            if (node.extractionCompleteTransition) {
+                yield* this.transitionToGenerator(node.extractionCompleteTransition, this.context.collectedData);
+                if (!this.flowEnded && this.currentNodeConfig) {
+                    // Cross-node carry-forward: if the next node is also an extraction node,
+                    // re-extract from the last user message against the new schema.
+                    if (isExtractionNode(this.currentNodeConfig)) {
+                        yield* this.runExtractionCarryForward(this.currentNodeConfig);
+                    }
+                    else if (this.currentNodeConfig.autoRespond !== false) {
+                        yield* this.runInference(false);
+                    }
+                }
+            }
+            return;
+        }
+        // Enforce max extraction turns
+        const maxTurns = node.extractionMaxTurns ?? 10;
+        if (turnCount > maxTurns) {
+            this.emitMetric('flow.extraction.max_turns_exceeded', { nodeId: node.id, turnCount });
+            yield { type: 'error', error: `Extraction node "${node.id}" exceeded max turns (${maxTurns})` };
+            if (node.extractionCompleteTransition) {
+                yield* this.transitionToGenerator(node.extractionCompleteTransition, this.context.collectedData);
+                if (!this.flowEnded && this.currentNodeConfig?.autoRespond !== false) {
+                    yield* this.runInference(false);
+                }
+            }
+            return;
+        }
+        // Extract structured fields from the latest user message.
+        // Use a nullable version of the schema so the LLM can return null for
+        // fields not mentioned, instead of hallucinating values.
+        //
+        // Run extraction if:
+        // - This was triggered by a user turn (normal extraction loop), OR
+        // - This is the first entry to the extraction node (turnCount === 0)
+        //   and there is a user message available (e.g., the user said something
+        //   that triggered a transition from a non-extraction node).
+        const shouldExtract = (triggeredByUserTurn || turnCount === 0) && this.context.messages.length > 0;
+        if (shouldExtract) {
+            await this.extractFromLastUserMessage(node);
+        }
+        // Re-check after extraction
+        if (this.isExtractionComplete(node)) {
+            const reqFields = node.extractionRequiredFields ?? Object.keys(node.extractionSchema?.shape ?? {});
+            const doneCollected = {};
+            for (const key of reqFields) {
+                const v = this.context.collectedData[key];
+                if (v !== undefined && v !== null) {
+                    doneCollected[key] = v;
+                }
+            }
+            this.emitMetric('flow.extraction.update', {
+                nodeId: node.id,
+                collected: doneCollected,
+                missing: [],
+            });
+            this.emitMetric('flow.extraction.complete', { nodeId: node.id, turns: turnCount });
+            this.emitMetric('flow.extraction.duration', { durationMs: Date.now() - extractionStart, nodeId: node.id });
+            yield* this.drainMetrics();
+            if (node.extractionCompleteTransition) {
+                yield* this.transitionToGenerator(node.extractionCompleteTransition, this.context.collectedData);
+                if (!this.flowEnded && this.currentNodeConfig) {
+                    if (isExtractionNode(this.currentNodeConfig)) {
+                        yield* this.runExtractionCarryForward(this.currentNodeConfig);
+                    }
+                    else if (this.currentNodeConfig.autoRespond !== false) {
+                        yield* this.runInference(false);
+                    }
+                }
+            }
+            return;
+        }
+        // Compute missing REQUIRED fields only -- do not ask for optional fields.
+        const requiredFields = node.extractionRequiredFields
+            ?? Object.keys(node.extractionSchema?.shape ?? {});
+        const missingFields = computeMissingFields(this.context.collectedData, requiredFields);
+        const collectedSnapshot = {};
+        for (const key of requiredFields) {
+            const v = this.context.collectedData[key];
+            if (v !== undefined && v !== null) {
+                collectedSnapshot[key] = v;
+            }
+        }
+        this.emitMetric('flow.extraction.update', {
+            nodeId: node.id,
+            collected: collectedSnapshot,
+            missing: missingFields,
+        });
+        this.emitMetric('flow.extraction.fields.collected', {
+            nodeId: node.id,
+            total: requiredFields.length,
+            collected: requiredFields.length - missingFields.length,
+            missing: missingFields.length,
+        });
+        yield* this.drainMetrics();
+        // If all REQUIRED fields are present but safeParse still fails (e.g., validation
+        // errors like min length), check which fields have validation issues.
+        if (missingFields.length === 0) {
+            // All required fields exist but schema validation failed.
+            // This means a field has an invalid value (wrong format, too short, etc.).
+            // Auto-transition with what we have rather than looping forever.
+            this.emitMetric('flow.extraction.complete', { nodeId: node.id, turns: turnCount });
+            this.emitMetric('flow.extraction.duration', { durationMs: Date.now() - extractionStart, nodeId: node.id });
+            if (node.extractionCompleteTransition) {
+                yield* this.transitionToGenerator(node.extractionCompleteTransition, this.context.collectedData);
+                if (!this.flowEnded && this.currentNodeConfig?.autoRespond !== false) {
+                    yield* this.runInference(false);
+                }
+            }
+            return;
+        }
+        // Generate follow-up prompt asking ONLY for required missing fields.
+        const promptMode = node.extractionPromptMode ?? 'llm';
+        if (promptMode === 'template') {
+            const prompts = missingFields.map(field => node.extractionFieldPrompts?.[field] ?? `Could you please provide your ${field}?`);
+            const followUpText = prompts.join(' ');
+            yield { type: 'text-delta', text: followUpText };
+            this.appendMessage({ role: 'assistant', content: followUpText });
+        }
+        else {
+            const systemPrompt = this.buildSystemPrompt(node);
+            const collectedSummary = Object.entries(this.context.collectedData)
+                .filter(([, v]) => v !== null && v !== undefined)
+                .map(([k, v]) => `  ${k}: ${v}`)
+                .join('\n');
+            const extractionContext = `\n\nYou are collecting required information. ` +
+                `Already collected:\n${collectedSummary || '  (nothing yet)'}\n` +
+                `Still needed: ${missingFields.join(', ')}.\n` +
+                `Ask ONLY for the missing fields listed above. Do not ask for anything else. Be concise.`;
+            const blocks = [...systemPrompt];
+            if (blocks.length > 0) {
+                blocks[blocks.length - 1] = {
+                    ...blocks[blocks.length - 1],
+                    content: blocks[blocks.length - 1].content + extractionContext,
+                };
+            }
+            const streamOptions = {
+                model: this.config.model,
+                system: blocks,
+                abortSignal: this.config.abortSignal,
+                experimental_telemetry: this.config.telemetry,
+            };
+            if (this.context.messages.length === 0) {
+                streamOptions.prompt = renderNodePrompt(node.prompt, this.context);
+            }
+            else {
+                streamOptions.messages = this.context.messages;
+            }
+            const result = streamText(streamOptions);
+            let responseText = '';
+            for await (const part of processAIStream(result.fullStream)) {
+                yield part;
+                if (part.type === 'text-delta') {
+                    responseText += part.text;
+                }
+            }
+            const response = await result.response;
+            for (const message of response.messages) {
+                this.appendMessage(message);
+            }
+            yield { type: 'turn-end', metadata: { response } };
+        }
+        this.emitMetric('flow.extraction.duration', {
+            durationMs: Date.now() - extractionStart,
+            nodeId: node.id,
+        });
+    }
+    /**
+     * Check if extraction is complete by running safeParse with nullified data.
+     * Fills undefined schema keys with null so .nullable() fields don't fail
+     * on absent keys (undefined !== null in Zod).
+     */
+    isExtractionComplete(node) {
+        const dataForParse = { ...this.context.collectedData };
+        const schemaShape = node.extractionSchema?.shape;
+        if (schemaShape) {
+            for (const key of Object.keys(schemaShape)) {
+                if (!(key in dataForParse)) {
+                    dataForParse[key] = null;
+                }
+            }
+        }
+        return node.extractionSchema.safeParse(dataForParse).success;
+    }
+    /**
+     * Extract structured fields from the last user message against a node's schema.
+     * Returns the number of NEW fields that were extracted (0 if nothing new).
+     * Used both for normal extraction turns and cross-node carry-forward.
+     */
+    async extractFromLastUserMessage(node) {
+        try {
+            const lastUserMsg = this.context.messages
+                .slice()
+                .reverse()
+                .find((m) => m.role === 'user');
+            const userInput = typeof lastUserMsg?.content === 'string' ? lastUserMsg.content : '';
+            if (userInput.length > 0) {
+                const nullableSchema = toNullableSchema(node.extractionSchema);
+                const before = { ...this.context.collectedData };
+                const extracted = await extractStructuredFields({
+                    model: this.config.model,
+                    schema: nullableSchema,
+                    userMessage: userInput,
+                    systemPrompt: node.extraction?.systemPrompt
+                        ?? 'Extract only facts explicitly stated in the latest user message. Return null for any field not clearly provided. Do not infer or guess.',
+                    abortSignal: this.config.abortSignal,
+                    telemetry: this.config.telemetry,
+                });
+                const merged = mergeExtractionData(this.context.collectedData, extracted);
+                // Count how many fields are genuinely new (not already in collectedData)
+                let newFields = 0;
+                for (const [key, value] of Object.entries(merged)) {
+                    if (value !== null && value !== undefined && before[key] !== value) {
+                        newFields++;
+                    }
+                }
+                Object.assign(this.context.collectedData, merged);
+                return newFields;
+            }
+        }
+        catch {
+            // Extraction failed; continue with what we have
+        }
+        return 0;
+    }
+    /**
+     * Cross-node extraction carry-forward: when transitioning from one extraction
+     * node to another, re-extract from the last user message against the new node's
+     * schema. This handles the case where a user provides data for multiple schemas
+     * in a single message (e.g., incident details AND vehicle details in one turn).
+     *
+     * Stops the cascade when zero new fields are extracted -- the user message has
+     * no data for this schema, so further hops would waste LLM calls.
+     */
+    async *runExtractionCarryForward(nextNode) {
+        // Try to extract from the last user message against the new schema.
+        const newFieldCount = await this.extractFromLastUserMessage(nextNode);
+        // If we extracted nothing new, stop cascading. The user message has no data
+        // for this schema. Ask the user for the missing information instead of
+        // burning LLM calls on downstream nodes.
+        if (newFieldCount === 0) {
+            if (nextNode.autoRespond !== false) {
+                yield* this.runInference(false);
+            }
+            return;
+        }
+        // If carry-forward satisfied the schema, continue the cascade.
+        if (this.isExtractionComplete(nextNode)) {
+            this.emitMetric('flow.extraction.complete', { nodeId: nextNode.id, turns: 0 });
+            if (nextNode.extractionCompleteTransition) {
+                yield* this.transitionToGenerator(nextNode.extractionCompleteTransition, this.context.collectedData);
+                if (!this.flowEnded && this.currentNodeConfig) {
+                    if (isExtractionNode(this.currentNodeConfig)) {
+                        yield* this.runExtractionCarryForward(this.currentNodeConfig);
+                    }
+                    else if (this.currentNodeConfig.autoRespond !== false) {
+                        yield* this.runInference(false);
+                    }
+                }
+            }
+            return;
+        }
+        // Extracted some fields but not enough -- ask for the rest.
+        if (nextNode.autoRespond !== false) {
+            yield* this.runInference(false);
+        }
+    }
 }
 function isRecord(value) {
     return typeof value === 'object' && value !== null;