@kuralle-agents/core 0.3.20 → 0.4.0

package/README.md

@@ -48,7 +48,7 @@ const runtime = createRuntime({ agents: [agent], defaultAgentId: 'support' });
 
 const handle = runtime.run({ input: 'Hello', sessionId: 'demo' });
 for await (const part of handle.events) {           // events is a property, not a method
-  if (part.type === 'text-delta') process.stdout.write(part.text);
+  if (part.type === 'text-delta') process.stdout.write(part.delta);
   if (part.type === 'done') console.log('\nSession:', part.sessionId);
 }
 await handle;   // resolves to TurnResult once the stream is consumed

package/dist/capabilities/ValidationCapability.d.ts

@@ -3,6 +3,8 @@ import type { Session, SourceRef, ToolCallRecord } from '../types/index.js';
 export interface ValidationCapability {
     readonly name: string;
     readonly order?: 'parallel' | 'serial';
+    /** Absent ⇒ `turn` (buffered, safe). Streaming is an explicit opt-in by the gate author. */
+    readonly streamGranularity?: 'sentence' | 'turn';
     validate(input: ValidateInput): Promise<ValidateDecision>;
 }
 export interface ValidateInput {

package/dist/eval/EvalRunner.js

@@ -25,7 +25,7 @@ export class EvalRunner {
             const handle = runtime.run({ input: turn.input, sessionId });
             for await (const part of handle.events) {
                 if (part.type === 'text-delta') {
-                    response += part.text;
+                    response += part.delta;
                 }
                 if (part.type === 'tool-call') {
                     toolsCalled.push(part.toolName);

package/dist/flow/collectDigression.js

@@ -76,7 +76,10 @@ export async function runCollectDigression(options) {
     };
     const turn = await driver.runAgentTurn(resolveReplyNode(replyNode, run.state, { freeConversation: true }), ctx);
     if (turn.text.trim()) {
-        ctx.emit({ type: 'text-delta', text: turn.text });
+        const id = crypto.randomUUID();
+        ctx.emit({ type: 'text-start', id });
+        ctx.emit({ type: 'text-delta', id, delta: turn.text });
+        ctx.emit({ type: 'text-end', id });
         ctx.emit({ type: 'turn-end' });
         appendAssistantMessage(run, turn.text);
     }

package/dist/flow/collectUntilComplete.js

@@ -111,7 +111,10 @@ export function emitCollectAsk(node, run, ctx) {
     if (!text.trim()) {
         return;
     }
-    ctx.emit({ type: 'text-delta', text });
+    const id = crypto.randomUUID();
+    ctx.emit({ type: 'text-start', id });
+    ctx.emit({ type: 'text-delta', id, delta: text });
+    ctx.emit({ type: 'text-end', id });
     ctx.emit({ type: 'turn-end' });
     appendAssistantMessage(run, text);
 }

package/dist/flow/degrade.js

@@ -6,7 +6,10 @@ export function findEscalateNode(registry) {
 export function appendSafeAssistantMessage(run, ctx, text = SAFE_DEGRADED_MESSAGE) {
     const message = { role: 'assistant', content: text };
     run.messages = [...run.messages, message];
-    ctx.emit({ type: 'text-delta', text });
+    const id = crypto.randomUUID();
+    ctx.emit({ type: 'text-start', id });
+    ctx.emit({ type: 'text-delta', id, delta: text });
+    ctx.emit({ type: 'text-end', id });
 }
 export async function degradeFlowError(flow, registry, run, driver, ctx, dispatchNode) {
     appendSafeAssistantMessage(run, ctx);

package/dist/foundation/DefaultConversationEventLog.js

@@ -33,7 +33,7 @@ export class DefaultConversationEventLog {
         if (part.type === 'text-delta') {
             const prevRaw = context.session.workingMemory[ASSISTANT_TEXT_KEY];
             const prev = typeof prevRaw === 'string' ? prevRaw : '';
-            context.session.workingMemory[ASSISTANT_TEXT_KEY] = prev + part.text;
+            context.session.workingMemory[ASSISTANT_TEXT_KEY] = prev + part.delta;
             return;
         }
         const base = {

package/dist/runtime/Runtime.js

@@ -74,7 +74,12 @@ export class Runtime {
                 tools: effectTools,
                 enforcer: policies.enforcer,
                 agentId: opened.agent.id,
-                onInterim: (message) => emit({ type: 'text-delta', text: message }),
+                onInterim: (message) => {
+                    const id = crypto.randomUUID();
+                    emit({ type: 'text-start', id });
+                    emit({ type: 'text-delta', id, delta: message });
+                    emit({ type: 'text-end', id });
+                },
             });
             const steps = await loadRecordedSteps(opened.runStore, opened.runState.runId);
             const freshRunState = (await opened.runStore.getRunState(opened.runState.runId)) ?? opened.runState;
@@ -173,7 +178,10 @@ export class Runtime {
                 if (isDegradableRuntimeError(error)) {
                     const message = error instanceof Error ? error.message : String(error);
                     emit({ type: 'error', error: message });
-                    emit({ type: 'text-delta', text: SAFE_DEGRADED_MESSAGE });
+                    const degradedId = crypto.randomUUID();
+                    emit({ type: 'text-start', id: degradedId });
+                    emit({ type: 'text-delta', id: degradedId, delta: SAFE_DEGRADED_MESSAGE });
+                    emit({ type: 'text-end', id: degradedId });
                     runCtx.runState.messages = [
                         ...runCtx.runState.messages,
                         { role: 'assistant', content: SAFE_DEGRADED_MESSAGE },

package/dist/runtime/channels/TextDriver.js

@@ -6,6 +6,8 @@ import { consumePendingUserInput } from './inputBuffer.js';
 import { runSilentExtraction } from './extractionTurn.js';
 import { applyPreTurnPolicies, applyPostTurnPolicies } from '../policies/agentTurn.js';
 import { resolveMaxSteps } from '../policies/limits.js';
+import { speakGated } from './streaming/speakGated.js';
+import { resolveStreamMode } from './streaming/mode.js';
 import { appendGatherBlocks, resolveNodeGatherScope, runGatherPhase } from '../grounding/index.js';
 import { isFlowTransitionControlTool } from '../../flow/flowControlTools.js';
 import { resolveStructuredDecide } from '../../flow/choiceMatch.js';
@@ -24,7 +26,10 @@ export class TextDriver {
         const preTurn = await applyPreTurnPolicies(ctx);
         if (!preTurn.proceed) {
             const blocked = preTurn.blockedMessage ?? 'Input blocked by guardrails';
-            ctx.emit({ type: 'text-delta', text: blocked });
+            const id = crypto.randomUUID();
+            ctx.emit({ type: 'text-start', id });
+            ctx.emit({ type: 'text-delta', id, delta: blocked });
+            ctx.emit({ type: 'text-end', id });
             ctx.emit({ type: 'turn-end' });
             return { text: blocked, toolResults: [] };
         }
@@ -39,73 +44,89 @@ export class TextDriver {
         const aiTools = this.resolveTools(node, ctx);
         const maxSteps = resolveMaxSteps(ctx.limits, this.maxSteps);
         const toolCallsMade = [];
-        let draftText = '';
-        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) {
-                if (part.type === 'text-delta') {
-                    draftText += part.text;
+        const mode = resolveStreamMode(ctx, node);
+        const turnId = crypto.randomUUID();
+        const source = {
+            async *[Symbol.asyncIterator]() {
+                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) {
+                        if (part.type === 'text-delta') {
+                            yield { delta: part.text };
+                        }
+                        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) {
+                        ctx.emit({
+                            type: 'tool-call',
+                            toolName: call.toolName,
+                            args: call.input,
+                            toolCallId: call.toolCallId,
+                        });
+                        const { result: toolResult, control, failed } = await executeModelToolCall(ctx, { toolName: call.toolName, input: call.input, toolCallId: call.toolCallId }, node.localTools);
+                        out.toolResults.push({
+                            name: call.toolName,
+                            args: call.input,
+                            result: toolResult,
+                            toolCallId: call.toolCallId,
+                        });
+                        toolCallsMade.push({
+                            toolCallId: call.toolCallId,
+                            toolName: call.toolName,
+                            args: call.input,
+                            result: toolResult,
+                            success: !failed,
+                            timestamp: Date.now(),
+                        });
+                        out.control ??= control;
+                        ctx.emit({
+                            type: 'tool-result',
+                            toolName: call.toolName,
+                            result: toolResult,
+                            toolCallId: call.toolCallId,
+                        });
+                        messages.push(toolResultMessage({ toolName: call.toolName, input: call.input, toolCallId: call.toolCallId }, toolResult));
+                    }
                 }
-                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) {
-                ctx.emit({
-                    type: 'tool-call',
-                    toolName: call.toolName,
-                    args: call.input,
-                    toolCallId: call.toolCallId,
-                });
-                const { result: toolResult, control, failed } = await executeModelToolCall(ctx, { toolName: call.toolName, input: call.input, toolCallId: call.toolCallId }, node.localTools);
-                out.toolResults.push({
-                    name: call.toolName,
-                    args: call.input,
-                    result: toolResult,
-                    toolCallId: call.toolCallId,
-                });
-                toolCallsMade.push({
-                    toolCallId: call.toolCallId,
-                    toolName: call.toolName,
-                    args: call.input,
-                    result: toolResult,
-                    success: !failed,
-                    timestamp: Date.now(),
-                });
-                out.control ??= control;
-                ctx.emit({
-                    type: 'tool-result',
-                    toolName: call.toolName,
-                    result: toolResult,
-                    toolCallId: call.toolCallId,
-                });
-                messages.push(toolResultMessage({ toolName: call.toolName, input: call.input, toolCallId: call.toolCallId }, toolResult));
-            }
-        }
-        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 });
-        }
+            },
+        };
+        const spoken = await speakGated({
+            ctx,
+            mode,
+            turnId,
+            source,
+            runGate: async (text, _final) => {
+                const r = await applyPostTurnPolicies(ctx, text, toolCallsMade, gather.citations ?? []);
+                return {
+                    blocked: !r.proceed,
+                    text: r.proceed ? r.text : (r.blockedMessage ?? r.text),
+                    reason: r.control?.reason,
+                    control: r.control,
+                    confidence: r.confidence,
+                };
+            },
+        });
+        out.text = spoken.text;
+        out.control = spoken.control;
+        out.confidence = spoken.confidence;
         ctx.emit({ type: 'turn-end' });
         return out;
     }

package/dist/runtime/channels/VoiceDriver.js

@@ -4,8 +4,35 @@ import { buildNodePrompt, resolveInstructions, composeSystem } from '../../flow/
 import { executeModelToolCall } from './executeModelTool.js';
 import { applyPreTurnPolicies, applyPostTurnPolicies } from '../policies/agentTurn.js';
 import { resolveMaxSteps } from '../policies/limits.js';
+import { speakGated } from './streaming/speakGated.js';
+import { resolveStreamMode } from './streaming/mode.js';
+import { createDeferredTokenSource, } from './streaming/deferredTokenSource.js';
 import { appendGatherBlocks, resolveNodeGatherScope, runGatherPhase } from '../grounding/index.js';
 import { resolveVoiceGeminiTools } from './voiceTools.js';
+function emitNativeRealtimePostHocGate(ctx, client, gate) {
+    if (gate.escalated) {
+        ctx.emit({
+            type: 'safety-blocked',
+            moderator: gate.moderator,
+            rationale: gate.rationale,
+            userFacingMessage: gate.safeText,
+        });
+    }
+    else {
+        ctx.emit({
+            type: 'pipeline-validation-block',
+            rationale: gate.rationale,
+            userFacingMessage: gate.safeText,
+        });
+        ctx.emit({
+            type: 'safety-blocked',
+            moderator: gate.moderator,
+            rationale: gate.rationale,
+            userFacingMessage: gate.safeText,
+        });
+    }
+    client.requestResponse?.(gate.safeText);
+}
 export class VoiceDriver {
     client;
     toolDefs;
@@ -25,7 +52,10 @@ export class VoiceDriver {
         const preTurn = await applyPreTurnPolicies(ctx);
         if (!preTurn.proceed) {
             const blocked = preTurn.blockedMessage ?? 'Input blocked by guardrails';
-            ctx.emit({ type: 'text-delta', text: blocked });
+            const id = crypto.randomUUID();
+            ctx.emit({ type: 'text-start', id });
+            ctx.emit({ type: 'text-delta', id, delta: blocked });
+            ctx.emit({ type: 'text-end', id });
             ctx.emit({ type: 'turn-end' });
             return { text: blocked, toolResults: [] };
         }
@@ -38,17 +68,56 @@ export class VoiceDriver {
         const geminiTools = resolveVoiceGeminiTools(node, { ...this.toolDefs, ...(ctx.globalTools ?? {}) }, { siloFlowControl: ctx.outOfBandControl && !node.freeConversation });
         const toolCallsMade = [];
         const maxSteps = resolveMaxSteps(ctx.limits, this.maxSteps);
+        const mode = resolveStreamMode(ctx, node);
+        const turnId = crypto.randomUUID();
+        const transcript = createDeferredTokenSource();
         let draftText = '';
         this.heardCharCount = 0;
+        let postHocGate = null;
+        const speakPromise = speakGated({
+            ctx,
+            mode,
+            turnId,
+            source: transcript.source,
+            runGate: async (text, _final) => {
+                const r = await applyPostTurnPolicies(ctx, text, toolCallsMade, gather.citations ?? []);
+                if (!r.proceed) {
+                    const safeText = r.blockedMessage ?? r.text;
+                    postHocGate = {
+                        safeText,
+                        rationale: r.control?.reason ?? 'blocked',
+                        moderator: 'post-turn-gate',
+                        escalated: r.control?.type === 'escalate',
+                    };
+                }
+                return {
+                    blocked: !r.proceed,
+                    text: r.proceed ? r.text : (r.blockedMessage ?? r.text),
+                    reason: r.control?.reason,
+                    control: r.control,
+                    confidence: r.confidence,
+                };
+            },
+        });
         await this.reconfigure({ systemInstruction: system, tools: geminiTools });
         for (let step = 0; step < maxSteps; step += 1) {
-            const { outcome, assistantText } = await this.collectProviderTurn(ctx, out, step === 0, toolCallsMade, node.localTools);
+            const { outcome, assistantText } = await this.collectProviderTurn(ctx, out, step === 0, toolCallsMade, node.localTools, transcript);
             draftText += assistantText;
             if (outcome === 'interrupted') {
+                transcript.close('interrupted');
+                try {
+                    await speakPromise;
+                }
+                catch {
+                    /* speakGated cancels in-flight stream on interrupt */
+                }
                 out.interrupted = true;
                 out.truncateAt = this.heardCharCount;
                 out.text = truncateToHeard(draftText, this.heardCharCount);
-                ctx.emit({ type: 'text-delta', text: out.text });
+                const id = crypto.randomUUID();
+                ctx.emit({ type: 'text-start', id });
+                ctx.emit({ type: 'text-delta', id, delta: out.text });
+                ctx.emit({ type: 'text-end', id });
                 ctx.emit({ type: 'turn-end' });
                 return out;
             }
@@ -56,13 +125,15 @@ export class VoiceDriver {
                 break;
             }
         }
-        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 });
+        transcript.close('complete');
+        const spoken = await speakPromise;
+        out.text = spoken.text;
+        out.control = spoken.control;
+        out.confidence = spoken.confidence;
+        if (postHocGate) {
+            // Advisory post-hoc gate: provider audio may already have played; correction does not un-speak it.
+            emitNativeRealtimePostHocGate(ctx, this.client, postHocGate);
+            out.gateScope = 'advisory';
         }
         ctx.emit({ type: 'turn-end' });
         return out;
@@ -94,7 +165,7 @@ export class VoiceDriver {
     getHeardCharCount() {
         return this.heardCharCount;
     }
-    async collectProviderTurn(ctx, out, triggerResponse, toolCallsMade, localTools) {
+    async collectProviderTurn(ctx, out, triggerResponse, toolCallsMade, localTools, transcript) {
         return new Promise((resolve, reject) => {
             let assistantText = '';
             let settled = false;
@@ -111,12 +182,14 @@ export class VoiceDriver {
                     return;
                 settled = true;
                 cleanup();
+                transcript.close('error');
                 reject(error);
             };
             const onTranscript = (text, role) => {
                 if (role === 'assistant') {
                     assistantText += text;
                     this.heardCharCount += text.length;
+                    transcript.push(text);
                 }
                 if (role === 'user' && sawInterrupt) {
                     this.pendingBargeInInput = text;

package/dist/runtime/channels/streaming/SentenceAggregator.d.ts

@@ -0,0 +1,12 @@
+export declare function matchEndOfSentence(text: string): number;
+export declare class SentenceAggregator {
+    private buffer;
+    private needsLookahead;
+    private pendingPeriodConfirm;
+    push(tokenText: string): string[];
+    flush(): string | null;
+    private confirmPendingPeriod;
+    private checkSentenceWithLookahead;
+    private drainConfirmedAtBufferEnd;
+    private emitFirstSentenceIfFound;
+}

package/dist/runtime/channels/streaming/SentenceAggregator.js

@@ -0,0 +1,196 @@
+const ABBREVIATIONS = [
+    'mr.',
+    'mrs.',
+    'ms.',
+    'dr.',
+    'prof.',
+    'st.',
+    'e.g.',
+    'i.e.',
+    'etc.',
+    'vs.',
+    'no.',
+];
+const TERMINAL_PUNCT_RE = /(?:\.{3}|[!?]+|\.)/g;
+const MIN_WORDS_TO_CONFIRM_PERIOD_AT_TOKEN_END = 3;
+function hasWordCharBefore(text, index) {
+    return index > 0 && /\w/.test(text[index - 1]);
+}
+function isDecimalPeriod(text, periodIndex) {
+    if (text[periodIndex] !== '.')
+        return false;
+    const before = periodIndex > 0 ? text[periodIndex - 1] : '';
+    const after = periodIndex < text.length - 1 ? text[periodIndex + 1] : '';
+    return /\d/.test(before) && /\d/.test(after);
+}
+function isAbbreviationPeriod(text, periodIndex) {
+    if (text[periodIndex] !== '.')
+        return false;
+    const prefix = text.slice(0, periodIndex + 1).toLowerCase();
+    for (const abbr of ABBREVIATIONS) {
+        if (prefix.endsWith(abbr)) {
+            const start = prefix.length - abbr.length;
+            if (!hasWordCharBefore(prefix, start))
+                return true;
+        }
+        for (let len = 1; len < abbr.length; len++) {
+            const partial = abbr.slice(0, len);
+            if (!partial.endsWith('.'))
+                continue;
+            if (!prefix.endsWith(partial))
+                continue;
+            const start = prefix.length - partial.length;
+            if (!hasWordCharBefore(prefix, start))
+                return true;
+        }
+    }
+    return false;
+}
+function endsWithSentencePunctuation(text) {
+    if (/[!?]+$/.test(text))
+        return true;
+    if (/\.{3,}$/.test(text))
+        return true;
+    if (/\.$/.test(text) && !/\.{2,}$/.test(text))
+        return true;
+    return false;
+}
+function endsWithIncompleteEllipsis(text) {
+    return /\.{2}$/.test(text) && !/\.{3,}$/.test(text);
+}
+function remainderStartsNewSentence(text, endIndex) {
+    const rest = text.slice(endIndex);
+    return /^\s*$/.test(rest) || /^\s+[A-Z]/.test(rest);
+}
+function wordCount(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return 0;
+    return trimmed.split(/\s+/).length;
+}
+function isValidSentenceEnd(text, endIndex) {
+    const punct = text.slice(0, endIndex).match(/(?:\.{3}|[!?]+|\.)$/)?.[0];
+    if (!punct)
+        return false;
+    const periodIndex = endIndex - punct.length;
+    if (punct === '.' || (punct.startsWith('.') && punct.length === 1)) {
+        if (endIndex < text.length && text[endIndex] === '.')
+            return false;
+        if (isDecimalPeriod(text, periodIndex))
+            return false;
+        if (isAbbreviationPeriod(text, periodIndex))
+            return false;
+    }
+    if (endIndex === text.length && endsWithIncompleteEllipsis(text.slice(0, endIndex))) {
+        return false;
+    }
+    return true;
+}
+export function matchEndOfSentence(text) {
+    if (!text)
+        return 0;
+    TERMINAL_PUNCT_RE.lastIndex = 0;
+    let match;
+    while ((match = TERMINAL_PUNCT_RE.exec(text)) !== null) {
+        const end = match.index + match[0].length;
+        if (!isValidSentenceEnd(text, end))
+            continue;
+        if (remainderStartsNewSentence(text, end))
+            return end;
+    }
+    if (endsWithIncompleteEllipsis(text))
+        return 0;
+    const trailing = text.match(/(?:\.{3}|[!?]+|\.)$/);
+    if (trailing && isValidSentenceEnd(text, text.length))
+        return text.length;
+    return 0;
+}
+export class SentenceAggregator {
+    buffer = '';
+    needsLookahead = false;
+    pendingPeriodConfirm = false;
+    push(tokenText) {
+        if (tokenText === '')
+            return [];
+        if (/^\s+$/.test(tokenText)) {
+            this.buffer += tokenText;
+            return [];
+        }
+        const sentences = [];
+        if (this.pendingPeriodConfirm) {
+            const confirmed = this.confirmPendingPeriod(tokenText[0]);
+            if (confirmed !== null)
+                sentences.push(confirmed);
+        }
+        for (const char of tokenText) {
+            this.buffer += char;
+            const completed = this.checkSentenceWithLookahead(char);
+            if (completed !== null)
+                sentences.push(completed);
+        }
+        const drained = this.drainConfirmedAtBufferEnd();
+        if (drained !== null)
+            sentences.push(drained);
+        return sentences;
+    }
+    flush() {
+        if (this.buffer.length === 0)
+            return null;
+        const tail = this.buffer;
+        this.buffer = '';
+        this.needsLookahead = false;
+        this.pendingPeriodConfirm = false;
+        return tail;
+    }
+    confirmPendingPeriod(nextChar) {
+        this.pendingPeriodConfirm = false;
+        if (nextChar.trim() === '') {
+            this.needsLookahead = false;
+            return this.emitFirstSentenceIfFound();
+        }
+        this.needsLookahead = false;
+        return null;
+    }
+    checkSentenceWithLookahead(char) {
+        if (this.needsLookahead) {
+            if (char.trim() !== '') {
+                this.needsLookahead = false;
+                this.pendingPeriodConfirm = false;
+                return this.emitFirstSentenceIfFound();
+            }
+            return null;
+        }
+        if (this.buffer.length > 0 && endsWithSentencePunctuation(this.buffer)) {
+            this.needsLookahead = true;
+        }
+        return null;
+    }
+    drainConfirmedAtBufferEnd() {
+        if (!this.needsLookahead)
+            return null;
+        if (this.buffer.endsWith('.') && !/\.{2,}$/.test(this.buffer)) {
+            if (wordCount(this.buffer) < MIN_WORDS_TO_CONFIRM_PERIOD_AT_TOKEN_END) {
+                this.pendingPeriodConfirm = true;
+                return null;
+            }
+        }
+        const end = matchEndOfSentence(this.buffer);
+        if (end > 0 && end === this.buffer.length) {
+            this.needsLookahead = false;
+            this.pendingPeriodConfirm = false;
+            const sentence = this.buffer;
+            this.buffer = '';
+            return sentence.length > 0 ? sentence : null;
+        }
+        return null;
+    }
+    emitFirstSentenceIfFound() {
+        const end = matchEndOfSentence(this.buffer);
+        if (end > 0) {
+            const sentence = this.buffer.slice(0, end);
+            this.buffer = this.buffer.slice(end);
+            return sentence.length > 0 ? sentence : null;
+        }
+        return null;
+    }
+}

package/dist/runtime/channels/streaming/deferredTokenSource.d.ts

@@ -0,0 +1,8 @@
+import type { TokenSource } from './speakGated.js';
+export type DeferredCloseReason = 'complete' | 'interrupted' | 'error';
+export interface DeferredTokenSource {
+    source: TokenSource;
+    push(delta: string): void;
+    close(reason?: DeferredCloseReason): void;
+}
+export declare function createDeferredTokenSource(): DeferredTokenSource;

package/dist/runtime/channels/streaming/deferredTokenSource.js

@@ -0,0 +1,45 @@
+export function createDeferredTokenSource() {
+    const queue = [];
+    let closed = false;
+    let closeReason;
+    const waiters = [];
+    const notify = () => {
+        for (const wake of waiters)
+            wake();
+        waiters.length = 0;
+    };
+    const source = {
+        async *[Symbol.asyncIterator]() {
+            while (true) {
+                while (queue.length > 0) {
+                    yield queue.shift();
+                }
+                if (closed) {
+                    if (closeReason === 'interrupted') {
+                        throw new Error('interrupted');
+                    }
+                    return;
+                }
+                await new Promise((resolve) => {
+                    waiters.push(resolve);
+                });
+            }
+        },
+    };
+    return {
+        source,
+        push(delta) {
+            if (closed || delta.length === 0)
+                return;
+            queue.push({ delta });
+            notify();
+        },
+        close(reason = 'complete') {
+            if (closed)
+                return;
+            closed = true;
+            closeReason = reason;
+            notify();
+        },
+    };
+}

package/dist/runtime/channels/streaming/mode.d.ts

@@ -0,0 +1,4 @@
+import type { RunContext } from '../../../types/run-context.js';
+import type { ResolvedNode } from '../../../types/channel.js';
+export type StreamMode = 'token' | 'sentence' | 'turn';
+export declare function resolveStreamMode(ctx: RunContext, node: ResolvedNode): StreamMode;

package/dist/runtime/channels/streaming/mode.js

@@ -0,0 +1,16 @@
+function nodeHasWholeAnswerGroundingGate(_ctx, node) {
+    return node.node.kind === 'reply' && node.node.confidenceGate != null;
+}
+export function resolveStreamMode(ctx, node) {
+    const grans = [
+        ...(ctx.outputProcessors ?? []).map((p) => p.streamGranularity ?? 'turn'),
+        ...(ctx.validationPolicies ?? []).map((p) => p.streamGranularity ?? 'turn'),
+    ];
+    if (nodeHasWholeAnswerGroundingGate(ctx, node))
+        grans.push('turn');
+    if (grans.includes('turn'))
+        return 'turn';
+    if (grans.includes('sentence'))
+        return 'sentence';
+    return 'token';
+}

package/dist/runtime/channels/streaming/speakGated.d.ts

@@ -0,0 +1,26 @@
+import type { TurnControl } from '../../../types/channel.js';
+import type { RunContext } from '../../../types/run-context.js';
+import type { StreamMode } from './mode.js';
+export interface TokenSource {
+    [Symbol.asyncIterator](): AsyncIterator<{
+        delta: string;
+    }>;
+}
+export interface GateOutcome {
+    blocked: boolean;
+    text: string;
+    reason?: string;
+    control?: TurnControl;
+    confidence?: number;
+}
+export declare function speakGated(args: {
+    ctx: RunContext;
+    mode: StreamMode;
+    turnId: string;
+    source: TokenSource;
+    runGate: (fullOrSentence: string, final: boolean) => Promise<GateOutcome>;
+}): Promise<{
+    text: string;
+    control?: TurnControl;
+    confidence?: number;
+}>;

package/dist/runtime/channels/streaming/speakGated.js

@@ -0,0 +1,103 @@
+import { randomUUID } from 'node:crypto';
+import { SentenceAggregator } from './SentenceAggregator.js';
+function emitMessage(ctx, id, text) {
+    ctx.emit({ type: 'text-start', id });
+    ctx.emit({ type: 'text-delta', id, delta: text });
+    ctx.emit({ type: 'text-end', id });
+}
+async function emitBlockedSafeMessage(ctx, turnId, started, outcome) {
+    if (started) {
+        ctx.emit({
+            type: 'text-cancel',
+            id: turnId,
+            reason: outcome.reason ?? 'blocked',
+        });
+    }
+    const safeId = randomUUID();
+    emitMessage(ctx, safeId, outcome.text);
+    return {
+        text: outcome.text,
+        control: outcome.control,
+        confidence: outcome.confidence,
+    };
+}
+export async function speakGated(args) {
+    const { ctx, mode, turnId, source, runGate } = args;
+    if (mode === 'turn') {
+        let full = '';
+        try {
+            for await (const { delta } of source) {
+                full += delta;
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            ctx.emit({ type: 'error', error: message });
+            throw err instanceof Error ? err : new Error(message);
+        }
+        const decision = await runGate(full, true);
+        emitMessage(ctx, turnId, decision.text);
+        return {
+            text: decision.text,
+            control: decision.control,
+            confidence: decision.confidence,
+        };
+    }
+    const agg = new SentenceAggregator();
+    let started = false;
+    let emitted = '';
+    const openOnce = () => {
+        if (!started) {
+            ctx.emit({ type: 'text-start', id: turnId });
+            started = true;
+        }
+    };
+    const emitCleared = (chunk) => {
+        openOnce();
+        ctx.emit({ type: 'text-delta', id: turnId, delta: chunk });
+        emitted += chunk;
+    };
+    const gateSentence = async (sentence, final) => {
+        const decision = await runGate(sentence.trim(), final);
+        if (decision.blocked) {
+            return emitBlockedSafeMessage(ctx, turnId, started, decision);
+        }
+        emitCleared(sentence);
+        return null;
+    };
+    try {
+        for await (const { delta } of source) {
+            if (mode === 'token') {
+                openOnce();
+                ctx.emit({ type: 'text-delta', id: turnId, delta });
+                emitted += delta;
+                continue;
+            }
+            for (const sentence of agg.push(delta)) {
+                const blocked = await gateSentence(sentence, false);
+                if (blocked)
+                    return blocked;
+            }
+        }
+        if (mode === 'sentence') {
+            const tail = agg.flush();
+            if (tail) {
+                const blocked = await gateSentence(tail, true);
+                if (blocked)
+                    return blocked;
+            }
+        }
+        if (started) {
+            ctx.emit({ type: 'text-end', id: turnId });
+        }
+        return { text: emitted };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        ctx.emit({ type: 'error', error: message });
+        if (started) {
+            ctx.emit({ type: 'text-cancel', id: turnId, reason: message });
+        }
+        throw err instanceof Error ? err : new Error(message);
+    }
+}

package/dist/types/channel.d.ts

@@ -31,6 +31,8 @@ export interface TurnResult {
     interrupted?: boolean;
     truncateAt?: number;
     confidence?: number;
+    /** Native realtime post-hoc gate: provider audio already played; gate is advisory only. */
+    gateScope?: 'advisory';
 }
 export type UserSignal = {
     type: 'message';

package/dist/types/processors.d.ts

@@ -37,6 +37,8 @@ export interface OutputProcessor {
     id: string;
     name?: string;
     description?: string;
+    /** Absent ⇒ `turn` (buffered, safe). Streaming is an explicit opt-in by the gate author. */
+    streamGranularity?: 'sentence' | 'turn';
     process: (args: {
         text: string;
         messages: ModelMessage[];
@@ -69,8 +71,19 @@ export interface AgentCapabilityDescriptor {
     doesNotHandle?: string[];
 }
 export type AgentStreamPart = {
+    type: 'text-start';
+    id: string;
+} | {
     type: 'text-delta';
-    text: string;
+    id: string;
+    delta: string;
+} | {
+    type: 'text-end';
+    id: string;
+} | {
+    type: 'text-cancel';
+    id: string;
+    reason: string;
 } | {
     type: 'tool-call';
     toolName: string;

package/dist/types/stream.d.ts

@@ -6,8 +6,19 @@ import type { ChoiceOption } from './selection.js';
  * does not include `{ type: 'interactive' }`.
  */
 export type HarnessStreamPart = {
+    type: 'text-start';
+    id: string;
+} | {
     type: 'text-delta';
-    text: string;
+    id: string;
+    delta: string;
+} | {
+    type: 'text-end';
+    id: string;
+} | {
+    type: 'text-cancel';
+    id: string;
+    reason: string;
 } | {
     type: 'tool-call';
     toolName: string;
@@ -56,6 +67,16 @@ export type HarnessStreamPart = {
     prompt: string;
 } | {
     type: 'turn-end';
+} | {
+    type: 'pipeline-validation-block';
+    rationale: string;
+    userFacingMessage?: string;
+} | {
+    type: 'safety-blocked';
+    moderator: string;
+    rationale: string;
+    userFacingMessage: string;
+    handlerOutcome?: 'queued' | 'connected' | 'failed';
 } | {
     type: 'error';
     error: string;

package/dist/types/voice.d.ts

@@ -216,9 +216,20 @@ export type HarnessStreamPart = {
     type: 'input';
     text: string;
     userId?: string;
+} | {
+    type: 'text-start';
+    id: string;
 } | {
     type: 'text-delta';
-    text: string;
+    id: string;
+    delta: string;
+} | {
+    type: 'text-end';
+    id: string;
+} | {
+    type: 'text-cancel';
+    id: string;
+    reason: string;
 } | {
     type: 'channel-switched';
     from: ChannelId;

package/package.json

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