@kuralle-agents/core 0.3.17 → 0.3.19

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/runFlow.js

@@ -12,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) {
@@ -169,6 +170,21 @@ async function dispatchNode(node, run, driver, ctx, agent, flow) {
         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));
         }

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/channels/index.d.ts

@@ -4,4 +4,4 @@ export type { TextDriverConfig } from './TextDriver.js';
 export { VoiceDriver } from './VoiceDriver.js';
 export type { VoiceDriverConfig } from './VoiceDriver.js';
 export { resolveVoiceGeminiTools, v2ToolsToGemini } from './voiceTools.js';
-export { setPendingUserInput, consumePendingUserInput, peekPendingUserInput } from './inputBuffer.js';
+export { setPendingUserInput, consumePendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './inputBuffer.js';

package/dist/runtime/channels/index.js

@@ -5,4 +5,4 @@ export { TextDriver, buildNodePrompt } from './TextDriver.js';
 // the primary primitive; cascaded voice runs over text (see livekit-plugin).
 export { VoiceDriver } from './VoiceDriver.js';
 export { resolveVoiceGeminiTools, v2ToolsToGemini } from './voiceTools.js';
-export { setPendingUserInput, consumePendingUserInput, peekPendingUserInput } from './inputBuffer.js';
+export { setPendingUserInput, consumePendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './inputBuffer.js';

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

@@ -3,4 +3,5 @@ export type { RuntimeLike } from './RuntimeLike.js';
 export { SessionWorkingMemory } from './WorkingMemory.js';
 export { TextDriver, VoiceDriver } from './channels/index.js';
 export type { VoiceDriverConfig } from './channels/index.js';
+export { setPendingUserInput, consumePendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './channels/index.js';
 export { isAbortSignal, type InterruptionEvent, type AbortOptions, type CancellationReason, } from '../types/index.js';

package/dist/runtime/index.js

@@ -1,4 +1,8 @@
 export { createRuntime, Runtime, } from './Runtime.js';
 export { SessionWorkingMemory } from './WorkingMemory.js';
 export { TextDriver, VoiceDriver } from './channels/index.js';
+// Pending-input buffer helpers — required by custom ChannelDriver authors to
+// implement awaitUser the same FIFO-aware way the built-in drivers do (the
+// buffer is an ordered queue since 0.3.13/H3, not a single slot).
+export { setPendingUserInput, consumePendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './channels/index.js';
 export { isAbortSignal, } from '../types/index.js';

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/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.17",
+  "version": "0.3.19",
   "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.17"
+    "@kuralle-agents/realtime-audio": "0.3.19"
   },
   "dependencies": {
     "chrono-node": "^2.6.0",