@nexalab/agent-sdk 0.1.6 → 0.1.8

package/dist/guided-flows/runtime.js

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { z } from "zod";
 import { runNativeToolLoop } from "../native-tool-loop.js";
 import { namespaceKey } from "../tenancy.js";
 import { parseStructuredOutput, structuredOutputInstruction } from "../structured-output.js";
@@ -8,6 +9,9 @@ import { diffRequirements, evaluateRequirements } from "./requirements.js";
 import { missingCollectFields, resolveActiveStep } from "./steps.js";
 import { missingRequiredBeforeExitTools, missingRequiredTools, resolveStepTools } from "./tool-policy.js";
 import { publishFlowEvent } from "./events.js";
+const MAX_REPLY_ROUNDS = 6;
+/** Safety cap on how many consecutive silent tool-only steps a single turn can auto-chain through (see the loop in `driveFlow`). Prevents a misconfigured flow (e.g. two tool-only steps whose `when`/`exit` bounce between each other) from looping forever within one turn. */
+const MAX_CHAIN_STEPS = 8;
 const ONGOING_STATUSES = ["active", "waiting_for_user", "waiting_for_tool", "waiting_for_approval"];
 function isOngoing(status) {
     return ONGOING_STATUSES.includes(status);
@@ -42,6 +46,11 @@ export class GuidedFlowRuntime {
     key(tenant, sessionId) {
         return tenant && (tenant.tenantId || tenant.userId) ? namespaceKey(tenant, sessionId) : sessionId;
     }
+    /** Publishes onto the shared EventBus (unchanged behavior) and, if this turn supplied one, also delivers the same event directly to the turn-scoped sink. */
+    async announce(onEvent, event) {
+        await publishFlowEvent(this.options.events, event);
+        onEvent?.(event);
+    }
     async selectFlow(input) {
         const key = this.key(input.tenant, input.sessionId);
         for (const flow of this.options.flows) {
@@ -83,6 +92,15 @@ export class GuidedFlowRuntime {
         const runId = randomUUID();
         const now = () => new Date().toISOString();
         const existing = await this.options.store.getFlowState(key, flow.id);
+        // In a multi-flow agent, a flow with no prior state was necessarily just picked THIS turn by
+        // `selectFlow`'s trigger/flowSelector match (an already-ongoing flow always has `existing`
+        // state — see `selectFlow`, which returns any ongoing flow before ever consulting triggers).
+        // That means `input.text` is the phrase that CAUSED the routing, not an answer to whatever
+        // the newly-entered flow's first step asks. Reproduced live: a billing flow whose first step
+        // is a bare single-field `collect: ["idTicket"]` swallowed "quiero hacer una factura" itself
+        // as the ticket id. Single-flow agents are exempt: there's nothing else the message could be
+        // routing to, so treating turn one as a direct answer (no preceding question) is intentional.
+        const flowJustSelectedThisTurn = !existing && this.options.flows.length > 1;
         let record = existing ?? {
             flowId: flow.id,
             flowVersion: flow.version,
@@ -97,107 +115,214 @@ export class GuidedFlowRuntime {
         };
         if (!existing) {
             await this.options.hooks.fire("beforeFlowStart", { flowId: flow.id, sessionId: key, context: { taskId, runId } });
-            await publishFlowEvent(this.options.events, { type: "flow.started", flowId: flow.id, sessionId: key, taskId, runId, payload: { state: record.state } });
+            await this.announce(input.onEvent, { type: "flow.started", flowId: flow.id, sessionId: key, taskId, runId, payload: { state: record.state } });
             await this.options.hooks.fire("afterFlowStart", { flowId: flow.id, sessionId: key, context: { taskId, runId } });
         }
         else if (existing.status === "cancelled") {
             record = { ...existing, status: "active" };
-            await publishFlowEvent(this.options.events, { type: "flow.resumed", flowId: flow.id, sessionId: key, taskId, runId, payload: { state: record.state } });
+            await this.announce(input.onEvent, { type: "flow.resumed", flowId: flow.id, sessionId: key, taskId, runId, payload: { state: record.state } });
         }
         let state = record.state;
         const previousStepId = record.currentStepId;
         const stepToolLog = { ...record.stepToolLog };
         let requirements = evaluateRequirements(config, state);
         let step = resolveActiveStep(config, state);
-        await this.announceStepChange(flow, key, previousStepId, step?.id, taskId, runId);
+        if (!existing && input.initialState && Object.keys(input.initialState).length) {
+            ({ state, requirements, step } = await this.applyPatch(flow, key, taskId, runId, config, state, { set: input.initialState, source: "system" }, requirements, input.onEvent));
+        }
+        await this.announceStepChange(flow, key, previousStepId, step?.id, taskId, runId, input.onEvent);
         // --- Extraction sub-call: pull a Zod-validated partial state patch out of free text ---
         const modelPatchSchema = buildModelPatchSchema(config.stateSchema, config.protectedFields);
         let modelPatch = {};
-        try {
-            const extraction = await this.options.client.complete({
-                providerId: this.options.providerId,
-                model: this.options.model,
-                messages: [
-                    {
-                        role: "system",
-                        content: `${buildGuidedInstructions(config, step, state, this.options.skills)}\n\n${structuredOutputInstruction(modelPatchSchema, "StatePatch")}\nOnly include fields the user explicitly provided in their latest message. Omit fields that are unknown, already known, or not mentioned.`
-                    },
-                    ...input.messages,
-                    { role: "user", content: input.text }
-                ]
-            });
-            const parsed = parseStructuredOutput(modelPatchSchema, extraction.text);
-            if (parsed.ok)
-                modelPatch = parsed.data;
-            else {
-                await publishFlowEvent(this.options.events, {
+        // A step collecting a single enum field (a numbered choice, per `step.prompt`) has an
+        // unambiguous, mechanically checkable answer space — try matching the user's raw text
+        // against it (by list index, exact label, or an unambiguous partial match) before ever
+        // asking a model to "extract" it. Short colloquial answers ("si", "sip", a bare "1") are
+        // exactly where free-text extraction is least reliable — a model call can still say yes
+        // but then fail to produce the exact enum literal, or need several attempts. This can't
+        // drift that way because there's no free-text interpretation step to drift in; it either
+        // finds an unambiguous match or leaves `modelPatch` empty and falls through to the
+        // existing extraction call, unchanged from before.
+        // A step collecting a single PLAIN free-text field (a name, a comment — no enum, no tool
+        // that would need to compose or validate it) has nothing for a model to decide either: the
+        // only thing that could ever go there is exactly what the user just typed. Caught live: a
+        // model asked to extract a bare "Juan" into a single obvious `firstname` field sometimes
+        // just didn't — silently leaving it unset and re-showing the same prompt, for a case with no
+        // real ambiguity to weigh. See `singlePlainTextCollectField`'s doc comment for the (narrow)
+        // conditions this only ever applies under.
+        const deterministicChoice = flowJustSelectedThisTurn
+            ? undefined
+            : (matchSingleEnumChoice(config.stateSchema, step, input.text) ?? matchSinglePlainTextCollect(config.stateSchema, step, input.text));
+        if (deterministicChoice) {
+            modelPatch = deterministicChoice;
+        }
+        else {
+            // The current step's single enum `collect` field already went through every
+            // deterministic matching strategy above (index, exact label, unambiguous partial) and
+            // still found nothing — that's a bounded, mechanically-checkable answer space, so a
+            // model guessing at it afterwards can only do worse: it has no new information the
+            // deterministic pass didn't already have, just more room to hallucinate a plausible-
+            // sounding option the user never actually picked. Caught live: an unrelated word ("pedido")
+            // got the extraction call to silently invent a menu choice, skipping straight past the
+            // step that was supposed to show the menu at all. Excluding the field from the schema —
+            // rather than trusting "Only include fields explicitly provided" to hold — makes it
+            // structurally impossible for this one call to set it.
+            const enumCollectField = singleEnumCollectField(config.stateSchema, step);
+            const extractionSchema = enumCollectField ? modelPatchSchema.omit({ [enumCollectField]: true }) : modelPatchSchema;
+            try {
+                const extraction = await this.options.client.complete({
+                    providerId: this.options.providerId,
+                    model: this.options.model,
+                    messages: [
+                        {
+                            role: "system",
+                            content: `${buildGuidedInstructions(config, step, state, this.options.skills)}\n\n${structuredOutputInstruction(extractionSchema, "StatePatch")}\nOnly include fields the user explicitly provided in their latest message. Omit fields that are unknown, already known, or not mentioned.`
+                        },
+                        ...input.messages,
+                        { role: "user", content: input.text }
+                    ],
+                    ...(input.signal ? { signal: input.signal } : {})
+                });
+                const parsed = parseStructuredOutput(extractionSchema, extraction.text, "StatePatch");
+                if (parsed.ok)
+                    modelPatch = parsed.data;
+                else {
+                    await this.announce(input.onEvent, {
+                        type: "flow.validation.failed",
+                        flowId: flow.id,
+                        sessionId: key,
+                        taskId,
+                        runId,
+                        payload: { stage: "extraction", reason: parsed.error }
+                    });
+                }
+            }
+            catch (error) {
+                await this.announce(input.onEvent, {
                     type: "flow.validation.failed",
                     flowId: flow.id,
                     sessionId: key,
                     taskId,
                     runId,
-                    payload: { stage: "extraction", reason: parsed.error }
+                    payload: { stage: "extraction", reason: error instanceof Error ? error.message : String(error) }
                 });
             }
         }
-        catch (error) {
-            await publishFlowEvent(this.options.events, {
-                type: "flow.validation.failed",
-                flowId: flow.id,
-                sessionId: key,
-                taskId,
-                runId,
-                payload: { stage: "extraction", reason: error instanceof Error ? error.message : String(error) }
-            });
-        }
-        ({ state, requirements, step } = await this.applyPatch(flow, key, taskId, runId, config, state, { set: modelPatch, source: "model" }, requirements));
-        // --- Tool-scoped reply pass: never offers tools beyond the active step's policy ---
-        const effectiveTools = resolveStepTools(this.options.toolRegistrations, step?.tools);
-        const maxRounds = 6;
-        const loopInput = {
-            client: this.options.client,
-            providerId: this.options.providerId,
-            model: this.options.model,
-            messages: [
-                { role: "system", content: buildGuidedInstructions(config, step, state, this.options.skills) },
-                ...input.messages,
-                { role: "user", content: input.text }
-            ],
-            tools: effectiveTools,
-            taskId,
-            runId,
-            maxRounds,
-            onEvent: (event) => this.forwardNativeEvent(flow, key, taskId, runId, event)
-        };
-        const native = this.options.harness ? await this.options.harness.run(loopInput) : await runNativeToolLoop(loopInput);
-        const activeStepId = step?.id;
-        if (activeStepId)
-            stepToolLog[activeStepId] = stepToolLog[activeStepId] ?? [];
+        ({ state, requirements, step } = await this.applyPatch(flow, key, taskId, runId, config, state, { set: modelPatch, source: "model" }, requirements, input.onEvent));
+        // --- Tool-scoped reply pass, auto-chaining through consecutive silent tool-only steps ---
+        // A step whose only job is "run this required tool — nothing to ask the user" (no
+        // `collect`, no `prompt`, has `tools.required`) has no real turn boundary in the source
+        // flow: a Typebot conversion commonly chains e.g. `search-client` straight into
+        // `search-client-addresses` with no user input between them. Stopping the turn there
+        // anyway forces the model to invent SOME reply for a step it has nothing to say about
+        // (seen live: after finding the customer record, "¿qué te gustaría ordenar? 🍽️" instead of
+        // silently continuing to look up their addresses, like the original bot does). So keep
+        // resolving steps within this same turn — invisibly to the caller — until landing on one
+        // that actually needs the user (has `collect` fields or a literal `prompt`), a tool
+        // requests approval, a step fails to advance, or a safety cap is hit. Only the final
+        // step's reply is ever shown; every silent step in between never surfaces its own text.
+        let currentStep = step;
+        let native = { text: "", messages: [], toolCalls: [], toolResults: [], rounds: 0 };
         let pendingApproval = false;
-        for (const toolResult of native.toolResults) {
-            if (toolResult.result.status === "pending_approval")
+        let activeStepId;
+        // Whether the very first step this turn resolves to (before any tool ran) is one the user
+        // was ALREADY sitting on — as opposed to one this turn's own extraction patch just walked
+        // them into (e.g. a single-enum step whose exit condition the deterministic matcher just
+        // satisfied). Matters only for the collect+verbatimTextArg auto-invoke path below: `rawText`
+        // is this turn's message, which was addressed to whatever step was active BEFORE this turn
+        // started — feeding it into a step reached for the first time this same turn (which hasn't
+        // even had a chance to ask its own question yet) would resolve a free-text tool against
+        // words that were never an answer to it. Reproduced live: confirming a previous step with
+        // "si" landed on a fresh date-collection step and immediately fed that same "si" into
+        // `delivery.validate_date`, which understandably found no date in it and left a blank reply.
+        // A brand new session (no prior turn at all — `previousStepId` undefined) is the one
+        // exception: there's no earlier step this message could have been misdirected from, so its
+        // very first step is fair game even on turn one. That exception does NOT hold when this flow
+        // was just entered THIS turn via multi-flow routing (`flowJustSelectedThisTurn`) — there
+        // `input.text` is the phrase that caused the routing, not an answer to this flow's own first
+        // question, same root cause as the `matchSinglePlainTextCollect` guard above.
+        const rawTextBelongsToStep = (previousStepId === undefined && !flowJustSelectedThisTurn) || step?.id === previousStepId;
+        for (let chainLength = 1; chainLength <= MAX_CHAIN_STEPS; chainLength += 1) {
+            activeStepId = currentStep?.id;
+            if (activeStepId)
+                stepToolLog[activeStepId] = stepToolLog[activeStepId] ?? [];
+            const effectiveTools = resolveStepTools(this.options.toolRegistrations, currentStep?.tools);
+            // A step with a literal `prompt` and zero available tools has nothing for the model to
+            // decide: there's no tool call it could make, and the only thing left to say is the
+            // step's own scripted text. Skip the reply-composition call entirely instead of trusting
+            // a model (any model, of any size) to faithfully reproduce that text rather than drift
+            // toward something plausible-sounding but off-script.
+            // A silent tool-only step (no `collect`, no `prompt`, exactly one required tool) has
+            // nothing for a model to decide either: which tool to call isn't ambiguous, and if every
+            // one of that tool's input properties already has a same-named value in `state` (most of
+            // them do — they're typically the previous step's own tool-output fields), the call can
+            // be constructed and executed directly. A model asked to do the exact same thing will
+            // sometimes narrate ("let me check that for you") instead of actually emitting the tool
+            // call, silently stalling the chain — this path can't drift that way because there's no
+            // free-text composition step to drift in. Falls back to the model when an argument can't
+            // be confidently resolved from state, so this only ever fires when it's safe to.
+            const canUseRawTextForAutoInvoke = chainLength > 1 || rawTextBelongsToStep;
+            const autoInvoked = await this.tryAutoInvokeRequiredTool(currentStep, effectiveTools, state, canUseRawTextForAutoInvoke ? input.text : undefined, taskId, runId);
+            native =
+                autoInvoked ??
+                    (currentStep?.prompt && effectiveTools.length === 0
+                        ? { text: interpolatePrompt(currentStep.prompt, state), messages: [], toolCalls: [], toolResults: [], rounds: 0 }
+                        : await this.runReplyPass(config, currentStep, state, input, effectiveTools, taskId, runId, flow, key, canUseRawTextForAutoInvoke));
+            let roundPendingApproval = false;
+            for (const toolResult of native.toolResults) {
+                if (toolResult.result.status === "pending_approval")
+                    roundPendingApproval = true;
+                if (toolResult.result.status === "ok" && activeStepId) {
+                    stepToolLog[activeStepId] = [...(stepToolLog[activeStepId] ?? []), toolResult.tool.id];
+                }
+                const binding = config.tools?.bindings?.[toolResult.tool.id];
+                if (binding) {
+                    const patch = binding.applyResult({ result: toolResult.result, state });
+                    if (patch) {
+                        ({ state, requirements, step: currentStep } = await this.applyPatch(flow, key, taskId, runId, config, state, patch, requirements, input.onEvent));
+                    }
+                }
+            }
+            if (roundPendingApproval)
                 pendingApproval = true;
-            if (toolResult.result.status === "ok" && activeStepId) {
-                stepToolLog[activeStepId] = [...(stepToolLog[activeStepId] ?? []), toolResult.tool.id];
+            // Don't let the resolved step silently skip past one whose requiredBeforeExit tools haven't run yet.
+            let finalStep = resolveActiveStep(config, state);
+            if (activeStepId && finalStep?.id !== activeStepId) {
+                const previousStepDef = config.steps.find((candidate) => candidate.id === activeStepId);
+                const stillMissing = missingRequiredBeforeExitTools(previousStepDef?.tools, stepToolLog[activeStepId] ?? []);
+                if (stillMissing.length)
+                    finalStep = previousStepDef;
             }
-            const binding = config.tools?.bindings?.[toolResult.tool.id];
-            if (binding) {
-                const patch = binding.applyResult({ result: toolResult.result, state });
-                if (patch) {
-                    ({ state, requirements, step } = await this.applyPatch(flow, key, taskId, runId, config, state, patch, requirements));
-                }
+            const stepChanged = Boolean(activeStepId) && finalStep?.id !== activeStepId;
+            // The reply pass's system prompt reflected the step this round STARTED on — not
+            // necessarily this one. A tool call inside this round can advance the flow past that
+            // step before the reply is even composed, but the model was never told what the NEW
+            // step asks, so it improvises. When the step actually changed and the new step has a
+            // literal `prompt`, use that instead of the improvised text — the same model-agnostic
+            // guarantee as the pre-round verbatim path, just applied to a transition that only
+            // became knowable mid-round. Unlike the pre-round check, this doesn't require the new
+            // step to have zero available tools: the user's message this round was about the step
+            // we're LEAVING, not the one we just landed on, so nothing has denied that step's own
+            // tool a fair chance yet — it gets one on the next external turn, once the user actually
+            // responds to what `prompt` is now asking.
+            if (stepChanged && finalStep?.prompt) {
+                native = { ...native, text: interpolatePrompt(finalStep.prompt, state) };
             }
+            await this.announceStepChange(flow, key, activeStepId, finalStep?.id, taskId, runId, input.onEvent);
+            currentStep = finalStep;
+            const isSilentToolOnlyStep = Boolean(currentStep &&
+                (!currentStep.collect || currentStep.collect.length === 0) &&
+                !currentStep.prompt &&
+                (currentStep.tools?.required?.length ?? 0) > 0);
+            if (roundPendingApproval || !stepChanged || !isSilentToolOnlyStep)
+                break;
         }
-        // Don't let the resolved step silently skip past one whose requiredBeforeExit tools haven't run yet.
-        let finalStep = resolveActiveStep(config, state);
-        if (activeStepId && finalStep?.id !== activeStepId) {
-            const previousStepDef = config.steps.find((candidate) => candidate.id === activeStepId);
-            const stillMissing = missingRequiredBeforeExitTools(previousStepDef?.tools, stepToolLog[activeStepId] ?? []);
-            if (stillMissing.length)
-                finalStep = previousStepDef;
-        }
-        step = finalStep;
-        await this.announceStepChange(flow, key, activeStepId, step?.id, taskId, runId);
+        step = currentStep;
+        // Last-resort safety net: an auto-invoked tool that didn't advance the step (no `message`
+        // on its output, or the step's own prompt wasn't already substituted above) should still
+        // never leave the user looking at a blank reply — fall back to the step's own literal
+        // prompt, interpolated against the now-current state, if it has one.
+        const replyText = native.text || (step?.prompt ? interpolatePrompt(step.prompt, state) : native.text);
         requirements = evaluateRequirements(config, state);
         const missingRequirementIds = requirements.filter((requirement) => !requirement.satisfied).map((requirement) => requirement.id);
         const completedRequirementIds = requirements.filter((requirement) => requirement.satisfied).map((requirement) => requirement.id);
@@ -211,7 +336,7 @@ export class GuidedFlowRuntime {
             const mapped = config.mapOutput({ state });
             const validated = config.outputSchema.safeParse(mapped);
             if (!validated.success) {
-                await publishFlowEvent(this.options.events, {
+                await this.announce(input.onEvent, {
                     type: "flow.validation.failed",
                     flowId: flow.id,
                     sessionId: key,
@@ -226,18 +351,18 @@ export class GuidedFlowRuntime {
             status = "completed";
             completedAt = now();
             await this.options.hooks.fire("afterFlowComplete", { flowId: flow.id, sessionId: key, output, context: { taskId, runId } });
-            await publishFlowEvent(this.options.events, { type: "flow.completed", flowId: flow.id, sessionId: key, taskId, runId, payload: { output: output } });
+            await this.announce(input.onEvent, { type: "flow.completed", flowId: flow.id, sessionId: key, taskId, runId, payload: { output: output } });
         }
         else if (pendingApproval) {
             status = "waiting_for_approval";
-            await publishFlowEvent(this.options.events, { type: "flow.waiting_for_approval", flowId: flow.id, sessionId: key, taskId, runId, payload: {} });
+            await this.announce(input.onEvent, { type: "flow.waiting_for_approval", flowId: flow.id, sessionId: key, taskId, runId, payload: {} });
         }
-        else if (native.rounds >= maxRounds && native.toolCalls.length > 0) {
+        else if (native.rounds >= MAX_REPLY_ROUNDS && native.toolCalls.length > 0) {
             status = "waiting_for_tool";
         }
         else {
             status = "waiting_for_user";
-            await publishFlowEvent(this.options.events, { type: "flow.waiting_for_user", flowId: flow.id, sessionId: key, taskId, runId, payload: {} });
+            await this.announce(input.onEvent, { type: "flow.waiting_for_user", flowId: flow.id, sessionId: key, taskId, runId, payload: {} });
         }
         const updated = {
             flowId: flow.id,
@@ -256,7 +381,7 @@ export class GuidedFlowRuntime {
         };
         await this.options.store.saveFlowState(updated);
         return {
-            text: native.text,
+            text: replyText,
             ...(output !== undefined ? { output } : {}),
             state: state,
             flow: {
@@ -272,14 +397,131 @@ export class GuidedFlowRuntime {
             }
         };
     }
-    async applyPatch(flow, key, taskId, runId, config, state, patch, previousRequirements) {
+    /** The model-driven reply pass: composes text and may call the active step's tools. Only reached when a step has no `prompt`, or does but still has tools available (e.g. a validation step, which needs the model to react to a tool result/error dynamically). */
+    async runReplyPass(config, step, state, input, effectiveTools, taskId, runId, flow, key, allowVerbatimTextArg = true) {
+        // `verbatimTextArg` forces whatever the model composes to be overwritten with this turn's
+        // raw text — the right call when the text is actually the user's answer to `step`'s own
+        // question, but wrong the moment `step` was only just reached this same turn (e.g. a "sí"
+        // confirming the PREVIOUS step landed here via the deterministic enum patch, before the
+        // user ever saw this step's own prompt). Forcing it there doesn't just risk a bad guess —
+        // it guarantees one, since whatever the model supplies gets discarded either way. Caught
+        // live: that exact "sí" got forced into `customer.validate_email_2`'s phone argument,
+        // failing validation for a phone number the user never got a chance to type.
+        const verbatimMapping = allowVerbatimTextArg ? step?.tools?.verbatimTextArg : undefined;
+        const loopInput = {
+            client: this.options.client,
+            providerId: this.options.providerId,
+            model: this.options.model,
+            messages: [
+                { role: "system", content: buildGuidedInstructions(config, step, state, this.options.skills) },
+                ...input.messages,
+                { role: "user", content: input.text }
+            ],
+            tools: applyVerbatimTextArgs(effectiveTools, verbatimMapping, input.text),
+            taskId,
+            runId,
+            maxRounds: MAX_REPLY_ROUNDS,
+            onEvent: (event) => this.forwardNativeEvent(flow, key, taskId, runId, event, input.onEvent),
+            ...(input.signal ? { signal: input.signal } : {})
+        };
+        return this.options.harness ? await this.options.harness.run(loopInput) : await runNativeToolLoop(loopInput);
+    }
+    /**
+     * Deterministically calls a step's single applicable tool when its arguments are fully
+     * resolvable without asking a model to decide anything. Covers two shapes:
+     *
+     * 1. A silent tool-only step (no `collect`, exactly one required tool) where every input
+     *    property already resolves to a known value in `state` (matched by property name,
+     *    case-insensitively — the generator's convention of lowercase-flattened field names makes
+     *    this a reliable match in practice).
+     * 2. A `collect` step whose only useful action is resolving the user's free text against a
+     *    dynamic list (an address, a product, a time slot): exactly one tool in `tools.allowed`
+     *    has a `verbatimTextArg` mapping configured. Which tool to call isn't ambiguous and the
+     *    argument that matters most — the user's own words — is already pinned to the raw turn
+     *    text, so there's nothing left for a model to compose either. (Caught live: asked to do
+     *    the exact same thing, a model sometimes narrates — "voy a consultar..." — instead of
+     *    actually emitting the tool call, leaving the user with a blank reply.)
+     *
+     * Returns `undefined` — never partially constructed input — the moment any other required
+     * property can't be confidently resolved, so the caller falls back to the model-driven
+     * `runReplyPass` exactly as before. Bypasses the harness too: this never asks a model
+     * anything, so a custom `ModelHarness` has nothing to intercept here (same reasoning as the
+     * `step.prompt` verbatim path).
+     */
+    async tryAutoInvokeRequiredTool(step, effectiveTools, state, rawText, taskId, runId) {
+        const requiredIds = step?.tools?.required ?? [];
+        const hasCollect = (step?.collect?.length ?? 0) > 0;
+        let toolId;
+        let verbatimArgName;
+        if (!hasCollect && requiredIds.length === 1) {
+            toolId = requiredIds[0];
+        }
+        else if (hasCollect && rawText !== undefined) {
+            const verbatimMapping = step?.tools?.verbatimTextArg;
+            const allowedIds = step?.tools?.allowed ?? [];
+            const verbatimIds = verbatimMapping ? allowedIds.filter((id) => verbatimMapping[id]) : [];
+            const soleVerbatimId = verbatimIds.length === 1 ? verbatimIds[0] : undefined;
+            if (soleVerbatimId) {
+                toolId = soleVerbatimId;
+                verbatimArgName = verbatimMapping?.[soleVerbatimId];
+            }
+        }
+        if (!toolId)
+            return undefined;
+        const registration = effectiveTools.find((candidate) => candidate.tool.id === toolId);
+        if (!registration)
+            return undefined;
+        const schema = registration.tool.inputSchema;
+        const propertyNames = Object.keys(schema?.properties ?? {});
+        const requiredPropertyNames = schema?.required ?? propertyNames;
+        const stateEntries = Object.entries(state);
+        const args = {};
+        for (const propertyName of propertyNames) {
+            // `verbatimArgName` is only ever set above once `rawText !== undefined` was confirmed —
+            // this narrows what TypeScript can't infer across the two functions.
+            if (propertyName === verbatimArgName && rawText !== undefined) {
+                args[propertyName] = rawText;
+                continue;
+            }
+            const value = resolveArgFromState(propertyName, stateEntries);
+            if (value === undefined || value === null || value === "") {
+                if (requiredPropertyNames.includes(propertyName))
+                    return undefined;
+                continue;
+            }
+            // A loosely-typed state field (the generator emits `z.unknown()` for plenty of collected
+            // values) commonly holds a JS type its own tool argument didn't expect — not because
+            // anything drifted, but because the extraction call itself just returns valid JSON for
+            // whatever the user said: "1" comes back as the NUMBER 1, not the string "1", when the
+            // field has no type constraint to anchor it. A tool argument typed `z.string()` then
+            // rejects that number outright. Caught live: `numberOfCilinders` silently failing to
+            // resolve this way left `order.call` invoked with the count missing entirely, and the
+            // real API rejected the whole order with a generic, unhelpful error. Coercing between
+            // closely-related primitives (number/boolean → string, numeric string → number) covers
+            // this safely; anything further off (an object where a string was expected, say) still
+            // bails rather than guessing.
+            const coerced = coerceToJsonSchemaType(value, schema?.properties?.[propertyName]?.type);
+            if (!coerced.ok)
+                return undefined;
+            args[propertyName] = coerced.value;
+        }
+        const result = await registration.handler(args, { taskId, runId, stepId: `auto-chain-${registration.tool.id}-${randomUUID()}` });
+        return {
+            text: extractResultMessage(result),
+            messages: [],
+            toolCalls: [],
+            toolResults: [{ tool: registration.tool, result, toolCallId: `auto-${randomUUID()}` }],
+            rounds: 0
+        };
+    }
+    async applyPatch(flow, key, taskId, runId, config, state, patch, previousRequirements, onEvent) {
         await this.options.hooks.fire("beforeFlowStatePatch", { flowId: flow.id, sessionId: key, patch, context: { taskId, runId } });
         const applied = applyStatePatch(config, state, patch);
         const confirmationResult = applyConfirmationReset(config, applied.state, applied.changedKeys);
         const nextState = confirmationResult.state;
         const changedKeys = confirmationResult.reset && config.confirmation ? [...applied.changedKeys, String(config.confirmation.stateField)] : applied.changedKeys;
         if (changedKeys.length) {
-            await publishFlowEvent(this.options.events, {
+            await this.announce(onEvent, {
                 type: "flow.state.updated",
                 flowId: flow.id,
                 sessionId: key,
@@ -292,31 +534,31 @@ export class GuidedFlowRuntime {
         const requirements = evaluateRequirements(config, nextState);
         const diff = diffRequirements(previousRequirements, requirements);
         for (const id of diff.newlySatisfied) {
-            await publishFlowEvent(this.options.events, { type: "flow.requirement.satisfied", flowId: flow.id, sessionId: key, taskId, runId, payload: { requirementId: id } });
+            await this.announce(onEvent, { type: "flow.requirement.satisfied", flowId: flow.id, sessionId: key, taskId, runId, payload: { requirementId: id } });
         }
         for (const id of diff.newlyInvalidated) {
-            await publishFlowEvent(this.options.events, { type: "flow.requirement.invalidated", flowId: flow.id, sessionId: key, taskId, runId, payload: { requirementId: id } });
+            await this.announce(onEvent, { type: "flow.requirement.invalidated", flowId: flow.id, sessionId: key, taskId, runId, payload: { requirementId: id } });
         }
         return { state: nextState, requirements, step: resolveActiveStep(config, nextState) };
     }
-    async announceStepChange(flow, key, previousStepId, nextStepId, taskId, runId) {
+    async announceStepChange(flow, key, previousStepId, nextStepId, taskId, runId, onEvent) {
         if (previousStepId === nextStepId)
             return;
         if (previousStepId) {
             await this.options.hooks.fire("afterFlowStep", { flowId: flow.id, sessionId: key, stepId: previousStepId, context: { taskId, runId } });
-            await publishFlowEvent(this.options.events, { type: "flow.step.exited", flowId: flow.id, sessionId: key, stepId: previousStepId, taskId, runId, payload: {} });
+            await this.announce(onEvent, { type: "flow.step.exited", flowId: flow.id, sessionId: key, stepId: previousStepId, taskId, runId, payload: {} });
         }
         if (nextStepId) {
             await this.options.hooks.fire("beforeFlowStep", { flowId: flow.id, sessionId: key, stepId: nextStepId, context: { taskId, runId } });
-            await publishFlowEvent(this.options.events, { type: "flow.step.entered", flowId: flow.id, sessionId: key, stepId: nextStepId, taskId, runId, payload: {} });
+            await this.announce(onEvent, { type: "flow.step.entered", flowId: flow.id, sessionId: key, stepId: nextStepId, taskId, runId, payload: {} });
         }
     }
-    forwardNativeEvent(flow, key, taskId, runId, event) {
+    forwardNativeEvent(flow, key, taskId, runId, event, onEvent) {
         if (event.type === "native.tool.started") {
-            void publishFlowEvent(this.options.events, { type: "flow.tool.requested", flowId: flow.id, sessionId: key, taskId, runId, payload: { toolId: event.toolId } });
+            void this.announce(onEvent, { type: "flow.tool.requested", flowId: flow.id, sessionId: key, taskId, runId, payload: { toolId: event.toolId } });
         }
         if (event.type === "native.tool.completed") {
-            void publishFlowEvent(this.options.events, {
+            void this.announce(onEvent, {
                 type: "flow.tool.completed",
                 flowId: flow.id,
                 sessionId: key,
@@ -403,6 +645,266 @@ export class GuidedFlowRuntime {
         return this.options.store.getFlowState(key, flow.id);
     }
 }
+/**
+ * Substitutes `{{fieldName}}` placeholders in a step's literal `prompt` with the live value of
+ * that field in `state` — e.g. a Typebot bubble that's literally `{{addressesListMessage}}`
+ * (a previous tool's own output, meant to be shown to the user verbatim) becomes the real
+ * address list text instead of vanishing or showing raw template syntax. An unresolved or
+ * still-empty field renders as `""` rather than leaking `{{...}}` to the user — this can only
+ * happen if `prompt` is reached before the tool that was supposed to populate it has actually
+ * run, which the `denied`-tools-by-default step policy is what prevents in practice.
+ */
+/**
+ * Best-effort text for an auto-invoked tool's result, so a step that doesn't advance (a failed
+ * free-text match, a validation rejection) doesn't leave the user staring at a blank reply — the
+ * same failure mode `resolveArgFromState`'s auto-invoke path is meant to eliminate, just on the
+ * output side instead of the input side. Purely additive: when the tool's output has no string
+ * `message` field, this returns "" exactly as before, and a later step-change in the same turn
+ * (see the `stepChanged && finalStep?.prompt` override) still takes priority over this text.
+ */
+function extractResultMessage(result) {
+    if (result.status !== "ok")
+        return "";
+    const output = result.output;
+    if (output && typeof output === "object" && !Array.isArray(output) && "message" in output) {
+        const message = output.message;
+        return typeof message === "string" ? message : "";
+    }
+    return "";
+}
+function interpolatePrompt(prompt, state) {
+    return prompt.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (match, field) => {
+        const value = state[field];
+        return value === undefined || value === null ? "" : String(value);
+    });
+}
+/**
+ * Resolves a tool's input property (e.g. `addressId`) against `state`, for
+ * `tryAutoInvokeRequiredTool`. Tries an exact case-insensitive key match first (`customerId` ↔
+ * `customerid`); if that finds nothing, falls back to a state key that ENDS WITH the property
+ * name (`addressId` ↔ `selectedaddressid`) — only when exactly one key qualifies, so it can
+ * never guess between two plausible fields. This second pass matters in practice: generated
+ * state field names are commonly prefixed with what produced them (`selected`, `chosen`,
+ * `validated`...), so a literal match against the tool's own property name often doesn't
+ * exist even though there's exactly one unambiguous field it obviously means. Without it, this
+ * step falls through to asking a model to supply the same argument — which is where a real bug
+ * showed up: the model narrated "voy a consultar los productos..." instead of actually calling
+ * the tool that turn, stalling the flow exactly like the cases this whole mechanism exists to
+ * avoid.
+ */
+function resolveArgFromState(propertyName, stateEntries) {
+    const lowerProperty = propertyName.toLowerCase();
+    const exact = stateEntries.find(([key]) => key.toLowerCase() === lowerProperty);
+    if (exact)
+        return exact[1];
+    const suffixMatches = stateEntries.filter(([key]) => {
+        const lowerKey = key.toLowerCase();
+        return lowerKey.length > lowerProperty.length && lowerKey.endsWith(lowerProperty);
+    });
+    if (suffixMatches.length !== 1)
+        return undefined;
+    const match = suffixMatches[0];
+    return match ? match[1] : undefined;
+}
+/**
+ * Whether `value` is a plausible fit for a JSON Schema `type` keyword ("string", "number",
+ * "integer", "boolean", "array", "object") before it's handed to a tool's own (stricter) Zod
+ * validation. Deliberately permissive when `expectedType` is missing/unrecognized — the caller
+ * only uses this to bail out of an auto-invoke early, never to accept a value it otherwise
+ * wouldn't have.
+ */
+/**
+ * Checks a resolved state value against a tool argument's declared JSON Schema `type`, coercing
+ * between closely-related PRIMITIVES (number/boolean → string, a numeric string → number) rather
+ * than just accepting-or-rejecting — an extraction call returning `1` for a field the user
+ * answered with the free-text "1" is the ordinary case, not a corruption, and a `z.string()`
+ * argument should get `"1"` for it rather than silently losing the whole tool call. Structured
+ * mismatches (an object/array where a primitive was expected, or vice versa) are never coerced —
+ * those really do indicate the wrong value ended up in the wrong field, and this rejects
+ * (`ok: false`) exactly as before so the caller falls back to the model.
+ */
+function coerceToJsonSchemaType(value, expectedType) {
+    switch (expectedType) {
+        case "string":
+            if (typeof value === "string")
+                return { ok: true, value };
+            if (typeof value === "number" || typeof value === "boolean")
+                return { ok: true, value: String(value) };
+            return { ok: false };
+        case "number":
+        case "integer":
+            if (typeof value === "number")
+                return { ok: true, value };
+            if (typeof value === "string" && value.trim() !== "" && !Number.isNaN(Number(value)))
+                return { ok: true, value: Number(value) };
+            return { ok: false };
+        case "boolean":
+            return typeof value === "boolean" ? { ok: true, value } : { ok: false };
+        case "array":
+            return Array.isArray(value) ? { ok: true, value } : { ok: false };
+        case "object":
+            return typeof value === "object" && value !== null && !Array.isArray(value) ? { ok: true, value } : { ok: false };
+        default:
+            return { ok: true, value };
+    }
+}
+/**
+ * Wraps any tool registration named in `mapping` so its handler always receives the current
+ * turn's raw text under the mapped argument name, overwriting whatever the model itself put
+ * there. See `StepToolPolicy.verbatimTextArg` for why: a model composing that argument from
+ * context can invent a plausible-sounding value instead of relaying what the user actually
+ * said, especially for a vague reply — this makes the tool's own "does this resolve to
+ * anything?" check trustworthy, since it's always judging the real input.
+ */
+function applyVerbatimTextArgs(tools, mapping, rawText) {
+    if (!mapping || Object.keys(mapping).length === 0)
+        return tools;
+    return tools.map((registration) => {
+        const argName = mapping[registration.tool.id];
+        if (!argName)
+            return registration;
+        return {
+            ...registration,
+            handler: (rawInput, context) => registration.handler({ ...rawInput, [argName]: rawText }, context)
+        };
+    });
+}
+function unwrapEnum(schema) {
+    if (schema instanceof z.ZodEnum)
+        return schema;
+    if (schema instanceof z.ZodOptional || schema instanceof z.ZodDefault || schema instanceof z.ZodNullable) {
+        return unwrapEnum(schema._def.innerType);
+    }
+    return undefined;
+}
+const COMBINING_DIACRITICS = new RegExp("[\\u0300-\\u036f]", "g");
+const normalizeChoiceText = (value) => value
+    .normalize("NFD")
+    .replace(COMBINING_DIACRITICS, "")
+    .trim()
+    .toLowerCase();
+/**
+ * Matches raw user text against a single enum-typed `collect` field's options — by 1-based
+ * list index (matching the numbered list `step.prompt` renders), exact label (accent- and
+ * case-insensitive), or an unambiguous partial match (exactly one option contains the text or
+ * vice versa, e.g. "quiero el tanque" or a bare "tanque" both resolving "Tanque"). Returns
+ * `undefined` — never a guess — the moment more than one option could plausibly match, or the
+ * step isn't a single-enum choice at all, so the caller always has a safe fallback to the
+ * model-driven extraction call.
+ */
+/**
+ * Identifies a step's single enum-typed `collect` field, if it has exactly one — the same
+ * precondition `matchSingleEnumChoice` requires to even attempt a deterministic match. Exposed
+ * separately so the caller can tell "no deterministic match was possible" apart from "this
+ * field isn't even a bounded-choice one", which matters for deciding whether to trust the
+ * extraction model with it at all (see the call site in `driveFlow`).
+ */
+function singleEnumCollectField(stateSchema, step) {
+    if (step?.collect?.length !== 1)
+        return undefined;
+    const field = String(step.collect[0]);
+    const fieldSchema = stateSchema.shape[field];
+    return fieldSchema && unwrapEnum(fieldSchema) ? field : undefined;
+}
+function matchSingleEnumChoice(stateSchema, step, rawText) {
+    const field = singleEnumCollectField(stateSchema, step);
+    if (!field)
+        return undefined;
+    const fieldSchema = stateSchema.shape[field];
+    const enumSchema = fieldSchema && unwrapEnum(fieldSchema);
+    if (!enumSchema)
+        return undefined;
+    const options = enumSchema.options;
+    const text = normalizeChoiceText(rawText);
+    if (!text)
+        return undefined;
+    const index = Number(text);
+    if (Number.isInteger(index) && index >= 1 && index <= options.length) {
+        return { [field]: options[index - 1] };
+    }
+    const exact = options.filter((option) => normalizeChoiceText(option) === text);
+    if (exact.length === 1)
+        return { [field]: exact[0] };
+    const partial = options.filter((option) => {
+        const normalizedOption = normalizeChoiceText(option);
+        return normalizedOption.includes(text) || text.includes(normalizedOption);
+    });
+    if (partial.length === 1)
+        return { [field]: partial[0] };
+    // Common Spanish yes/no colloquialisms ("sip", "va", "nel"...) share no substring with a
+    // label like "Sí es correcto" or "Continuar" — the checks above miss them entirely, which
+    // regressed a real confirm step live: "sip" stopped resolving "Sí es correcto" once the
+    // extraction call was barred from guessing this field at all (see the enum-field exclusion
+    // below), leaving affirmations that don't literally overlap with the option text with no path
+    // to resolve short of a second try. This only fires when exactly one option's own wording is
+    // recognizably yes-flavored (or no-flavored) and the other isn't — never for option pairs like
+    // "Elegir de la lista" / "Agregar domicilio" that aren't a yes/no choice in the first place.
+    const polarityMatch = matchYesNoColloquialism(options, text);
+    if (polarityMatch)
+        return { [field]: polarityMatch };
+    return undefined;
+}
+const AFFIRMATIVE_OPTION_WORDS = ["si", "correcto", "confirmar", "confirmo", "continuar", "aceptar", "acepto"];
+const NEGATIVE_OPTION_WORDS = ["no", "corregir", "cancelar", "incorrecto", "rechazar", "cambiar"];
+const AFFIRMATIVE_SYNONYMS = new Set(["si", "sip", "sisas", "simon", "claro", "va", "dale", "ok", "okay", "correcto", "afirmativo"]);
+const NEGATIVE_SYNONYMS = new Set(["no", "nel", "nop", "negativo", "paranada", "nones"]);
+function optionPolarity(normalizedOption) {
+    const isAffirmative = AFFIRMATIVE_OPTION_WORDS.some((word) => normalizedOption.includes(word));
+    const isNegative = NEGATIVE_OPTION_WORDS.some((word) => normalizedOption.includes(word));
+    if (isAffirmative && !isNegative)
+        return "yes";
+    if (isNegative && !isAffirmative)
+        return "no";
+    return undefined;
+}
+function matchYesNoColloquialism(options, text) {
+    const textPolarity = AFFIRMATIVE_SYNONYMS.has(text) ? "yes" : NEGATIVE_SYNONYMS.has(text) ? "no" : undefined;
+    if (!textPolarity)
+        return undefined;
+    const matches = options.filter((option) => optionPolarity(normalizeChoiceText(option)) === textPolarity);
+    return matches.length === 1 ? matches[0] : undefined;
+}
+/**
+ * A step's single `collect` field qualifies for verbatim capture — the raw turn text becomes
+ * its value with no model involved — only under conditions narrow enough that there's nothing
+ * left to decide:
+ * - Exactly one `collect` field (a multi-field step genuinely needs the model to work out which
+ *   part of the text answers which still-open question).
+ * - Not an enum (that's `matchSingleEnumChoice`'s job — a bounded answer space needs matching,
+ *   not verbatim capture).
+ * - The step has no `allowed`/`required` tools at all — if a tool exists, an argument might need
+ *   real composition or validation (that's what `verbatimTextArg` + the tool's own logic are
+ *   for); this only covers steps whose entire job is "remember exactly what they typed."
+ */
+function isPlainTextSchema(schema) {
+    if (schema instanceof z.ZodOptional || schema instanceof z.ZodDefault || schema instanceof z.ZodNullable) {
+        return isPlainTextSchema(schema._def.innerType);
+    }
+    // Deliberately narrow: booleans/numbers/objects/arrays need real parsing (or come from a
+    // confirmation step, a derived value, a tool result) — verbatim raw text would either fail
+    // that field's own validation or silently coerce into something the user never intended.
+    // The generator's convention for free-text fields is `z.unknown()`; `z.string()`/`z.any()`
+    // cover the rest of what a plain "remember what they typed" field could reasonably be.
+    return schema instanceof z.ZodString || schema instanceof z.ZodUnknown || schema instanceof z.ZodAny;
+}
+function singlePlainTextCollectField(stateSchema, step) {
+    if (step?.collect?.length !== 1)
+        return undefined;
+    if ((step.tools?.allowed?.length ?? 0) > 0 || (step.tools?.required?.length ?? 0) > 0)
+        return undefined;
+    const field = String(step.collect[0]);
+    const fieldSchema = stateSchema.shape[field];
+    if (!fieldSchema || unwrapEnum(fieldSchema) || !isPlainTextSchema(fieldSchema))
+        return undefined;
+    return field;
+}
+function matchSinglePlainTextCollect(stateSchema, step, rawText) {
+    const field = singlePlainTextCollectField(stateSchema, step);
+    if (!field)
+        return undefined;
+    const text = rawText.trim();
+    return text ? { [field]: text } : undefined;
+}
 function buildGuidedInstructions(config, step, state, skills) {
     const known = Object.entries(state)
         .filter(([, value]) => value !== undefined && value !== null && value !== "")
@@ -411,11 +913,28 @@ function buildGuidedInstructions(config, step, state, skills) {
     const stepSkills = (step?.skills ?? [])
         .map((id) => skills.find((skill) => skill.id === id))
         .filter((skill) => Boolean(skill));
+    // A step with nothing to collect and a required tool is a pure backend step — there is
+    // nothing to narrate or confirm yet, only a tool to call. Left to its own judgment, a model
+    // will sometimes announce "let me check that for you" as plain text instead of actually
+    // emitting the tool call in that same response, which silently stalls the auto-chain in
+    // `driveFlow` (it only keeps chaining once the tool has actually run). State this as an
+    // imperative instruction rather than leaving it implicit in `instructions`.
+    const requiredTools = step?.tools?.required ?? [];
+    const mustCallNow = !step?.collect?.length && requiredTools.length > 0
+        ? `This step has exactly one job: call ${requiredTools.map((id) => `"${String(id)}"`).join(", ")} right now, in this response. Do not narrate, explain, or say you're about to do it — call the tool immediately, with no preceding text.`
+        : "";
     const lines = [
         `You are guiding the user through the "${config.name}" flow. Goal: ${config.goal}`,
         known.length ? `Known so far: ${known.join(", ")}.` : "Nothing is known about the user yet.",
         missing.length ? `Still missing: ${missing.join(", ")}. Ask only for what's missing — never re-ask for known fields.` : "",
-        step?.instructions ? `Current step instructions: ${step.instructions}` : "",
+        // `instructions` can carry the same `{{field}}` placeholders `prompt` does — e.g. an error
+        // message field that's only meaningful after a failed validation. Left un-interpolated, a
+        // model composing a reply from these instructions has been observed to just echo the raw
+        // `{{errormessagephone}}` syntax back to the user verbatim instead of treating it as
+        // internal templating. `prompt` gets this via `interpolatePrompt` at render time; do the
+        // same here since `instructions` also ends up as literal text in front of the model.
+        step?.instructions ? `Current step instructions: ${interpolatePrompt(step.instructions, state)}` : "",
+        mustCallNow,
         ...stepSkills.map((skill) => `Skill "${skill.id}": ${skill.instructions}`)
     ];
     return lines.filter(Boolean).join("\n");