@kuralle-agents/core 0.3.16 → 0.3.17

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/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,8 +19,12 @@ 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] };
     }

package/package.json

@@ -6,7 +6,7 @@
     "url": "git+https://github.com/kuralle/kuralle-agents.git",
     "directory": "packages/kuralle-core"
   },
-  "version": "0.3.16",
+  "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.16"
+    "@kuralle-agents/realtime-audio": "0.3.17"
   },
   "dependencies": {
     "chrono-node": "^2.6.0",