@kuralle-agents/core 0.3.16 → 0.3.18

package/dist/audit/index.d.ts

@@ -1 +1,2 @@
 export { filterAuditEntries } from './filterAuditEntries.js';
+export { appendConversationAudit, type AuditRecordContext, type NewAuditEntry } from './record.js';

package/dist/audit/index.js

@@ -1 +1,2 @@
 export { filterAuditEntries } from './filterAuditEntries.js';
+export { appendConversationAudit } from './record.js';

package/dist/audit/record.d.ts

@@ -0,0 +1,15 @@
+import type { ConversationAuditEntry, AuditEntryBase } from './types.js';
+import type { Session } from '../types/session.js';
+export interface AuditRecordContext {
+    sessionId: string;
+    conversationId?: string;
+    userId?: string;
+    agentId?: string;
+    turnIndex?: number;
+}
+export type NewAuditEntry = {
+    [K in ConversationAuditEntry['type']]: Omit<Extract<ConversationAuditEntry, {
+        type: K;
+    }>, keyof AuditEntryBase>;
+}[ConversationAuditEntry['type']];
+export declare function appendConversationAudit(session: Session, ctx: AuditRecordContext, entry: NewAuditEntry): void;

package/dist/audit/record.js

@@ -0,0 +1,23 @@
+export function appendConversationAudit(session, ctx, entry) {
+    const at = new Date().toISOString();
+    const full = {
+        at,
+        sessionId: ctx.sessionId,
+        conversationId: ctx.conversationId,
+        userId: ctx.userId,
+        agentId: ctx.agentId,
+        turnIndex: ctx.turnIndex,
+        ...entry,
+    };
+    if (!session.metadata) {
+        session.metadata = {
+            createdAt: session.createdAt,
+            lastActiveAt: session.updatedAt,
+            totalTokens: 0,
+            totalSteps: 0,
+            handoffHistory: [],
+        };
+    }
+    session.metadata.audit ??= [];
+    session.metadata.audit.push(full);
+}

package/dist/capabilities/ValidationCapability.d.ts

@@ -1,3 +1,4 @@
+import type { EscalationReason } from '../escalation/types.js';
 import type { Session, SourceRef, ToolCallRecord } from '../types/index.js';
 export interface ValidationCapability {
     readonly name: string;
@@ -21,6 +22,13 @@ export type ValidateDecision = {
     confidence: number;
     rewrittenOutput: string;
     rationale: string;
+} | {
+    decision: 'escalate';
+    confidence: number;
+    rationale: string;
+    escalateTo?: string;
+    escalationReason?: EscalationReason;
+    userFacingMessage?: string;
 } | {
     decision: 'block';
     confidence: number;

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';
@@ -11,6 +12,7 @@ import { loadRecordedSteps } from '../runtime/durable/replay.js';
 import { SuspendError } from '../runtime/durable/RunStore.js';
 import { ToolApprovalDeniedError } from '../tools/effect/errors.js';
 import { emitInteractiveOnNodeEnter } from './emitInteractive.js';
+import { appendConversationAudit } from '../audit/record.js';
 import { appendSafeAssistantMessage, degradeFlowError, findEscalateNode, } from './degrade.js';
 export class FlowOscillationError extends Error {
     constructor(from, to) {
@@ -87,12 +89,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 +144,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 +156,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 };
@@ -165,6 +170,21 @@ async function dispatchNode(node, run, driver, ctx) {
         if (turn.control?.type === 'recover') {
             return { kind: 'end', reason: turn.control.reason ?? 'error_degraded' };
         }
+        if (node.confidenceGate &&
+            turn.confidence != null &&
+            turn.confidence < node.confidenceGate.min) {
+            appendConversationAudit(ctx.session, {
+                sessionId: ctx.session.id,
+                conversationId: ctx.session.conversationId,
+                userId: ctx.session.userId,
+                agentId: ctx.runState.activeAgentId,
+            }, {
+                type: 'escalation',
+                reason: 'low-confidence',
+                confidence: turn.confidence,
+            });
+            return normalizeTransition(node.confidenceGate.onLow);
+        }
         if (node.next) {
             return normalizeTransition(await node.next(turn, run.state));
         }
@@ -172,7 +192,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 +212,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 +220,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

@@ -98,11 +98,13 @@ export class TextDriver {
                 messages.push(toolResultMessage({ toolName: call.toolName, input: call.input, toolCallId: call.toolCallId }, toolResult));
             }
         }
-        const postTurn = await applyPostTurnPolicies(ctx, draftText, toolCallsMade);
-        const finalText = postTurn.text;
-        out.text = finalText;
-        if (finalText) {
-            ctx.emit({ type: 'text-delta', text: finalText });
+        const postTurn = await applyPostTurnPolicies(ctx, draftText, toolCallsMade, gather.citations ?? []);
+        out.confidence = postTurn.confidence;
+        out.control = postTurn.control;
+        const emitText = postTurn.control ? (postTurn.blockedMessage ?? postTurn.text) : postTurn.text;
+        out.text = emitText;
+        if (emitText) {
+            ctx.emit({ type: 'text-delta', text: emitText });
         }
         ctx.emit({ type: 'turn-end' });
         return out;

package/dist/runtime/channels/VoiceDriver.js

@@ -56,10 +56,13 @@ export class VoiceDriver {
                 break;
             }
         }
-        const postTurn = await applyPostTurnPolicies(ctx, draftText, toolCallsMade);
-        out.text = postTurn.text;
-        if (out.text) {
-            ctx.emit({ type: 'text-delta', text: out.text });
+        const postTurn = await applyPostTurnPolicies(ctx, draftText, toolCallsMade, gather.citations ?? []);
+        out.confidence = postTurn.confidence;
+        out.control = postTurn.control;
+        const emitText = postTurn.control ? (postTurn.blockedMessage ?? postTurn.text) : postTurn.text;
+        out.text = emitText;
+        if (emitText) {
+            ctx.emit({ type: 'text-delta', text: emitText });
         }
         ctx.emit({ type: 'turn-end' });
         return out;

package/dist/runtime/grounding/gather.d.ts

@@ -1,7 +1,9 @@
+import type { SourceRef } from '../../types/voice.js';
 import type { GatherScope, RunContext } from '../../types/run-context.js';
 export type { GatherScope } from '../../types/run-context.js';
 export interface GatherResult {
     retrievalBlock?: string;
     memoryBlock?: string;
+    citations?: SourceRef[];
 }
 export declare function runGatherPhase(ctx: RunContext, scope?: GatherScope): Promise<GatherResult>;

package/dist/runtime/grounding/gather.js

@@ -1,9 +1,27 @@
+function normalizeRetrieveResult(raw) {
+    if (raw == null) {
+        return {};
+    }
+    if (typeof raw === 'string') {
+        return { retrievalBlock: raw };
+    }
+    return { retrievalBlock: raw.block, citations: raw.citations };
+}
 export async function runGatherPhase(ctx, scope) {
-    const retrievalBlock = ctx.autoRetrieve && scope?.knowledge?.autoRetrieve !== false
-        ? await ctx.autoRetrieve.retrieve(ctx, scope)
-        : undefined;
+    let retrievalBlock;
+    let citations;
+    if (ctx.autoRetrieve && scope?.knowledge?.autoRetrieve !== false) {
+        const raw = await ctx.autoRetrieve.retrieve(ctx, scope);
+        const normalized = normalizeRetrieveResult(raw);
+        retrievalBlock = normalized.retrievalBlock;
+        citations = normalized.citations;
+        ctx.lastRetrievalCitations = citations;
+    }
+    else {
+        ctx.lastRetrievalCitations = undefined;
+    }
     const memoryBlock = ctx.memoryService?.preload && scope?.memory?.preload !== false
         ? await ctx.memoryService.preload(ctx, scope)
         : undefined;
-    return { retrievalBlock, memoryBlock };
+    return { retrievalBlock, memoryBlock, citations };
 }

package/dist/runtime/grounding/knowledge.js

@@ -1,3 +1,4 @@
+import { normalizeCitations } from '../citations/index.js';
 import { KnowledgeProvider } from '../KnowledgeProvider.js';
 function latestUserMessage(ctx) {
     for (let index = ctx.runState.messages.length - 1; index >= 0; index -= 1) {
@@ -51,7 +52,12 @@ export function buildAutoRetrieveProvider(provider, agent) {
                 ...retrievalResults.map((result) => ({ text: result.text })),
             ];
             const maxChars = provider.resolveConfig(merged).maxOutputTokens * 4;
-            return formatRetrievalBlock(combined, maxChars);
+            const block = formatRetrievalBlock(combined, maxChars);
+            const citations = normalizeCitations(retrievalResults);
+            if (!block && citations.length === 0) {
+                return undefined;
+            }
+            return { block, citations: citations.length > 0 ? citations : undefined };
         },
     };
 }

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/policies/agentTurn.d.ts

@@ -1,4 +1,6 @@
+import type { TurnControl } from '../../types/channel.js';
 import type { ToolCallRecord } from '../../types/session.js';
+import type { SourceRef } from '../../types/voice.js';
 import type { RunContext } from '../../types/run-context.js';
 export interface PreTurnResult {
     proceed: boolean;
@@ -9,6 +11,8 @@ export interface PostTurnResult {
     proceed: boolean;
     text: string;
     blockedMessage?: string;
+    control?: TurnControl;
+    confidence?: number;
 }
 export declare function applyPreTurnPolicies(ctx: RunContext): Promise<PreTurnResult>;
-export declare function applyPostTurnPolicies(ctx: RunContext, assistantOutput: string, toolCallsMade?: ToolCallRecord[]): Promise<PostTurnResult>;
+export declare function applyPostTurnPolicies(ctx: RunContext, assistantOutput: string, toolCallsMade?: ToolCallRecord[], knowledgeCitations?: SourceRef[]): Promise<PostTurnResult>;

package/dist/runtime/policies/agentTurn.js

@@ -1,3 +1,5 @@
+import { appendConversationAudit } from '../../audit/record.js';
+import { SAFE_DEGRADED_MESSAGE } from '../../flow/degrade.js';
 import { runInputProcessors, runOutputProcessors } from '../../processors/ProcessorRunner.js';
 function latestUserMessage(messages) {
     for (let index = messages.length - 1; index >= 0; index -= 1) {
@@ -8,6 +10,67 @@ function latestUserMessage(messages) {
     }
     return '';
 }
+function auditContext(ctx) {
+    return {
+        sessionId: ctx.session.id,
+        conversationId: ctx.session.conversationId,
+        userId: ctx.session.userId,
+        agentId: ctx.runState.activeAgentId,
+    };
+}
+function recordKnowledgeCitations(ctx, citations) {
+    for (const citation of citations) {
+        appendConversationAudit(ctx.session, auditContext(ctx), {
+            type: 'knowledge-citation',
+            sourceId: citation.id,
+            title: citation.title,
+            score: citation.score,
+        });
+    }
+}
+function recordValidationDecision(ctx, policyName, decision) {
+    if (decision.decision === 'block') {
+        appendConversationAudit(ctx.session, auditContext(ctx), {
+            type: 'safety-block',
+            moderator: policyName,
+            rationale: decision.rationale,
+            userFacingMessage: decision.userFacingMessage ?? decision.rationale,
+        });
+        appendConversationAudit(ctx.session, auditContext(ctx), {
+            type: 'validation',
+            aggregate: 'block',
+            confidence: decision.confidence,
+            rationale: decision.rationale,
+            moderator: policyName,
+        });
+        return;
+    }
+    if (decision.decision === 'escalate') {
+        appendConversationAudit(ctx.session, auditContext(ctx), {
+            type: 'escalation',
+            reason: decision.escalationReason ?? 'low-confidence',
+            confidence: decision.confidence,
+        });
+        appendConversationAudit(ctx.session, auditContext(ctx), {
+            type: 'validation',
+            aggregate: 'block',
+            confidence: decision.confidence,
+            rationale: decision.rationale,
+            moderator: policyName,
+        });
+        return;
+    }
+    appendConversationAudit(ctx.session, auditContext(ctx), {
+        type: 'validation',
+        aggregate: decision.decision === 'rewrite' ? 'rewrite' : 'continue',
+        confidence: decision.confidence,
+        rationale: decision.rationale ?? '',
+        moderator: policyName,
+    });
+}
+function safeBlockedText(decision) {
+    return decision.userFacingMessage?.trim() || decision.rationale?.trim() || SAFE_DEGRADED_MESSAGE;
+}
 async function runRefinementPolicies(ctx, userMessage) {
     const policies = ctx.refinementPolicies ?? [];
     if (policies.length === 0) {
@@ -36,34 +99,56 @@ async function runRefinementPolicies(ctx, userMessage) {
     }
     return { proceed: true, userMessage: current };
 }
-async function runValidationPolicies(ctx, userMessage, assistantOutput, toolCallsMade) {
+async function runValidationPolicies(ctx, userMessage, assistantOutput, toolCallsMade, knowledgeCitations) {
     const policies = ctx.validationPolicies ?? [];
     if (policies.length === 0) {
         return { proceed: true, text: assistantOutput };
     }
+    if (knowledgeCitations.length > 0) {
+        recordKnowledgeCitations(ctx, knowledgeCitations);
+    }
     const sorted = [...policies].sort((a, b) => a.name.localeCompare(b.name));
     let current = assistantOutput;
+    let lastConfidence;
     for (const policy of sorted) {
         const decision = await policy.validate({
             session: ctx.session,
             userMessage,
             assistantOutput: current,
             toolCallsMade,
-            knowledgeCitations: [],
+            knowledgeCitations,
             abortSignal: ctx.abortSignal,
         });
+        recordValidationDecision(ctx, policy.name, decision);
+        lastConfidence = decision.confidence;
         if (decision.decision === 'block') {
+            const safe = safeBlockedText(decision);
             return {
                 proceed: false,
-                text: decision.userFacingMessage ?? '',
-                blockedMessage: decision.userFacingMessage ?? decision.rationale,
+                text: safe,
+                blockedMessage: safe,
+                control: { type: 'recover', reason: decision.rationale },
+                confidence: decision.confidence,
+            };
+        }
+        if (decision.decision === 'escalate') {
+            const safe = safeBlockedText(decision);
+            return {
+                proceed: false,
+                text: safe,
+                blockedMessage: safe,
+                control: { type: 'escalate', reason: decision.rationale },
+                confidence: decision.confidence,
             };
         }
         if (decision.decision === 'rewrite') {
             current = decision.rewrittenOutput;
         }
     }
-    return { proceed: true, text: current };
+    if (ctx.session.metadata) {
+        ctx.session.metadata.lastValidationConfidence = lastConfidence;
+    }
+    return { proceed: true, text: current, confidence: lastConfidence };
 }
 export async function applyPreTurnPolicies(ctx) {
     const userMessage = latestUserMessage(ctx.runState.messages);
@@ -92,7 +177,7 @@ export async function applyPreTurnPolicies(ctx) {
     }
     return runRefinementPolicies(ctx, latestUserMessage(ctx.runState.messages));
 }
-export async function applyPostTurnPolicies(ctx, assistantOutput, toolCallsMade = []) {
+export async function applyPostTurnPolicies(ctx, assistantOutput, toolCallsMade = [], knowledgeCitations = []) {
     const userMessage = latestUserMessage(ctx.runState.messages);
     const processors = ctx.outputProcessors ?? [];
     let current = assistantOutput;
@@ -117,7 +202,8 @@ export async function applyPostTurnPolicies(ctx, assistantOutput, toolCallsMade
         }
         current = outcome.text;
     }
-    return runValidationPolicies(ctx, userMessage, current, toolCallsMade);
+    const citations = knowledgeCitations.length > 0 ? knowledgeCitations : (ctx.lastRetrievalCitations ?? []);
+    return runValidationPolicies(ctx, userMessage, current, toolCallsMade, citations);
 }
 function patchLatestUserMessage(messages, next) {
     for (let index = messages.length - 1; index >= 0; index -= 1) {

package/dist/runtime/policies/resolvePolicies.js

@@ -5,8 +5,8 @@ export function resolveAgentPolicies(agent) {
     return {
         inputProcessors: guardrails?.input ?? [],
         outputProcessors: guardrails?.output ?? [],
-        refinementPolicies: [],
-        validationPolicies: [],
+        refinementPolicies: agent.refine ?? [],
+        validationPolicies: agent.validate ?? [],
         limits: agent.limits,
         enforcer: enforcementRules.length > 0 ? createToolEnforcer(enforcementRules) : undefined,
     };

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

@@ -4,6 +4,8 @@ import type { Flow } from './flow.js';
 import type { Route, RoutingPolicy } from './route.js';
 import type { Guardrails, Limits } from './guardrails.js';
 import type { AgentKnowledge, AgentMemory } from './grounding.js';
+import type { RefinementCapability } from '../capabilities/RefinementCapability.js';
+import type { ValidationCapability } from '../capabilities/ValidationCapability.js';
 import type { AnyTool } from './effectTool.js';
 export type Instructions = string | AgentPrompt | ((ctx: {
     state: Record<string, unknown>;
@@ -35,6 +37,10 @@ export interface AgentConfig {
     memory?: AgentMemory;
     guardrails?: Guardrails;
     limits?: Limits;
+    /** Post-turn validation policies (grounding/confidence gate). Default: none. */
+    validate?: ValidationCapability[];
+    /** Pre-turn refinement policies. Default: none. */
+    refine?: RefinementCapability[];
     experimental?: {
         /** Flow reply nodes: silo flow-transition control tools + deterministic evaluator (ADR 0003 H1). Default OFF. */
         outOfBandControl?: boolean;

package/dist/types/flow.d.ts

@@ -56,6 +56,11 @@ export interface ReplyNode {
     model?: LanguageModel;
     context?: ContextStrategy;
     grounding?: NodeGrounding;
+    /** When set, routes to `onLow` when post-turn validation confidence is below `min`. */
+    confidenceGate?: {
+        min: number;
+        onLow: Transition;
+    };
     next?: (turn: TurnResult, state: FlowState) => Transition | Promise<Transition>;
 }
 export interface CollectNode {

package/dist/types/run-context.d.ts

@@ -9,7 +9,7 @@ import type { ValidationCapability } from '../capabilities/ValidationCapability.
 import type { Limits } from './guardrails.js';
 import type { AnyTool } from './effectTool.js';
 import type { Instructions } from './agentConfig.js';
-import type { AgentKnowledgeOverrides } from './voice.js';
+import type { AgentKnowledgeOverrides, SourceRef } from './voice.js';
 export interface GatherScope {
     query?: string;
     knowledge?: AgentKnowledgeOverrides & {
@@ -33,8 +33,12 @@ export interface EffectToolExecutor {
     /** Resolve a registered tool definition by name (used to read flags like `needsApproval`). */
     getTool?(name: string): AnyTool | undefined;
 }
+export interface AutoRetrieveResult {
+    block?: string;
+    citations?: SourceRef[];
+}
 export interface AutoRetrieveProvider {
-    retrieve(ctx: RunContext, scope?: GatherScope): Promise<string | undefined>;
+    retrieve(ctx: RunContext, scope?: GatherScope): Promise<AutoRetrieveResult | string | undefined>;
 }
 export interface MemoryService {
     preload?(ctx: RunContext, scope?: GatherScope): Promise<string | undefined>;
@@ -73,6 +77,8 @@ export interface RunContext {
      * context. Reset to false on every `createRunContext` (i.e. every turn).
      */
     turnInputConsumed?: boolean;
+    /** Citations from the latest gather-phase retrieval on this turn. */
+    lastRetrievalCitations?: SourceRef[];
     /** 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

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