@kuralle-agents/core 0.3.15 → 0.3.17

package/dist/flow/choiceMatch.d.ts

@@ -0,0 +1,17 @@
+import type { ModelMessage } from 'ai';
+import { z } from 'zod';
+import type { DecideNode } from '../types/flow.js';
+import type { ChoiceOption } from '../types/selection.js';
+import type { RunContext } from '../types/run-context.js';
+/** Reserved enum member: model declines to pick a listed choice (→ author stay/unmatched). */
+export declare const CHOICE_NONE = "__none";
+export declare function isConstrainedChoiceEnumSchema(schema: unknown): boolean;
+export declare function isChoiceFieldSchema(schema: unknown): schema is z.ZodObject<{
+    choice: z.ZodString;
+}>;
+export declare function buildChoiceEnumSchema(choices: ChoiceOption[]): z.ZodObject<{
+    choice: z.ZodEnum<[string, ...string[]]>;
+}>;
+export declare function latestUserMessageText(messages: ModelMessage[]): string | undefined;
+export declare function matchChoiceFromInput(input: string, choices: ChoiceOption[]): string | undefined;
+export declare function resolveStructuredDecide(node: DecideNode, ctx: RunContext, system: string): Promise<unknown>;

package/dist/flow/choiceMatch.js

@@ -0,0 +1,119 @@
+import { generateObject } from 'ai';
+import { z } from 'zod';
+/** Reserved enum member: model declines to pick a listed choice (→ author stay/unmatched). */
+export const CHOICE_NONE = '__none';
+function normalize(raw) {
+    return raw.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+function keywordTerms(text) {
+    return normalize(text)
+        .split(/[^a-z0-9]+/)
+        .filter((term) => term.length > 4);
+}
+export function isConstrainedChoiceEnumSchema(schema) {
+    if (!(schema instanceof z.ZodObject)) {
+        return false;
+    }
+    return schema.shape.choice instanceof z.ZodEnum;
+}
+export function isChoiceFieldSchema(schema) {
+    if (!(schema instanceof z.ZodObject)) {
+        return false;
+    }
+    const keys = Object.keys(schema.shape);
+    if (keys.length !== 1 || keys[0] !== 'choice') {
+        return false;
+    }
+    return schema.shape.choice instanceof z.ZodString;
+}
+export function buildChoiceEnumSchema(choices) {
+    const ids = choices.map((c) => c.id);
+    if (ids.length === 0) {
+        return z.object({ choice: z.enum([CHOICE_NONE]) });
+    }
+    const members = [ids[0], ...ids.slice(1), CHOICE_NONE];
+    return z.object({ choice: z.enum(members) });
+}
+export function latestUserMessageText(messages) {
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const message = messages[i];
+        if (message?.role === 'user') {
+            if (typeof message.content === 'string') {
+                return message.content;
+            }
+            if (Array.isArray(message.content)) {
+                const text = message.content
+                    .filter((part) => part.type === 'text')
+                    .map((part) => part.text)
+                    .join('');
+                if (text) {
+                    return text;
+                }
+            }
+        }
+    }
+    return undefined;
+}
+export function matchChoiceFromInput(input, choices) {
+    const normalized = normalize(input);
+    if (!normalized) {
+        return undefined;
+    }
+    const idMatches = choices.filter((c) => normalize(c.id) === normalized).map((c) => c.id);
+    if (idMatches.length === 1) {
+        return idMatches[0];
+    }
+    if (idMatches.length > 1) {
+        return undefined;
+    }
+    const labelMatches = choices.filter((c) => normalize(c.label) === normalized).map((c) => c.id);
+    if (labelMatches.length === 1) {
+        return labelMatches[0];
+    }
+    if (labelMatches.length > 1) {
+        return undefined;
+    }
+    const keywordMatches = [];
+    for (const choice of choices) {
+        const terms = keywordTerms(choice.label);
+        if (terms.length > 0 && terms.some((term) => normalized.includes(term))) {
+            keywordMatches.push(choice.id);
+        }
+    }
+    if (keywordMatches.length === 1) {
+        return keywordMatches[0];
+    }
+    return undefined;
+}
+export async function resolveStructuredDecide(node, ctx, system) {
+    const schema = node.schema;
+    const useConstrainedChoices = (node.choices?.length ?? 0) > 0 && isChoiceFieldSchema(schema);
+    if (!useConstrainedChoices) {
+        const { object } = await generateObject({
+            model: ctx.controlModel,
+            schema,
+            system,
+            messages: ctx.runState.messages,
+            temperature: 0,
+            abortSignal: ctx.abortSignal,
+        });
+        return object;
+    }
+    const input = latestUserMessageText(ctx.runState.messages);
+    if (input) {
+        const matched = matchChoiceFromInput(input, node.choices);
+        if (matched) {
+            return { choice: matched };
+        }
+    }
+    const choiceSchema = buildChoiceEnumSchema(node.choices);
+    const { object } = await generateObject({
+        model: ctx.controlModel,
+        schema: choiceSchema,
+        system,
+        messages: ctx.runState.messages,
+        temperature: 0,
+        abortSignal: ctx.abortSignal,
+    });
+    return object;
+}

package/dist/flow/collectDigression.d.ts

@@ -0,0 +1,31 @@
+import type { AgentConfig } from '../types/agentConfig.js';
+import type { ChannelDriver } from '../types/channel.js';
+import type { CollectNode } from '../types/flow.js';
+import type { RunContext } from '../types/run-context.js';
+import type { RunState } from '../runtime/durable/types.js';
+import type { NormalizedTransition } from './normalizeTransition.js';
+import { selectHostTarget } from '../runtime/select.js';
+export interface FlowPark {
+    flow: string;
+    node: string;
+}
+export declare function getFlowPark(state: Record<string, unknown>): FlowPark | undefined;
+export declare function looksLikeOffScriptQuestion(input: string): boolean;
+export interface CollectDigressionOptions {
+    agent: AgentConfig;
+    node: CollectNode;
+    activeFlowName: string;
+    run: RunState;
+    driver: ChannelDriver;
+    ctx: RunContext;
+    select?: typeof selectHostTarget;
+}
+export type CollectDigressionResult = {
+    kind: 'transition';
+    transition: NormalizedTransition;
+} | {
+    kind: 'answeredThenResume';
+} | {
+    kind: 'none';
+};
+export declare function runCollectDigression(options: CollectDigressionOptions): Promise<CollectDigressionResult>;

package/dist/flow/collectDigression.js

@@ -0,0 +1,99 @@
+import { resolveReplyNode } from './nodeBuilders.js';
+import { selectHostTarget } from '../runtime/select.js';
+const FLOW_PARK_KEY = '__flowPark';
+export function getFlowPark(state) {
+    const raw = state[FLOW_PARK_KEY];
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return undefined;
+    }
+    const flow = raw.flow;
+    const node = raw.node;
+    if (typeof flow === 'string' && typeof node === 'string') {
+        return { flow, node };
+    }
+    return undefined;
+}
+function setFlowPark(state, park) {
+    state[FLOW_PARK_KEY] = park;
+}
+function appendAssistantMessage(run, text) {
+    if (!text.trim()) {
+        return;
+    }
+    const message = { role: 'assistant', content: text };
+    run.messages = [...run.messages, message];
+}
+export function looksLikeOffScriptQuestion(input) {
+    const trimmed = input.trim();
+    if (!trimmed) {
+        return false;
+    }
+    if (trimmed.includes('?')) {
+        return true;
+    }
+    return /^(what|how|why|when|where|who|can|could|do|does|is|are|will|would)\b/i.test(trimmed);
+}
+export async function runCollectDigression(options) {
+    const { agent, node, activeFlowName, run, driver, ctx } = options;
+    const select = options.select ?? selectHostTarget;
+    const offScriptInput = peekLatestUserMessage(run);
+    if (!offScriptInput) {
+        return { kind: 'none' };
+    }
+    const selection = await select({
+        agent,
+        run,
+        model: agent.routing?.model ?? ctx.controlModel,
+        alwaysRoute: agent.routing?.always === true,
+        excludeFlowNames: [activeFlowName],
+    });
+    if (selection.kind === 'route') {
+        return {
+            kind: 'transition',
+            transition: { kind: 'handoff', to: selection.agentId, reason: selection.reason },
+        };
+    }
+    if (selection.kind === 'enterFlow') {
+        setFlowPark(run.state, { flow: activeFlowName, node: node.id });
+        return {
+            kind: 'transition',
+            transition: {
+                kind: 'switchFlow',
+                flow: selection.flow,
+                park: { flow: activeFlowName, node: node.id },
+            },
+        };
+    }
+    if (!looksLikeOffScriptQuestion(offScriptInput)) {
+        return { kind: 'none' };
+    }
+    const replyNode = {
+        kind: 'reply',
+        id: `${node.id}__digression`,
+        instructions: ctx.baseInstructions ??
+            'Answer the user helpfully and concisely. Do not mention internal routing or flows.',
+        tools: ctx.globalTools,
+    };
+    const turn = await driver.runAgentTurn(resolveReplyNode(replyNode, run.state, { freeConversation: true }), ctx);
+    if (turn.text.trim()) {
+        ctx.emit({ type: 'text-delta', text: turn.text });
+        ctx.emit({ type: 'turn-end' });
+        appendAssistantMessage(run, turn.text);
+    }
+    if (turn.control?.type === 'handoff') {
+        return {
+            kind: 'transition',
+            transition: { kind: 'handoff', to: turn.control.target, reason: turn.control.reason },
+        };
+    }
+    return { kind: 'answeredThenResume' };
+}
+function peekLatestUserMessage(run) {
+    for (let i = run.messages.length - 1; i >= 0; i -= 1) {
+        const message = run.messages[i];
+        if (message?.role === 'user' && typeof message.content === 'string') {
+            return message.content;
+        }
+    }
+    return undefined;
+}

package/dist/flow/collectUntilComplete.d.ts

@@ -1,6 +1,11 @@
+import type { AgentConfig } from '../types/agentConfig.js';
 import type { ChannelDriver } from '../types/channel.js';
 import type { CollectNode } from '../types/flow.js';
 import type { RunContext } from '../types/run-context.js';
 import type { RunState } from '../runtime/durable/types.js';
 import type { NormalizedTransition } from './normalizeTransition.js';
-export declare function collectUntilComplete(node: CollectNode, run: RunState, driver: ChannelDriver, ctx: RunContext): Promise<NormalizedTransition>;
+export declare function collectUntilComplete(node: CollectNode, run: RunState, driver: ChannelDriver, ctx: RunContext, options?: {
+    agent?: AgentConfig;
+    activeFlowName?: string;
+}): Promise<NormalizedTransition>;
+export declare function emitCollectAsk(node: CollectNode, run: RunState, ctx: RunContext): void;

package/dist/flow/collectUntilComplete.js

@@ -1,3 +1,4 @@
+import { runCollectDigression } from './collectDigression.js';
 import { hasPendingUserInput } from '../runtime/channels/inputBuffer.js';
 import { resolveCollectExtractionNode } from './nodeBuilders.js';
 import { computeMissingFields, createExtractionSubmitTool, getCollectData, incrementCollectTurns, emitExtractionTelemetry, mergeTurnExtraction, projectCollectData, schemaSatisfied, } from './extraction.js';
@@ -13,7 +14,7 @@ function appendUserMessage(run, input) {
     const message = { role: 'user', content: input };
     run.messages = [...run.messages, message];
 }
-export async function collectUntilComplete(node, run, driver, ctx) {
+export async function collectUntilComplete(node, run, driver, ctx, options) {
     for (;;) {
         if (schemaSatisfied(node, run.state)) {
             const data = projectCollectData(node, run.state);
@@ -44,11 +45,11 @@ export async function collectUntilComplete(node, run, driver, ctx) {
             const data = projectCollectData(node, run.state);
             return normalizeTransition(await node.onComplete(data, run.state));
         }
-        const missing = computeMissingFields(node, getCollectData(run.state, node.id));
-        const submitTool = createExtractionSubmitTool(node, missing, {
+        const missingBefore = computeMissingFields(node, getCollectData(run.state, node.id));
+        const submitTool = createExtractionSubmitTool(node, missingBefore, {
             userMessage: peekLatestUserMessage(run),
         });
-        const resolved = resolveCollectExtractionNode(node, missing, run.state, submitTool);
+        const resolved = resolveCollectExtractionNode(node, missingBefore, run.state, submitTool);
         // Non-speaking extraction: the model's prose is DISCARDED (never emitted or
         // appended), so a collect turn cannot author narration that contradicts flow
         // state. Falls back to runAgentTurn for drivers without runExtraction; its
@@ -58,6 +59,28 @@ export async function collectUntilComplete(node, run, driver, ctx) {
             ? driver.runExtraction(resolved, ctx)
             : driver.runAgentTurn(resolved, ctx));
         mergeExtractionFromTurn(node, run, turn, ctx);
+        const missingAfter = computeMissingFields(node, getCollectData(run.state, node.id));
+        const advanced = missingAfter.length < missingBefore.length || schemaSatisfied(node, run.state);
+        if (!advanced &&
+            ctx.outOfBandControl &&
+            options?.agent &&
+            options.activeFlowName) {
+            const digression = await runCollectDigression({
+                agent: options.agent,
+                node,
+                activeFlowName: options.activeFlowName,
+                run,
+                driver,
+                ctx,
+            });
+            if (digression.kind === 'transition') {
+                return digression.transition;
+            }
+            if (digression.kind === 'answeredThenResume') {
+                emitCollectAsk(node, run, ctx);
+                return { kind: 'stay' };
+            }
+        }
     }
 }
 function humanizeField(field) {
@@ -82,7 +105,7 @@ function renderCollectAsk(node, missing, state) {
     }
     return 'Could you tell me a little more?';
 }
-function emitCollectAsk(node, run, ctx) {
+export function emitCollectAsk(node, run, ctx) {
     const missing = computeMissingFields(node, getCollectData(run.state, node.id));
     const text = renderCollectAsk(node, missing, run.state);
     if (!text.trim()) {

package/dist/flow/normalizeTransition.d.ts

@@ -1,4 +1,5 @@
-import type { FlowNode, Transition } from '../types/flow.js';
+import type { Flow, FlowNode, Transition } from '../types/flow.js';
+import type { FlowPark } from './collectDigression.js';
 export type NormalizedTransition = {
     kind: 'goto';
     node: FlowNode;
@@ -15,6 +16,10 @@ export type NormalizedTransition = {
     reason: string;
 } | {
     kind: 'stay';
+} | {
+    kind: 'switchFlow';
+    flow: Flow;
+    park: FlowPark;
 };
 export declare function resolveNodeRef(ref: FlowNode | (() => FlowNode)): FlowNode;
 export declare function normalizeTransition(transition: Transition): NormalizedTransition;

package/dist/flow/runFlow.d.ts

@@ -1,3 +1,4 @@
+import type { AgentConfig } from '../types/agentConfig.js';
 import type { ChannelDriver } from '../types/channel.js';
 import type { Flow } from '../types/flow.js';
 import type { RunContext } from '../types/run-context.js';
@@ -15,4 +16,4 @@ export type FlowResult = {
 export declare class FlowOscillationError extends Error {
     constructor(from: string, to: string);
 }
-export declare function runFlow(flow: Flow, run: RunState, driver: ChannelDriver, ctx: RunContext): Promise<FlowResult>;
+export declare function runFlow(flow: Flow, run: RunState, driver: ChannelDriver, ctx: RunContext, agent?: AgentConfig): Promise<FlowResult>;

package/dist/flow/runFlow.js

@@ -1,3 +1,4 @@
+import { getFlowPark } from './collectDigression.js';
 import { parseConfirmation } from './confirmParse.js';
 import { hasPendingUserInput } from '../runtime/channels/inputBuffer.js';
 import { collectUntilComplete } from './collectUntilComplete.js';
@@ -87,12 +88,15 @@ function appendAssistantMessage(run, text) {
     const message = { role: 'assistant', content: text };
     run.messages = [...run.messages, message];
 }
-async function dispatchNode(node, run, driver, ctx) {
+async function dispatchNode(node, run, driver, ctx, agent, flow) {
     if (isActionNode(node)) {
         return normalizeTransition(await node.run(run.state, toActionContext(ctx)));
     }
     if (isCollectNode(node)) {
-        return collectUntilComplete(node, run, driver, ctx);
+        return collectUntilComplete(node, run, driver, ctx, {
+            agent,
+            activeFlowName: flow.name,
+        });
     }
     if (isDecideNode(node)) {
         if (node.confirmGate) {
@@ -139,7 +143,7 @@ async function dispatchNode(node, run, driver, ctx) {
             if (decision.kind === 'redispatch') {
                 const signal = await driver.awaitUser(ctx);
                 appendUserMessage(run, signal.input);
-                return dispatchNode(node, run, driver, ctx);
+                return dispatchNode(node, run, driver, ctx, agent, flow);
             }
             appendAssistantMessage(run, turn.text);
             if (decision.kind === 'transition') {
@@ -151,7 +155,7 @@ async function dispatchNode(node, run, driver, ctx) {
         if (turn.interrupted) {
             const signal = await driver.awaitUser(ctx);
             appendUserMessage(run, signal.input);
-            return dispatchNode(node, run, driver, ctx);
+            return dispatchNode(node, run, driver, ctx, agent, flow);
         }
         if (turn.control?.type === 'handoff') {
             return { kind: 'handoff', to: turn.control.target, reason: turn.control.reason };
@@ -172,7 +176,7 @@ async function dispatchNode(node, run, driver, ctx) {
     }
     throw new Error(`Unknown node kind: ${node.kind}`);
 }
-export async function runFlow(flow, run, driver, ctx) {
+export async function runFlow(flow, run, driver, ctx, agent) {
     const registry = buildNodeRegistry(flow);
     const startNode = resolveStartNode(flow);
     const initialNodeId = run.activeNode ?? startNode.id;
@@ -192,7 +196,7 @@ export async function runFlow(flow, run, driver, ctx) {
     for (;;) {
         let transition;
         try {
-            transition = await dispatchNode(node, run, driver, ctx);
+            transition = await dispatchNode(node, run, driver, ctx, agent, flow);
         }
         catch (error) {
             if (error instanceof SuspendError || error instanceof ToolApprovalDeniedError) {
@@ -200,9 +204,27 @@ export async function runFlow(flow, run, driver, ctx) {
             }
             const message = error instanceof Error ? error.message : String(error);
             ctx.emit({ type: 'error', error: message });
-            return degradeFlowError(flow, registry, run, driver, ctx, dispatchNode);
+            return degradeFlowError(flow, registry, run, driver, ctx, (n, r, d, c) => dispatchNode(n, r, d, c, agent, flow));
+        }
+        if (transition.kind === 'switchFlow') {
+            run.activeFlow = transition.flow.name;
+            run.activeNode = undefined;
+            await ctx.runStore.putRunState(run);
+            return runFlow(transition.flow, run, driver, ctx, agent);
         }
         if (transition.kind === 'end') {
+            const park = getFlowPark(run.state);
+            if (park && agent) {
+                delete run.state.__flowPark;
+                const parkedFlow = agent.flows?.find((candidate) => candidate.name === park.flow);
+                if (parkedFlow) {
+                    run.activeFlow = park.flow;
+                    run.activeNode = park.node;
+                    await ctx.runStore.putRunState(run);
+                    ctx.emit({ type: 'flow-end', flow: flow.name, reason: transition.reason });
+                    return runFlow(parkedFlow, run, driver, ctx, agent);
+                }
+            }
             ctx.emit({ type: 'flow-end', flow: flow.name, reason: transition.reason });
             return { kind: 'ended', reason: transition.reason };
         }

package/dist/runtime/channels/TextDriver.js

@@ -1,4 +1,4 @@
-import { streamText, generateObject } from 'ai';
+import { streamText } from 'ai';
 import { buildNodePrompt, resolveInstructions, composeSystem } from '../../flow/nodeBuilders.js';
 import { buildToolSet } from '../../tools/effect/index.js';
 import { executeModelToolCall, toolResultMessage } from './executeModelTool.js';
@@ -8,6 +8,7 @@ import { applyPreTurnPolicies, applyPostTurnPolicies } from '../policies/agentTu
 import { resolveMaxSteps } from '../policies/limits.js';
 import { appendGatherBlocks, resolveNodeGatherScope, runGatherPhase } from '../grounding/index.js';
 import { isFlowTransitionControlTool } from '../../flow/flowControlTools.js';
+import { resolveStructuredDecide } from '../../flow/choiceMatch.js';
 export class TextDriver {
     toolDefs;
     maxSteps;
@@ -113,26 +114,8 @@ export class TextDriver {
         return runSilentExtraction(node, ctx, ctx.controlModel, resolveMaxSteps(ctx.limits, this.maxSteps));
     }
     async runStructured(node, ctx) {
-        const base = composeSystem(ctx.baseInstructions, resolveInstructions(node.instructions, ctx.runState.state), ctx.runState.state);
-        const schema = node.schema;
-        // When the node offers choices (e.g. via withChoices), constrain the model
-        // to return exactly one option id. Otherwise an unconstrained string schema
-        // lets the model reply with free-form prose that `decide()` can't match,
-        // stalling the flow at every interactive node.
-        const system = node.choices?.length
-            ? `${base}\n\nYou MUST pick exactly ONE option by its id. Valid ids: ${node.choices
-                .map((c) => c.id)
-                .join(', ')}. Respond with only the chosen id, nothing else.`
-            : base;
-        const { object } = await generateObject({
-            model: ctx.controlModel,
-            schema,
-            system,
-            messages: ctx.runState.messages,
-            temperature: 0,
-            abortSignal: ctx.abortSignal,
-        });
-        return object;
+        const system = composeSystem(ctx.baseInstructions, resolveInstructions(node.instructions, ctx.runState.state), ctx.runState.state);
+        return resolveStructuredDecide(node, ctx, system);
     }
     async awaitUser(ctx) {
         const input = consumePendingUserInput(ctx.session);

package/dist/runtime/channels/VoiceDriver.js

@@ -1,5 +1,5 @@
-import { generateObject } from 'ai';
 import { runSilentExtraction } from './extractionTurn.js';
+import { resolveStructuredDecide } from '../../flow/choiceMatch.js';
 import { buildNodePrompt, resolveInstructions, composeSystem } from '../../flow/nodeBuilders.js';
 import { executeModelToolCall } from './executeModelTool.js';
 import { applyPreTurnPolicies, applyPostTurnPolicies } from '../policies/agentTurn.js';
@@ -65,24 +65,8 @@ export class VoiceDriver {
         return out;
     }
     async runStructured(node, ctx) {
-        const base = composeSystem(ctx.baseInstructions, resolveInstructions(node.instructions, ctx.runState.state), ctx.runState.state);
-        const schema = node.schema;
-        // Parity with TextDriver: when the node offers choices, constrain the model
-        // to a single option id so an unconstrained string can't stall the decide.
-        const system = node.choices?.length
-            ? `${base}\n\nYou MUST pick exactly ONE option by its id. Valid ids: ${node.choices
-                .map((c) => c.id)
-                .join(', ')}. Respond with only the chosen id, nothing else.`
-            : base;
-        const { object } = await generateObject({
-            model: ctx.controlModel,
-            schema,
-            system,
-            messages: ctx.runState.messages,
-            temperature: 0,
-            abortSignal: ctx.abortSignal,
-        });
-        return object;
+        const system = composeSystem(ctx.baseInstructions, resolveInstructions(node.instructions, ctx.runState.state), ctx.runState.state);
+        return resolveStructuredDecide(node, ctx, system);
     }
     // Non-speaking collect extraction: uses the shared text-model extraction path
     // rather than the realtime audio provider, so the agent never SPEAKS during

package/dist/runtime/hostLoop.js

@@ -14,7 +14,7 @@ export async function hostLoop(options) {
             if (!flow) {
                 throw new Error(`Active flow "${run.activeFlow}" not found on agent "${agent.id}"`);
             }
-            return await runActiveFlow(flow, run, driver, ctx);
+            return await runActiveFlow(flow, run, driver, ctx, agent);
         }
         const alwaysRoute = agent.routing?.always === true;
         if (shouldRunHostSelector(agent, run.activeFlow, alwaysRoute)) {
@@ -25,7 +25,7 @@ export async function hostLoop(options) {
                 alwaysRoute,
             });
             if (selection.kind === 'enterFlow') {
-                return await runActiveFlow(selection.flow, run, driver, ctx);
+                return await runActiveFlow(selection.flow, run, driver, ctx, agent);
             }
             if (selection.kind === 'route') {
                 ctx.emit({ type: 'handoff', targetAgent: selection.agentId, reason: selection.reason });
@@ -45,10 +45,10 @@ export async function hostLoop(options) {
         throw error;
     }
 }
-async function runActiveFlow(flow, run, driver, ctx) {
+async function runActiveFlow(flow, run, driver, ctx, agent) {
     incrementTurnCount(run);
     assertWithinTurnLimit(run, ctx.limits);
-    const result = await runFlow(flow, run, driver, ctx);
+    const result = await runFlow(flow, run, driver, ctx, agent);
     if (result.kind === 'handoff') {
         return { kind: 'handoff', to: result.to, reason: result.reason };
     }

package/dist/runtime/select.d.ts

@@ -17,5 +17,7 @@ export interface SelectHostOptions {
     run: RunState;
     model: LanguageModel;
     alwaysRoute?: boolean;
+    /** Flow names to exclude from enterFlow (e.g. the active flow during in-flow digression). */
+    excludeFlowNames?: string[];
 }
 export declare function selectHostTarget(options: SelectHostOptions): Promise<HostSelection>;

package/dist/runtime/select.js

@@ -19,11 +19,19 @@ export async function selectHostTarget(options) {
     }
     const completed = run.state.__completedFlows;
     const completedFlows = Array.isArray(completed) ? completed : [];
-    const availableFlows = flows.filter((flow) => !completedFlows.includes(flow.name));
+    const excluded = new Set(options.excludeFlowNames ?? []);
+    const availableFlows = flows.filter((flow) => !completedFlows.includes(flow.name) && !excluded.has(flow.name));
     const agentRoutes = routes.filter((route) => route.agent);
+    if (availableFlows.length === 0 && agentRoutes.length === 0) {
+        return { kind: 'keep' };
+    }
     if (availableFlows.length === 1 && agentRoutes.length === 0) {
         return { kind: 'enterFlow', flow: availableFlows[0] };
     }
+    const deterministic = deterministicRouteMatch(latestUser, routes, availableFlows);
+    if (deterministic) {
+        return deterministic;
+    }
     const flowLines = availableFlows
         .map((flow) => `- flow "${flow.name}": ${flow.description}`)
         .join('\n');
@@ -72,6 +80,32 @@ export async function selectHostTarget(options) {
     }
     return keywordRouteFallback(latestUser, routes, availableFlows);
 }
+function deterministicRouteMatch(message, routes, availableFlows) {
+    const lower = message.toLowerCase();
+    const hits = [];
+    for (const route of routes) {
+        const terms = route.when
+            .toLowerCase()
+            .split(/[^a-z0-9]+/)
+            .filter((term) => term.length > 3);
+        if (!terms.some((term) => lower.includes(term))) {
+            continue;
+        }
+        if (route.flow) {
+            const flow = availableFlows.find((candidate) => candidate.name === route.flow);
+            if (flow) {
+                hits.push({ kind: 'enterFlow', flow });
+            }
+        }
+        else if (route.agent) {
+            hits.push({ kind: 'route', agentId: route.agent });
+        }
+    }
+    if (hits.length === 1) {
+        return hits[0];
+    }
+    return undefined;
+}
 function keywordRouteFallback(message, routes, availableFlows) {
     const lower = message.toLowerCase();
     for (const route of routes) {

package/package.json

@@ -6,7 +6,7 @@
     "url": "git+https://github.com/kuralle/kuralle-agents.git",
     "directory": "packages/kuralle-core"
   },
-  "version": "0.3.15",
+  "version": "0.3.17",
   "description": "A framework for structured conversational AI agents",
   "publishConfig": {
     "access": "public"
@@ -97,7 +97,7 @@
     "dotenv": "^16.4.0",
     "typescript": "^5.3.0",
     "zod": "^3.23.0",
-    "@kuralle-agents/realtime-audio": "0.3.15"
+    "@kuralle-agents/realtime-audio": "0.3.17"
   },
   "dependencies": {
     "chrono-node": "^2.6.0",