@kuralle-agents/core 0.3.4 → 0.3.6

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/flow/nodeBuilders.d.ts

@@ -4,5 +4,10 @@ import type { ResolvedNode } from '../types/channel.js';
 import type { Tool } from '../types/effectTool.js';
 export declare function resolveInstructions(instructions: Instructions, state: FlowState): string;
 export declare function buildNodePrompt(node: ReplyNode, state: FlowState): string;
+/** Compose the agent base layer (ADR 0001) into a node's system prompt: the
+ *  agent's base instructions (persona / safety / grounding) prefix the node's
+ *  own instructions. Node instructions layer ON TOP — they never replace the
+ *  base. Base resolves against the current state so dynamic base prompts work. */
+export declare function composeSystem(base: Instructions | undefined, nodeSystem: string, state: FlowState): string;
 export declare function resolveReplyNode(node: ReplyNode, state: FlowState): ResolvedNode;
 export declare function resolveCollectExtractionNode(collectNode: CollectNode, missing: string[], state: FlowState, submitTool: Tool): ResolvedNode;

package/dist/flow/nodeBuilders.js

@@ -15,6 +15,14 @@ export function resolveInstructions(instructions, state) {
 export function buildNodePrompt(node, state) {
     return resolveInstructions(node.instructions, state);
 }
+/** Compose the agent base layer (ADR 0001) into a node's system prompt: the
+ *  agent's base instructions (persona / safety / grounding) prefix the node's
+ *  own instructions. Node instructions layer ON TOP — they never replace the
+ *  base. Base resolves against the current state so dynamic base prompts work. */
+export function composeSystem(base, nodeSystem, state) {
+    const baseText = base ? resolveInstructions(base, state) : '';
+    return [baseText, nodeSystem].filter((s) => s && s.trim()).join('\n\n');
+}
 function buildNodeTools(node, state) {
     if (!node.tools) {
         return {};

package/dist/runtime/Runtime.js

@@ -97,6 +97,9 @@ export class Runtime {
                     ? buildMemoryService(this.config.memoryService, opened.agent)
                     : undefined,
             });
+            // Agent base layer (ADR 0001): composed into every node turn by the drivers.
+            runCtx.baseInstructions = opened.agent.instructions;
+            runCtx.globalTools = opened.agent.globalTools;
             await this.hooks?.onStart?.(runCtx);
             const driver = opts.driver ?? new TextDriver();
             let activeAgent = opened.agent;

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

@@ -1,8 +1,9 @@
 import { streamText, generateObject } from 'ai';
-import { buildNodePrompt, resolveInstructions } from '../../flow/nodeBuilders.js';
+import { buildNodePrompt, resolveInstructions, composeSystem } 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';
@@ -28,10 +29,11 @@ export class TextDriver {
         const gather = await runGatherPhase(ctx);
         const out = { text: '', toolResults: [] };
         const model = replyNode.model ?? ctx.model;
-        const baseSystem = node.prompt || buildNodePrompt(replyNode, ctx.runState.state);
+        const nodeSystem = node.prompt || buildNodePrompt(replyNode, ctx.runState.state);
+        const baseSystem = composeSystem(ctx.baseInstructions, nodeSystem, ctx.runState.state);
         const system = appendGatherBlocks(baseSystem, [gather.retrievalBlock, gather.memoryBlock]);
         const messages = [...ctx.runState.messages];
-        const aiTools = this.resolveTools(node);
+        const aiTools = this.resolveTools(node, ctx.globalTools);
         const maxSteps = resolveMaxSteps(ctx.limits, this.maxSteps);
         const toolCallsMade = [];
         let draftText = '';
@@ -126,8 +128,15 @@ 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 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
@@ -151,8 +160,8 @@ export class TextDriver {
         const input = consumePendingUserInput(ctx.session);
         return { type: 'message', input };
     }
-    resolveTools(resolved) {
-        const merged = { ...this.toolDefs, ...(resolved.localTools ?? {}) };
+    resolveTools(resolved, globalTools) {
+        const merged = { ...this.toolDefs, ...(globalTools ?? {}), ...(resolved.localTools ?? {}) };
         const aiTools = { ...resolved.tools };
         for (const [name, tool] of Object.entries(merged)) {
             if (tool && !aiTools[name]) {

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,5 +1,6 @@
 import { generateObject } from 'ai';
-import { buildNodePrompt, resolveInstructions } from '../../flow/nodeBuilders.js';
+import { runSilentExtraction } from './extractionTurn.js';
+import { buildNodePrompt, resolveInstructions, composeSystem } from '../../flow/nodeBuilders.js';
 import { classifyControl } from '../../flow/classifyControl.js';
 import { applyPreTurnPolicies, applyPostTurnPolicies } from '../policies/agentTurn.js';
 import { resolveMaxSteps } from '../policies/limits.js';
@@ -30,9 +31,10 @@ export class VoiceDriver {
         }
         const gather = await runGatherPhase(ctx);
         const out = { text: '', toolResults: [] };
-        const baseSystem = node.prompt || buildNodePrompt(replyNode, ctx.runState.state);
+        const nodeSystem = node.prompt || buildNodePrompt(replyNode, ctx.runState.state);
+        const baseSystem = composeSystem(ctx.baseInstructions, nodeSystem, ctx.runState.state);
         const system = appendGatherBlocks(baseSystem, [gather.retrievalBlock, gather.memoryBlock]);
-        const geminiTools = resolveVoiceGeminiTools(node, this.toolDefs);
+        const geminiTools = resolveVoiceGeminiTools(node, { ...this.toolDefs, ...(ctx.globalTools ?? {}) });
         const toolCallsMade = [];
         const maxSteps = resolveMaxSteps(ctx.limits, this.maxSteps);
         let draftText = '';
@@ -62,7 +64,7 @@ export class VoiceDriver {
         return out;
     }
     async runStructured(node, ctx) {
-        const system = resolveInstructions(node.instructions, ctx.runState.state);
+        const system = composeSystem(ctx.baseInstructions, resolveInstructions(node.instructions, ctx.runState.state), ctx.runState.state);
         const schema = node.schema;
         const { object } = await generateObject({
             model: ctx.model,
@@ -73,6 +75,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,87 @@
+import { streamText } from 'ai';
+import { buildToolSet } from '../../tools/effect/index.js';
+import { buildNodePrompt, composeSystem } 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 nodeSystem = node.prompt || buildNodePrompt(replyNode, ctx.runState.state);
+    const system = composeSystem(ctx.baseInstructions, nodeSystem, 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/agentConfig.d.ts

@@ -16,6 +16,12 @@ export interface AgentConfig {
     model?: LanguageModel;
     tools?: ToolSet;
     effectTools?: Record<string, AnyTool>;
+    /** Safe, always-available tools made model-visible in EVERY speaking node turn
+     *  (the agent "base layer", ADR 0001) — e.g. a returns/FAQ knowledge-base
+     *  lookup the user might ask for mid-flow. This is an explicit allow-list:
+     *  NEVER put consequential/mutating tools here (they must stay flow-gated), and
+     *  they are not exposed during non-speaking collect extraction. */
+    globalTools?: Record<string, AnyTool>;
     flows?: Flow[];
     routes?: Route[];
     routing?: RoutingPolicy;

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/dist/types/run-context.d.ts

@@ -8,6 +8,7 @@ import type { RefinementCapability } from '../capabilities/RefinementCapability.
 import type { ValidationCapability } from '../capabilities/ValidationCapability.js';
 import type { Limits } from './guardrails.js';
 import type { AnyTool } from './effectTool.js';
+import type { Instructions } from './agentConfig.js';
 export interface EffectToolExecutor {
     execute(args: {
         name: string;
@@ -57,6 +58,12 @@ export interface RunContext {
      * context. Reset to false on every `createRunContext` (i.e. every turn).
      */
     turnInputConsumed?: boolean;
+    /** Agent base layer (ADR 0001), set when entering a flow. `baseInstructions`
+     *  is composed as a prefix into every node turn's system prompt (persona /
+     *  safety / grounding floor); `globalTools` are safe tools made model-visible
+     *  in every speaking turn. */
+    baseInstructions?: Instructions;
+    globalTools?: Record<string, AnyTool>;
     tool(name: string, args: unknown, options?: {
         toolCallId?: string;
         def?: AnyTool;

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.6",
   "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.6"
   },
   "dependencies": {
     "chrono-node": "^2.6.0",