@kuralle-agents/core 0.12.0 → 0.14.0

package/dist/hooks/helpers.js

@@ -1,183 +0,0 @@
-import { TracingService } from '../services/TracingService.js';
-import { InMemoryMetricsService } from '../services/MetricsService.js';
-// Legacy Singleton for backward compatibility
-const defaultTracingService = new TracingService();
-let defaultMetricsService = null;
-// Re-export specific legacy functions delegated to services
-export function initTracing(config) {
-    defaultTracingService.init(config);
-}
-export function startSpan(name, attributes, parentSpanId) {
-    return defaultTracingService.startSpan(name, attributes, parentSpanId);
-}
-export function endSpan(span, status, error) {
-    return defaultTracingService.endSpan(span, status, error);
-}
-export function addSpanEvent(span, name, attributes) {
-    defaultTracingService.addSpanEvent(span, name, attributes);
-}
-export function getCurrentSpan() {
-    return defaultTracingService.getCurrentSpan();
-}
-/**
- * Creates tracing hooks.
- * @param service Optional TracingService instance. If not provided, uses the global singleton (legacy).
- */
-export function createTracingHooks(service = defaultTracingService) {
-    return {
-        onAgentStart: async (context, agentId) => {
-            service.startSpan('agent.run', { agentId, sessionId: context.session.id });
-        },
-        onAgentEnd: async (context) => {
-            const span = service.getCurrentSpan();
-            if (span) {
-                service.endSpan(span, 'success');
-            }
-        },
-        onStepStart: async (context, step) => {
-            service.startSpan('agent.step', { step, agentId: context.agentId });
-        },
-        onStepEnd: async (context, step, result) => {
-            const span = service.getCurrentSpan();
-            if (span) {
-                service.endSpan(span, 'success');
-            }
-        },
-        onToolCall: async (context, call) => {
-            service.startSpan('tool.call', {
-                toolName: call.toolName,
-                toolCallId: call.toolCallId,
-            });
-        },
-        onToolResult: async (context, call) => {
-            const span = service.getCurrentSpan();
-            if (span) {
-                service.addSpanEvent(span, 'tool.result', {
-                    success: String(call.success),
-                    durationMs: call.durationMs ?? 0,
-                });
-                service.endSpan(span, call.success ? 'success' : 'error', call.error);
-            }
-        },
-        onHandoff: async (context, from, to, reason) => {
-            service.startSpan('agent.handoff', { from, to, reason });
-            service.endSpan(service.getCurrentSpan(), 'success');
-        },
-        onError: async (context, error) => {
-            const span = service.getCurrentSpan();
-            if (span) {
-                service.endSpan(span, 'error', error);
-            }
-        },
-    };
-}
-// Metrics delegation
-export function createObservabilityMetrics(config = {}) {
-    return new InMemoryMetricsService(config);
-}
-export function initMetrics(metrics) {
-    defaultMetricsService = metrics;
-}
-export function getMetrics() {
-    if (!defaultMetricsService) {
-        throw new Error('Metrics not initialized. Call initMetrics() first.');
-    }
-    return defaultMetricsService;
-}
-export function createObservabilityHooks(service = getMetrics()) {
-    const metrics = service;
-    return {
-        onStart: async (context) => {
-            metrics.increment('run.start', 1, { agent: context.agentId });
-            metrics.gauge('run.active', 1);
-        },
-        onEnd: async (context, result) => {
-            const duration = Date.now() - context.startTime;
-            metrics.increment(result.success ? 'run.success' : 'run.failure');
-            metrics.gauge('run.active', -1);
-            metrics.timing('run.duration', duration);
-            metrics.histogram('run.steps', context.stepCount);
-            metrics.histogram('run.tokens', context.totalTokens);
-            metrics.histogram('run.handoffs', context.handoffStack.length);
-        },
-        onStepStart: async (context, step) => {
-            metrics.increment('step.start', 1, { agent: context.agentId });
-        },
-        onStepEnd: async (context, step, result) => {
-            metrics.increment('step.end', 1, { agent: context.agentId, reason: result.finishReason });
-        },
-        onToolCall: async (context, call) => {
-            metrics.increment('tool.call', 1, { tool: call.toolName });
-        },
-        onToolResult: async (context, call) => {
-            metrics.increment('tool.result', 1, { tool: call.toolName, success: String(call.success) });
-            if (call.durationMs) {
-                metrics.timing('tool.duration', call.durationMs, { tool: call.toolName });
-            }
-        },
-        onToolError: async (context, call) => {
-            metrics.increment('tool.error', 1, { tool: call.toolName });
-        },
-        onHandoff: async (context, from, to) => {
-            metrics.increment('handoff', 1, { from, to });
-        },
-        onError: async () => {
-            metrics.increment('error', 1);
-        },
-    };
-}
-export function captureSessionTelemetry(context, result) {
-    return {
-        sessionId: context.session.id,
-        agentId: context.agentId,
-        startTime: new Date(context.startTime),
-        endTime: new Date(),
-        duration: Date.now() - context.startTime,
-        steps: context.stepCount,
-        tokens: context.totalTokens,
-        toolCalls: context.toolCallHistory.length,
-        errors: context.toolCallHistory.filter(c => !c.success).length,
-        handoffs: context.handoffStack.length,
-        success: result.success,
-    };
-}
-export function createTelemetryHooks() {
-    const sessions = [];
-    return {
-        onStart: async (context) => {
-            sessions.push({
-                sessionId: context.session.id,
-                agentId: context.agentId,
-                startTime: new Date(),
-                steps: 0,
-                tokens: 0,
-                toolCalls: 0,
-                errors: 0,
-                handoffs: 0,
-                success: false,
-            });
-        },
-        onEnd: async (context, result) => {
-            const session = sessions.find(s => s.sessionId === context.session.id);
-            if (session) {
-                session.endTime = new Date();
-                session.duration = Date.now() - context.startTime;
-                session.steps = context.stepCount;
-                session.tokens = context.totalTokens;
-                session.toolCalls = context.toolCallHistory.length;
-                session.errors = context.toolCallHistory.filter(c => !c.success).length;
-                session.handoffs = context.handoffStack.length;
-                session.success = result.success;
-            }
-        },
-        onStepEnd: async (context, step, result) => {
-            const session = sessions.find(s => s.sessionId === context.session.id);
-            if (session) {
-                session.steps = step + 1;
-                session.tokens += result.tokensUsed;
-                session.toolCalls += result.toolCalls.length;
-            }
-        },
-    };
-}
-// Previously removed generateSpanId is now in TracingService

package/dist/hooks/index.d.ts

@@ -1,8 +0,0 @@
-export { HookRunner, createHookRunner } from './HookRunner.js';
-export { loggingHooks, createLoggingHooks } from './builtin/logging.js';
-export { createMetricsHooks, InMemoryMetrics } from './builtin/metrics.js';
-export type { Metrics } from './builtin/metrics.js';
-export { TracingService } from '../services/TracingService.js';
-export { MetricsService, InMemoryMetricsService } from '../services/MetricsService.js';
-export type { TracingConfig, Span, SpanEvent, ObservabilityMetrics, SessionTelemetry, } from '../types/index.js';
-export { initTracing, startSpan, endSpan, addSpanEvent, getCurrentSpan, createTracingHooks, initMetrics, getMetrics, createObservabilityMetrics, createObservabilityHooks, createTelemetryHooks, captureSessionTelemetry, } from './helpers.js';

package/dist/hooks/index.js

@@ -1,6 +0,0 @@
-export { HookRunner, createHookRunner } from './HookRunner.js';
-export { loggingHooks, createLoggingHooks } from './builtin/logging.js';
-export { createMetricsHooks, InMemoryMetrics } from './builtin/metrics.js';
-export { TracingService } from '../services/TracingService.js';
-export { InMemoryMetricsService } from '../services/MetricsService.js';
-export { initTracing, startSpan, endSpan, addSpanEvent, getCurrentSpan, createTracingHooks, initMetrics, getMetrics, createObservabilityMetrics, createObservabilityHooks, createTelemetryHooks, captureSessionTelemetry, } from './helpers.js';

package/dist/realtime/RealtimeAudioClient.d.ts

@@ -1,166 +0,0 @@
-/**
- * RealtimeAudioClient — Transport-agnostic interface for realtime voice AI models.
- *
- * Any model that accepts audio and returns audio + tool calls implements this.
- * Paired with CapabilityHost:
- * - CapabilityHost → agent logic (tools, prompts, flow state)
- * - RealtimeAudioClient → voice transport (audio I/O, tool dispatch)
- *
- * Implementations:
- * - GeminiRealtimeClient (Gemini Live, PCM16 @ 24kHz)
- * - OpenAIRealtimeClient (OpenAI Realtime, native G.711 μ-law @ 8kHz)
- * - LiveKit wraps these via @livekit/agents-plugin-google and @livekit/agents-plugin-openai
- */
-import type { GeminiFunctionDeclaration } from '../capabilities/adapters/gemini.js';
-export interface RealtimeSessionConfig {
-    /** System instruction / prompt for the model. */
-    systemInstruction: string;
-    /** Tool declarations (Gemini format — adapters convert to vendor-specific). */
-    tools: GeminiFunctionDeclaration[];
-    /** Voice preset (e.g., 'Puck', 'Charon', 'marin'). */
-    voice?: string;
-    /** Model identifier (e.g., 'gemini-3.1-flash-live-preview', 'gpt-realtime'). */
-    model?: string;
-    /** Session resumption handle (for reconnect continuity). */
-    resumptionHandle?: string;
-    /** Audio format preferences. */
-    audio?: RealtimeAudioConfig;
-}
-export interface RealtimeAudioConfig {
-    /** Input audio format. Default: 'pcm16'. */
-    inputFormat?: 'pcm16' | 'pcmu' | 'pcma';
-    /** Output audio format. Default: 'pcm16'. */
-    outputFormat?: 'pcm16' | 'pcmu' | 'pcma';
-    /** Input sample rate in Hz. Default varies by vendor (24000 for Gemini, 8000 for OpenAI G.711). */
-    inputSampleRate?: number;
-    /** Output sample rate in Hz. Default varies by vendor. */
-    outputSampleRate?: number;
-}
-export interface RealtimeToolResponse {
-    id: string;
-    name: string;
-    output: unknown;
-}
-/**
- * Capability flags per provider. Declared at construction time; read by
- * orchestration code (VoiceEngine, RealtimeCallWorker, etc.) to adapt
- * behavior to provider limits.
- *
- * Shape mirrors LiveKit's `RealtimeCapabilities` (agents-js
- * /agents/src/llm/realtime.ts:47-58) so plugins can bridge.
- *
- * Optional flags use `undefined = not declared` semantics: an implementation
- * that omits `midSessionToolsUpdate` is treated as "not supported" by consumers
- * that check `if (caps.midSessionToolsUpdate)`. Explicit `false` means the
- * implementor confirmed the provider does not support it.
- */
-export interface RealtimeCapabilities {
-    /** Provider handles turn detection server-side. If false, orchestrator owns it. */
-    turnDetection: boolean;
-    /** Provider emits user (input) transcripts. If false, orchestrator runs STT separately. */
-    userTranscription: boolean;
-    /** Provider supports truncating prior messages mid-session. */
-    messageTruncation: boolean;
-    /** Provider auto-replies after a tool result. If false, orchestrator sends `response.create`. */
-    autoToolReplyGeneration: boolean;
-    /** Provider produces audio output. If false, provider is text-only and needs external TTS. */
-    audioOutput: boolean;
-    /** Provider supports client-driven function calls. */
-    manualFunctionCalls: boolean;
-    /** Mid-session updates — optional because many providers require a full reconnect. */
-    midSessionChatCtxUpdate?: boolean;
-    midSessionInstructionsUpdate?: boolean;
-    midSessionToolsUpdate?: boolean;
-    perResponseToolChoice?: boolean;
-    /**
-     * How this provider recovers conversation context across a WS disconnect.
-     * Drives `withRealtimeVoice`'s reconnect strategy dispatch.
-     *
-     * - `"handle"` — server-side resumption via an opaque token (Gemini Live).
-     * - `"replay"` — client-side chat_ctx replay via `conversation.item.create`
-     *                (OpenAI Realtime, Azure OpenAI, xAI Grok).
-     * - `"none"`   — no recovery; session starts fresh (Workers AI, Phonic, etc.).
-     *
-     * Omitting the field is treated as `"none"` (migration-safe for older
-     * clients that predate this extension).
-     */
-    reconnectStrategy?: 'handle' | 'replay' | 'none';
-}
-export interface RealtimeEventMap {
-    /** Raw PCM audio from the model (send to client/transport). */
-    audio: (data: Uint8Array) => void;
-    /** Transcript of user or assistant speech. */
-    transcript: (text: string, role: 'user' | 'assistant') => void;
-    /** Model wants to call a tool. */
-    'tool-call': (id: string, name: string, args: unknown) => void;
-    /** Model finished speaking for this turn. */
-    'turn-complete': () => void;
-    /** User interrupted the model (barge-in). */
-    interrupted: () => void;
-    /** Connection error. */
-    error: (error: string) => void;
-    /** Connection closed. */
-    disconnected: () => void;
-}
-/**
- * Interface for realtime voice AI model connections.
- *
- * Lifecycle:
- * 1. connect(config) — establish WebSocket, send initial config
- * 2. sendAudio(frame) — stream user audio to model
- * 3. on('tool-call', ...) — handle tool calls from model
- * 4. sendToolResponse(...) — return tool results
- * 5. on('audio', ...) — receive model audio output
- * 6. updateConfig(...) — change prompt/tools mid-session (e.g., on flow transition)
- * 7. disconnect() — close cleanly
- *
- * NOTE: For SDK-based implementations (e.g. `@google/genai`), `session.receive()`
- * is an async iterator that completes after each turn and must be re-entered
- * inside a `while(true)` loop. Raw-wire implementations (fetch()+Upgrade on
- * Cloudflare Workers, direct `ws` WebSocket usage) do not have this quirk; the
- * underlying WebSocket stays open for the session lifetime. Future authors
- * porting this interface to a new transport should be aware that the SDK
- * wrapper and the raw-wire path diverge at this seam.
- */
-export interface RealtimeAudioClient {
-    /**
-     * Capability flags. Static per implementation; declared at construction.
-     * Implementations MUST NOT throw from this accessor.
-     */
-    readonly capabilities: RealtimeCapabilities;
-    /** Short stable identifier for the provider, e.g. `"gemini"`, `"openai"`. */
-    readonly provider: string;
-    /** Model identifier configured for this client, e.g. `"gpt-realtime"`. */
-    readonly model: string;
-    /** Connect to the AI service with initial configuration. */
-    connect(config: RealtimeSessionConfig): Promise<void>;
-    /** Disconnect gracefully. */
-    disconnect(): Promise<void>;
-    /** Send a PCM audio frame to the model. */
-    sendAudio(frame: Uint8Array): void;
-    /** Send tool call results back to the model. */
-    sendToolResponse(responses: RealtimeToolResponse[]): void;
-    /**
-     * Update session configuration mid-call (system prompt, tools).
-     * Used when CapabilityHost signals 'reconfigure' after a flow transition.
-     *
-     * Implementation may:
-     * - Send in-place update (if model supports it)
-     * - Disconnect and reconnect with new config (fallback)
-     * - Use session resumption handle for continuity
-     */
-    updateConfig(config: Partial<RealtimeSessionConfig>): Promise<void>;
-    /**
-     * Trigger a model response after config update.
-     * Optional — not all providers support it.
-     */
-    requestResponse?(instruction?: string): void;
-    /** Check connection health (WebSocket ping). */
-    ping(): Promise<boolean>;
-    /** Subscribe to events from the model. */
-    on<K extends keyof RealtimeEventMap>(event: K, handler: RealtimeEventMap[K]): void;
-    /** Unsubscribe from events. */
-    off<K extends keyof RealtimeEventMap>(event: K, handler: RealtimeEventMap[K]): void;
-    /** Whether currently connected to the model. */
-    readonly connected: boolean;
-}

package/dist/realtime/RealtimeAudioClient.js

@@ -1,14 +0,0 @@
-/**
- * RealtimeAudioClient — Transport-agnostic interface for realtime voice AI models.
- *
- * Any model that accepts audio and returns audio + tool calls implements this.
- * Paired with CapabilityHost:
- * - CapabilityHost → agent logic (tools, prompts, flow state)
- * - RealtimeAudioClient → voice transport (audio I/O, tool dispatch)
- *
- * Implementations:
- * - GeminiRealtimeClient (Gemini Live, PCM16 @ 24kHz)
- * - OpenAIRealtimeClient (OpenAI Realtime, native G.711 μ-law @ 8kHz)
- * - LiveKit wraps these via @livekit/agents-plugin-google and @livekit/agents-plugin-openai
- */
-export {};

package/dist/realtime/RealtimeSessionHandle.d.ts

@@ -1,6 +0,0 @@
-export interface RealtimeSessionHandle {
-    readonly sessionId: string;
-    readonly callId: string;
-    start(): Promise<void>;
-    stop(): Promise<void>;
-}

package/dist/realtime/RealtimeSessionHandle.js

@@ -1 +0,0 @@
-export {};

package/dist/realtime/index.d.ts

@@ -1,2 +0,0 @@
-export type { RealtimeAudioClient, RealtimeCapabilities, RealtimeSessionConfig, RealtimeAudioConfig, RealtimeToolResponse, RealtimeEventMap, } from './RealtimeAudioClient.js';
-export type { RealtimeSessionHandle } from './RealtimeSessionHandle.js';

package/dist/realtime/index.js

@@ -1 +0,0 @@
-export {};

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

@@ -1,31 +0,0 @@
-import type { TurnResult, UserSignal, ResolvedNode } from '../../types/channel.js';
-import type { RunContext } from '../../types/run-context.js';
-import type { ChannelDriver } from '../../types/channel.js';
-import type { DecideNode } from '../../types/flow.js';
-import { buildNodePrompt } from '../../flow/nodeBuilders.js';
-import type { AnyTool } from '../../types/effectTool.js';
-import type { RealtimeSessionConfig } from '../../realtime/RealtimeAudioClient.js';
-import type { RealtimeAudioClient } from '../../realtime/RealtimeAudioClient.js';
-export interface VoiceDriverConfig {
-    client: RealtimeAudioClient;
-    toolDefs?: Record<string, AnyTool>;
-    maxSteps?: number;
-}
-export declare class VoiceDriver implements ChannelDriver {
-    readonly outputCapability: "native-realtime";
-    private readonly client;
-    private readonly toolDefs;
-    private readonly maxSteps;
-    private heardCharCount;
-    private pendingBargeInInput;
-    constructor(config: VoiceDriverConfig);
-    runAgentTurn(node: ResolvedNode, ctx: RunContext): Promise<TurnResult>;
-    runStructured(node: DecideNode, ctx: RunContext): Promise<unknown>;
-    runExtraction(node: ResolvedNode, ctx: RunContext): Promise<TurnResult>;
-    awaitUser(ctx: RunContext): Promise<UserSignal>;
-    reconfigure(config: Partial<RealtimeSessionConfig>): Promise<void>;
-    getHeardCharCount(): number;
-    private collectProviderTurn;
-    private waitForUserTurn;
-}
-export { buildNodePrompt };