@kuralle-agents/core 0.3.4 → 0.3.5

package/dist/flow/collectUntilComplete.js

@@ -32,6 +32,9 @@ export async function collectUntilComplete(node, run, driver, ctx) {
             appendUserMessage(run, signal.input);
         }
         else if (ctx.turnInputConsumed) {
+            // No fresh input to extract this turn: ask (deterministically) for the
+            // fields still missing and wait. Never run extraction over stale context.
+            emitCollectAsk(node, run, ctx);
             return { kind: 'stay' };
         }
         ctx.turnInputConsumed = true;
@@ -46,11 +49,49 @@ export async function collectUntilComplete(node, run, driver, ctx) {
             userMessage: peekLatestUserMessage(run),
         });
         const resolved = resolveCollectExtractionNode(node, missing, run.state, submitTool);
-        const turn = await driver.runAgentTurn(resolved, ctx);
+        // 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
+        // text is likewise dropped here. The user-facing question is the deterministic
+        // `ask` emitted above — never model-authored.
+        const turn = await (driver.runExtraction
+            ? driver.runExtraction(resolved, ctx)
+            : driver.runAgentTurn(resolved, ctx));
         mergeExtractionFromTurn(node, run, turn);
-        appendAssistantMessage(run, turn.text);
     }
 }
+function humanizeField(field) {
+    return field
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/[_-]+/g, ' ')
+        .trim()
+        .toLowerCase();
+}
+/** Deterministic, framework-authored question for the still-missing fields. Uses
+ *  the node's `ask` when provided, else a safe default that never references a
+ *  downstream outcome (order/delivery/payment/website). */
+function renderCollectAsk(node, missing, state) {
+    if (node.ask) {
+        return node.ask(missing, state);
+    }
+    if (missing.length === 1) {
+        return `Could you share your ${humanizeField(missing[0])}?`;
+    }
+    if (missing.length > 1) {
+        return `Could you share: ${missing.map(humanizeField).join(', ')}?`;
+    }
+    return 'Could you tell me a little more?';
+}
+function emitCollectAsk(node, run, ctx) {
+    const missing = computeMissingFields(node, getCollectData(run.state, node.id));
+    const text = renderCollectAsk(node, missing, run.state);
+    if (!text.trim()) {
+        return;
+    }
+    ctx.emit({ type: 'text-delta', text });
+    ctx.emit({ type: 'turn-end' });
+    appendAssistantMessage(run, text);
+}
 function mergeExtractionFromTurn(node, run, turn) {
     mergeTurnExtraction(node, run.state, turn.toolResults.map((record) => ({ name: record.name, result: record.result })));
 }

package/dist/runtime/channels/TextDriver.d.ts

@@ -13,6 +13,7 @@ export declare class TextDriver implements ChannelDriver {
     private readonly maxSteps;
     constructor(config?: TextDriverConfig);
     runAgentTurn(node: ResolvedNode, ctx: RunContext): Promise<TurnResult>;
+    runExtraction(node: ResolvedNode, ctx: RunContext): Promise<TurnResult>;
     runStructured(node: DecideNode, ctx: RunContext): Promise<unknown>;
     awaitUser(ctx: RunContext): Promise<UserSignal>;
     private resolveTools;

package/dist/runtime/channels/TextDriver.js

@@ -3,6 +3,7 @@ import { buildNodePrompt, resolveInstructions } from '../../flow/nodeBuilders.js
 import { buildToolSet } from '../../tools/effect/index.js';
 import { classifyControl } from '../../flow/classifyControl.js';
 import { consumePendingUserInput } from './inputBuffer.js';
+import { runSilentExtraction } from './extractionTurn.js';
 import { applyPreTurnPolicies, applyPostTurnPolicies } from '../policies/agentTurn.js';
 import { resolveMaxSteps } from '../policies/limits.js';
 import { appendGatherBlocks, runGatherPhase } from '../grounding/index.js';
@@ -126,6 +127,13 @@ export class TextDriver {
         ctx.emit({ type: 'turn-end' });
         return out;
     }
+    // Non-speaking field extraction for collect nodes (shared helper so text and
+    // voice are identical). The model's prose is discarded; the user-facing
+    // question is emitted deterministically by the flow engine (CollectNode.ask).
+    runExtraction(node, ctx) {
+        const model = node.node.model ?? ctx.model;
+        return runSilentExtraction(node, ctx, model, resolveMaxSteps(ctx.limits, this.maxSteps));
+    }
     async runStructured(node, ctx) {
         const base = resolveInstructions(node.instructions, ctx.runState.state);
         const schema = node.schema;

package/dist/runtime/channels/VoiceDriver.d.ts

@@ -20,6 +20,7 @@ export declare class VoiceDriver implements ChannelDriver {
     constructor(config: VoiceDriverConfig);
     runAgentTurn(node: ResolvedNode, ctx: RunContext): Promise<TurnResult>;
     runStructured(node: DecideNode, ctx: RunContext): Promise<unknown>;
+    runExtraction(node: ResolvedNode, ctx: RunContext): Promise<TurnResult>;
     awaitUser(ctx: RunContext): Promise<UserSignal>;
     reconfigure(config: Partial<RealtimeSessionConfig>): Promise<void>;
     getHeardCharCount(): number;

package/dist/runtime/channels/VoiceDriver.js

@@ -1,4 +1,5 @@
 import { generateObject } from 'ai';
+import { runSilentExtraction } from './extractionTurn.js';
 import { buildNodePrompt, resolveInstructions } from '../../flow/nodeBuilders.js';
 import { classifyControl } from '../../flow/classifyControl.js';
 import { applyPreTurnPolicies, applyPostTurnPolicies } from '../policies/agentTurn.js';
@@ -73,6 +74,14 @@ export class VoiceDriver {
         });
         return object;
     }
+    // Non-speaking collect extraction: uses the shared text-model extraction path
+    // rather than the realtime audio provider, so the agent never SPEAKS during
+    // field collection (which is where ungrounded narration leaked). Identical
+    // behavior to TextDriver — voice and text emit the same structural events; the
+    // user-facing question is the deterministic CollectNode.ask, synthesized after.
+    runExtraction(node, ctx) {
+        return runSilentExtraction(node, ctx, ctx.model, resolveMaxSteps(ctx.limits, this.maxSteps));
+    }
     async awaitUser(ctx) {
         if (this.pendingBargeInInput != null) {
             const input = this.pendingBargeInInput;

package/dist/runtime/channels/extractionTurn.d.ts

@@ -0,0 +1,14 @@
+import { type LanguageModel } from 'ai';
+import type { ResolvedNode, TurnResult } from '../../types/channel.js';
+import type { RunContext } from '../../types/run-context.js';
+/**
+ * Shared, NON-SPEAKING field extraction for `collect` nodes, used by every
+ * ChannelDriver so text and voice behave identically. It runs the model with the
+ * node's submit tool to pull structured fields, but never emits a `text-delta`,
+ * never emits `turn-end`, and never appends model prose — the model's words are
+ * discarded by construction. The user-facing question is emitted deterministically
+ * by the flow engine (`CollectNode.ask`), not by the model. This is the structural
+ * invariant that stops a collect turn from narrating outcomes that contradict
+ * flow state, regardless of which model is used.
+ */
+export declare function runSilentExtraction(node: ResolvedNode, ctx: RunContext, model: LanguageModel, maxSteps: number): Promise<TurnResult>;

package/dist/runtime/channels/extractionTurn.js

@@ -0,0 +1,86 @@
+import { streamText } from 'ai';
+import { buildToolSet } from '../../tools/effect/index.js';
+import { buildNodePrompt } from '../../flow/nodeBuilders.js';
+/**
+ * Shared, NON-SPEAKING field extraction for `collect` nodes, used by every
+ * ChannelDriver so text and voice behave identically. It runs the model with the
+ * node's submit tool to pull structured fields, but never emits a `text-delta`,
+ * never emits `turn-end`, and never appends model prose — the model's words are
+ * discarded by construction. The user-facing question is emitted deterministically
+ * by the flow engine (`CollectNode.ask`), not by the model. This is the structural
+ * invariant that stops a collect turn from narrating outcomes that contradict
+ * flow state, regardless of which model is used.
+ */
+export async function runSilentExtraction(node, ctx, model, maxSteps) {
+    const replyNode = node.node;
+    const system = node.prompt || buildNodePrompt(replyNode, ctx.runState.state);
+    const messages = [...ctx.runState.messages];
+    const aiTools = resolveExtractionTools(node);
+    const out = { text: '', toolResults: [] };
+    for (let step = 0; step < maxSteps; step += 1) {
+        const result = streamText({ model, system, messages, tools: aiTools, abortSignal: ctx.abortSignal });
+        for await (const part of result.fullStream) {
+            // Intentionally NOT handling 'text-delta' — extraction never speaks.
+            if (part.type === 'error') {
+                const err = part.error;
+                const message = err instanceof Error ? err.message : String(err);
+                ctx.emit({ type: 'error', error: message });
+                throw err instanceof Error ? err : new Error(message);
+            }
+        }
+        const finishReason = await result.finishReason;
+        const response = await result.response;
+        messages.push(...response.messages);
+        if (finishReason !== 'tool-calls') {
+            break;
+        }
+        const toolCalls = await result.toolCalls;
+        for (const call of toolCalls) {
+            const localTool = node.localTools?.[call.toolName];
+            const toolResult = await ctx.tool(call.toolName, call.input, {
+                toolCallId: call.toolCallId,
+                ...(localTool && {
+                    def: localTool,
+                    toolCtx: {
+                        session: ctx.session,
+                        runState: ctx.runState,
+                        tool: ctx.tool.bind(ctx),
+                        now: ctx.now.bind(ctx),
+                        uuid: ctx.uuid.bind(ctx),
+                        emit: ctx.emit.bind(ctx),
+                    },
+                }),
+            });
+            out.toolResults.push({
+                name: call.toolName,
+                args: call.input,
+                result: toolResult,
+                toolCallId: call.toolCallId,
+            });
+            messages.push({
+                role: 'tool',
+                content: [
+                    {
+                        type: 'tool-result',
+                        toolCallId: call.toolCallId,
+                        toolName: call.toolName,
+                        output: { type: 'json', value: toolResult },
+                    },
+                ],
+            });
+        }
+    }
+    return out;
+}
+/** Tools available to the extraction turn = the node's submit tool only (built
+ *  from the resolved node, independent of any driver-level tool defs) so text and
+ *  voice resolve an identical toolset. */
+function resolveExtractionTools(resolved) {
+    const aiTools = { ...resolved.tools };
+    for (const [name, tool] of Object.entries(resolved.localTools ?? {})) {
+        if (tool && !aiTools[name]) {
+            Object.assign(aiTools, buildToolSet({ [name]: tool }));
+        }
+    }
+    return Object.keys(aiTools).length > 0 ? aiTools : undefined;
+}

package/dist/types/channel.d.ts

@@ -14,6 +14,13 @@ export interface ChannelDriver {
     runStructured?(node: Extract<FlowNode, {
         kind: 'decide';
     }>, ctx: RunContext): Promise<unknown>;
+    /** Non-speaking field extraction for `collect` nodes: runs the submit tool to
+     *  pull structured fields but MUST NOT emit any user-facing text (no
+     *  text-delta, no spoken transcript). The returned `text` is ignored by the
+     *  flow engine. This is the structural backstop that stops a collect turn from
+     *  authoring narration that contradicts flow state. Drivers without it fall
+     *  back to runAgentTurn, whose text the engine then discards. */
+    runExtraction?(node: ResolvedNode, ctx: RunContext): Promise<TurnResult>;
 }
 export interface TurnResult {
     text: string;

package/dist/types/flow.d.ts

@@ -42,7 +42,14 @@ export interface CollectNode {
     id: string;
     schema: StandardSchemaV1;
     required?: string[];
+    /** Extraction-only guidance for the (non-speaking) field extraction turn.
+     *  This text is NEVER shown to the user — see `ask` for user-facing copy. */
     instructions?: (missing: string[], state: FlowState) => Instructions;
+    /** Deterministic, framework-emitted question shown when fields are still
+     *  missing. Collect extraction never speaks model-authored text, so this is
+     *  the only user-facing copy a collect node produces. Must not claim any
+     *  downstream outcome (order placed, delivery scheduled, payment, website). */
+    ask?: (missing: string[], state: FlowState) => string;
     choices?: ChoiceOption[];
     maxTurns?: number;
     onComplete: (data: unknown, state: FlowState) => Transition | Promise<Transition>;

package/package.json

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