@kuralle-agents/core 0.13.0 → 0.14.0

package/dist/runtime/channels/VoiceDriver.js

@@ -1,321 +0,0 @@
-import { runSilentExtraction } from './extractionTurn.js';
-import { resolveStructuredDecide } from '../../flow/choiceMatch.js';
-import { buildNodePrompt, resolveInstructions, composeSystem } from '../../flow/nodeBuilders.js';
-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 {
-    outputCapability = 'native-realtime';
-    client;
-    toolDefs;
-    maxSteps;
-    heardCharCount = 0;
-    pendingBargeInInput = null;
-    constructor(config) {
-        this.client = config.client;
-        this.toolDefs = config.toolDefs ?? {};
-        this.maxSteps = config.maxSteps ?? 5;
-    }
-    async runAgentTurn(node, ctx) {
-        const replyNode = node.node;
-        if (replyNode.kind !== 'reply') {
-            throw new Error(`VoiceDriver.runAgentTurn expects a reply node, got ${replyNode.kind}`);
-        }
-        const preTurn = await applyPreTurnPolicies(ctx);
-        if (!preTurn.proceed) {
-            const blocked = preTurn.blockedMessage ?? 'Input blocked by guardrails';
-            ctx.emit({
-                type: 'safety-blocked',
-                moderator: preTurn.blockedBy ?? 'input-guardrails',
-                rationale: preTurn.blockedReason ?? 'input blocked',
-                userFacingMessage: 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: [] };
-        }
-        const scope = resolveNodeGatherScope(replyNode, ctx.runState.state, ctx.runState.messages);
-        const gather = await runGatherPhase(ctx, scope);
-        const out = { text: '', toolResults: [] };
-        const nodeSystem = node.prompt || buildNodePrompt(replyNode, ctx.runState.state);
-        const baseSystem = composeSystem(ctx.baseInstructions, nodeSystem, ctx.runState.state, ctx.skillPrompt, ctx.workingMemoryPrompt);
-        const system = appendGatherBlocks(baseSystem, [gather.retrievalBlock, gather.memoryBlock]);
-        const geminiTools = resolveVoiceGeminiTools(node, { ...this.toolDefs, ...(ctx.globalTools ?? {}), ...(ctx.workingMemoryTools ?? {}) }, { 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, 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);
-                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;
-            }
-            if (out.toolResults.length === 0 || outcome === 'complete') {
-                break;
-            }
-        }
-        transcript.close('complete');
-        const spoken = await speakPromise;
-        out.text = spoken.text;
-        // Preserve host-control raised during provider tool execution (enter_flow /
-        // transfer_to_agent); the post-hoc gate must not clobber it (else native
-        // realtime silently drops valid routing). Same fix as TextDriver.
-        out.control = spoken.control ?? out.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;
-    }
-    async runStructured(node, ctx) {
-        const system = composeSystem(ctx.baseInstructions, resolveInstructions(node.instructions, ctx.runState.state), ctx.runState.state, ctx.skillPrompt, ctx.workingMemoryPrompt);
-        return resolveStructuredDecide(node, ctx, system);
-    }
-    // Non-speaking collect extraction: uses the shared text-model extraction path
-    // rather than the realtime audio provider, so the agent never SPEAKS during
-    // field collection (which is where ungrounded narration leaked). Identical
-    // behavior to TextDriver — voice and text emit the same structural events; the
-    // user-facing question is the deterministic CollectNode.ask, synthesized after.
-    runExtraction(node, ctx) {
-        return runSilentExtraction(node, ctx, ctx.controlModel, resolveMaxSteps(ctx.limits, this.maxSteps));
-    }
-    async awaitUser(ctx) {
-        if (this.pendingBargeInInput != null) {
-            const input = this.pendingBargeInInput;
-            this.pendingBargeInInput = null;
-            return { type: 'message', input };
-        }
-        const input = await this.waitForUserTurn(ctx);
-        return { type: 'message', input };
-    }
-    async reconfigure(config) {
-        await this.client.updateConfig(config);
-    }
-    getHeardCharCount() {
-        return this.heardCharCount;
-    }
-    async collectProviderTurn(ctx, out, triggerResponse, toolCallsMade, localTools, transcript) {
-        return new Promise((resolve, reject) => {
-            let assistantText = '';
-            let settled = false;
-            let sawInterrupt = false;
-            const finish = (outcome) => {
-                if (settled)
-                    return;
-                settled = true;
-                cleanup();
-                resolve({ outcome, assistantText });
-            };
-            const fail = (error) => {
-                if (settled)
-                    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;
-                }
-            };
-            const onToolCall = (id, name, args) => {
-                void (async () => {
-                    ctx.emit({ type: 'tool-call', toolName: name, args, toolCallId: id });
-                    const { result: toolResult, control, failed } = await executeModelToolCall(ctx, { toolName: name, input: args, toolCallId: id }, {
-                        ...ctx.globalTools,
-                        ...(ctx.workingMemoryTools ?? {}),
-                        ...localTools,
-                    });
-                    out.toolResults.push({ name, args, result: toolResult, toolCallId: id });
-                    toolCallsMade.push({
-                        toolCallId: id,
-                        toolName: name,
-                        args,
-                        result: toolResult,
-                        success: !failed,
-                        timestamp: Date.now(),
-                    });
-                    out.control ??= control;
-                    ctx.emit({ type: 'tool-result', toolName: name, result: toolResult, toolCallId: id });
-                    this.client.sendToolResponse([{ id, name, output: toolResult }]);
-                })();
-            };
-            const onTurnComplete = () => {
-                finish(sawInterrupt ? 'interrupted' : 'complete');
-            };
-            const onInterrupted = () => {
-                sawInterrupt = true;
-                out.truncateAt = this.heardCharCount;
-            };
-            const onError = (error) => {
-                ctx.emit({ type: 'error', error });
-                fail(new Error(error));
-            };
-            const onAbort = () => {
-                sawInterrupt = true;
-                out.truncateAt = this.heardCharCount;
-                finish('interrupted');
-            };
-            const cleanup = () => {
-                this.client.off('transcript', onTranscript);
-                this.client.off('tool-call', onToolCall);
-                this.client.off('turn-complete', onTurnComplete);
-                this.client.off('interrupted', onInterrupted);
-                this.client.off('error', onError);
-                ctx.bargeIn?.removeEventListener('abort', onAbort);
-                ctx.abortSignal?.removeEventListener('abort', onAbort);
-            };
-            this.client.on('transcript', onTranscript);
-            this.client.on('tool-call', onToolCall);
-            this.client.on('turn-complete', onTurnComplete);
-            this.client.on('interrupted', onInterrupted);
-            this.client.on('error', onError);
-            ctx.bargeIn?.addEventListener('abort', onAbort, { once: true });
-            ctx.abortSignal?.addEventListener('abort', onAbort, { once: true });
-            if (triggerResponse && this.client.requestResponse) {
-                this.client.requestResponse();
-            }
-        });
-    }
-    waitForUserTurn(_ctx) {
-        return new Promise((resolve, reject) => {
-            let userText = '';
-            let settled = false;
-            const finish = (text) => {
-                if (settled)
-                    return;
-                settled = true;
-                cleanup();
-                resolve(text);
-            };
-            const fail = (error) => {
-                if (settled)
-                    return;
-                settled = true;
-                cleanup();
-                reject(error);
-            };
-            const onTranscript = (text, role) => {
-                if (role === 'user') {
-                    userText += text;
-                }
-            };
-            const onTurnComplete = () => {
-                finish(userText);
-            };
-            const onError = (error) => {
-                fail(new Error(error));
-            };
-            const cleanup = () => {
-                this.client.off('transcript', onTranscript);
-                this.client.off('turn-complete', onTurnComplete);
-                this.client.off('error', onError);
-            };
-            this.client.on('transcript', onTranscript);
-            this.client.on('turn-complete', onTurnComplete);
-            this.client.on('error', onError);
-        });
-    }
-}
-function truncateToHeard(text, heardChars) {
-    if (heardChars <= 0) {
-        return '';
-    }
-    if (heardChars >= text.length) {
-        return text;
-    }
-    const truncated = text.slice(0, heardChars);
-    const lastSpace = truncated.lastIndexOf(' ');
-    if (lastSpace > heardChars * 0.6) {
-        return truncated.slice(0, lastSpace);
-    }
-    return truncated;
-}
-export { buildNodePrompt };

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

@@ -1,9 +0,0 @@
-import type { GeminiFunctionDeclaration } from '../../capabilities/adapters/gemini.js';
-import type { ResolvedNode } from '../../types/channel.js';
-import type { AnyTool } from '../../types/effectTool.js';
-import { buildToolSet } from '../../tools/effect/defineTool.js';
-export declare function v2ToolsToGemini(tools: Record<string, AnyTool>): GeminiFunctionDeclaration[];
-export declare function resolveVoiceGeminiTools(resolved: ResolvedNode, toolDefs: Record<string, AnyTool>, options?: {
-    siloFlowControl?: boolean;
-}): GeminiFunctionDeclaration[];
-export { buildToolSet };

package/dist/runtime/channels/voiceTools.js

@@ -1,51 +0,0 @@
-import { z } from 'zod';
-import { toGeminiDeclarations } from '../../capabilities/adapters/gemini.js';
-import { buildToolSet } from '../../tools/effect/defineTool.js';
-import { isFlowTransitionControlTool } from '../../flow/flowControlTools.js';
-function toolToDeclaration(name, tool) {
-    return {
-        name: tool.name || name,
-        description: tool.description,
-        parameters: tool.input ?? z.object({}),
-        execute: async () => ({}),
-    };
-}
-export function v2ToolsToGemini(tools) {
-    const declarations = Object.entries(tools).map(([name, tool]) => toolToDeclaration(name, tool));
-    return toGeminiDeclarations(declarations);
-}
-export function resolveVoiceGeminiTools(resolved, toolDefs, options) {
-    const siloFlowControl = options?.siloFlowControl === true;
-    const merged = { ...toolDefs, ...(resolved.localTools ?? {}) };
-    const fromNode = toolSetToEffectTools(resolved.tools);
-    for (const [name, tool] of Object.entries(fromNode)) {
-        if (siloFlowControl && isFlowTransitionControlTool(name)) {
-            continue;
-        }
-        if (!merged[name]) {
-            merged[name] = tool;
-        }
-    }
-    if (siloFlowControl) {
-        for (const name of Object.keys(merged)) {
-            if (isFlowTransitionControlTool(name)) {
-                delete merged[name];
-            }
-        }
-    }
-    return v2ToolsToGemini(merged);
-}
-function toolSetToEffectTools(tools) {
-    const out = {};
-    for (const [name, aiTool] of Object.entries(tools)) {
-        const spec = aiTool;
-        out[name] = {
-            name,
-            description: spec.description ?? name,
-            input: spec.inputSchema,
-            execute: async () => ({}),
-        };
-    }
-    return out;
-}
-export { buildToolSet };

package/dist/tools/errorHandling.d.ts

@@ -1,35 +0,0 @@
-export interface ToolErrorConfig<T = unknown> {
-    maxRetries?: number;
-    retryDelayMs?: number;
-    fallbackValue?: T;
-    onError?: (error: Error, attempt: number) => Promise<void>;
-    shouldRetry?: (error: Error) => boolean;
-}
-export interface ToolResult<T = unknown> {
-    success: boolean;
-    data?: T;
-    error?: Error;
-    attempts: number;
-    totalTimeMs: number;
-}
-export declare function withErrorHandling<T, Args extends unknown[], R = Awaited<T>>(fn: (...args: Args) => T, config?: ToolErrorConfig<R>): (...args: Args) => Promise<ToolResult<R>>;
-export declare function executeWithRetry<T>(fn: () => Promise<T>, config?: {
-    maxRetries?: number;
-    delayMs?: number;
-    backoffMultiplier?: number;
-    maxDelayMs?: number;
-    onRetry?: (error: Error, attempt: number) => void;
-}): Promise<T>;
-export declare function createCircuitBreaker<T, Args extends unknown[]>(fn: (...args: Args) => Promise<T>, config?: {
-    failureThreshold?: number;
-    resetTimeoutMs?: number;
-}): (...args: Args) => Promise<T>;
-export declare function isPermanentError(error: Error): boolean;
-export declare class CircuitOpenError extends Error {
-    constructor(message: string);
-}
-export declare function isCircuitOpenError(error: unknown): error is CircuitOpenError;
-export declare class ToolTimeoutError extends Error {
-    constructor(message?: string);
-}
-export declare function withTimeout<T>(fn: () => Promise<T>, timeoutMs: number, error?: Error): Promise<T>;

package/dist/tools/errorHandling.js

@@ -1,145 +0,0 @@
-export function withErrorHandling(fn, config = {}) {
-    const { maxRetries = 3, retryDelayMs = 1000, fallbackValue, onError, shouldRetry = (e) => !isPermanentError(e), } = config;
-    return async (...args) => {
-        const startTime = Date.now();
-        let lastError;
-        let attempts = 0;
-        while (attempts <= maxRetries) {
-            attempts++;
-            try {
-                const result = await fn(...args);
-                return {
-                    success: true,
-                    data: result,
-                    attempts,
-                    totalTimeMs: Date.now() - startTime,
-                };
-            }
-            catch (error) {
-                lastError = error;
-                if (onError) {
-                    await onError(lastError, attempts);
-                }
-                if (attempts <= maxRetries && shouldRetry(lastError)) {
-                    await sleep(retryDelayMs * attempts);
-                }
-                else {
-                    break;
-                }
-            }
-        }
-        return {
-            success: false,
-            error: lastError,
-            attempts,
-            totalTimeMs: Date.now() - startTime,
-            data: fallbackValue,
-        };
-    };
-}
-export async function executeWithRetry(fn, config = {}) {
-    const { maxRetries = 3, delayMs = 1000, backoffMultiplier = 2, maxDelayMs = 10000, onRetry, } = config;
-    let lastError;
-    let currentDelay = delayMs;
-    for (let attempt = 1; attempt <= maxRetries + 1; attempt++) {
-        try {
-            return await fn();
-        }
-        catch (error) {
-            lastError = error;
-            if (isPermanentError(lastError) || attempt > maxRetries) {
-                throw lastError;
-            }
-            if (onRetry) {
-                onRetry(lastError, attempt);
-            }
-            await sleep(currentDelay);
-            currentDelay = Math.min(currentDelay * backoffMultiplier, maxDelayMs);
-        }
-    }
-    throw lastError;
-}
-export function createCircuitBreaker(fn, config = {}) {
-    const { failureThreshold = 5, resetTimeoutMs = 30000, } = config;
-    let failures = 0;
-    let lastFailureTime;
-    let state = 'CLOSED';
-    return async (...args) => {
-        const now = Date.now();
-        if (state === 'OPEN') {
-            if (lastFailureTime && now - lastFailureTime >= resetTimeoutMs) {
-                state = 'HALF_OPEN';
-            }
-            else {
-                throw new CircuitOpenError('Circuit breaker is open');
-            }
-        }
-        try {
-            const result = await fn(...args);
-            if (state === 'HALF_OPEN') {
-                state = 'CLOSED';
-                failures = 0;
-            }
-            else {
-                failures = 0; // Success in CLOSED state resets failure count
-            }
-            return result;
-        }
-        catch (error) {
-            failures++;
-            lastFailureTime = now;
-            if (state === 'HALF_OPEN' || failures >= failureThreshold) {
-                state = 'OPEN';
-            }
-            throw error;
-        }
-    };
-}
-export function isPermanentError(error) {
-    const permanentErrors = [
-        'not found',
-        'invalid',
-        'unauthorized',
-        'forbidden',
-        'not implemented',
-        'deprecated',
-        'already exists',
-        'permission denied',
-    ];
-    const message = error.message.toLowerCase();
-    return permanentErrors.some((e) => message.includes(e));
-}
-export class CircuitOpenError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'CircuitOpenError';
-    }
-}
-export function isCircuitOpenError(error) {
-    return error instanceof CircuitOpenError;
-}
-export class ToolTimeoutError extends Error {
-    constructor(message = 'Tool execution timed out') {
-        super(message);
-        this.name = 'ToolTimeoutError';
-    }
-}
-export async function withTimeout(fn, timeoutMs, error) {
-    let timer;
-    const timeoutPromise = new Promise((_, reject) => {
-        timer = setTimeout(() => {
-            reject(error ?? new ToolTimeoutError());
-        }, timeoutMs);
-    });
-    try {
-        return await Promise.race([fn(), timeoutPromise]);
-    }
-    finally {
-        if (timer) {
-            clearTimeout(timer);
-        }
-    }
-}
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}