@kuralle-agents/core 0.12.0 → 0.14.0

package/dist/foundation/DefaultToolExecutor.js

@@ -1,132 +0,0 @@
-import crypto from 'node:crypto';
-import { isRecord } from '../utils/isRecord.js';
-/**
- * Error thrown when a tool execution exceeds the configured timeout.
- */
-export class ToolTimeoutError extends Error {
-    toolName;
-    timeoutMs;
-    constructor(toolName, timeoutMs) {
-        super(`Tool "${toolName}" timeout after ${timeoutMs}ms`);
-        this.name = 'ToolTimeoutError';
-        this.toolName = toolName;
-        this.timeoutMs = timeoutMs;
-    }
-}
-/**
- * Default tool executor extracted from Runtime.wrapToolsWithEnforcement().
- *
- * Handles:
- * - Enforcement checks via ToolEnforcer
- * - Idempotency key generation
- * - Context enrichment (experimental_context)
- * - Error propagation via HookRunner
- */
-export class DefaultToolExecutor {
-    enforcer;
-    hookRunner;
-    memoryService;
-    defaultToolTimeoutMs;
-    constructor(config) {
-        this.enforcer = config.enforcer;
-        this.hookRunner = config.hookRunner;
-        this.memoryService = config.memoryService;
-        this.defaultToolTimeoutMs = config.defaultToolTimeoutMs;
-    }
-    async execute(args) {
-        const { session, agentId, toolName, tool, input, step = 0, turn = 0, toolCallHistory = [], } = args;
-        const toolCallId = args.toolCallId ?? crypto.randomUUID();
-        const idempotencyKey = this.buildIdempotencyKey({
-            sessionId: session.id,
-            agentId,
-            step,
-            toolName,
-            toolCallId,
-        });
-        const callRecord = {
-            toolCallId,
-            toolName,
-            args: input,
-            idempotencyKey,
-            success: true,
-            timestamp: Date.now(),
-        };
-        // Enforcement check
-        const enforcement = await this.enforcer.check(callRecord, {
-            previousCalls: toolCallHistory,
-            currentStep: step,
-            sessionState: session.state ?? {},
-        });
-        if (!enforcement.allowed) {
-            const reason = enforcement.reason ?? 'Tool call blocked by enforcement';
-            callRecord.success = false;
-            callRecord.error = new Error(reason);
-            toolCallHistory.push(callRecord);
-            const runContext = {
-                session,
-                agentId,
-                stepCount: step,
-                totalTokens: 0,
-                handoffStack: [],
-                startTime: Date.now(),
-                consecutiveErrors: 0,
-                toolCallHistory,
-            };
-            await this.hookRunner.onToolError(runContext, callRecord, callRecord.error);
-            throw callRecord.error;
-        }
-        // Build enriched options for the tool's execute function
-        if (!('execute' in tool) || typeof tool.execute !== 'function') {
-            throw new Error(`Tool "${toolName}" does not have an execute function`);
-        }
-        const enrichedOptions = this.withToolExecutionMetadata(undefined, { session, agentId, step, turn, toolName, toolCallId, idempotencyKey });
-        try {
-            const timeoutMs = tool.timeout ??
-                this.defaultToolTimeoutMs ??
-                30_000;
-            const exec = tool.execute.bind(tool);
-            const result = await Promise.race([
-                exec(input, enrichedOptions),
-                new Promise((_, reject) => {
-                    const timer = setTimeout(() => reject(new ToolTimeoutError(toolName, timeoutMs)), timeoutMs);
-                    if (typeof timer === 'object' && timer !== null && 'unref' in timer) {
-                        timer.unref();
-                    }
-                }),
-            ]);
-            return result;
-        }
-        catch (error) {
-            console.error(`[ToolExecutor] Tool execution failed for ${toolName}:`, error);
-            throw error;
-        }
-    }
-    buildIdempotencyKey(args) {
-        return `${args.sessionId}:${args.agentId}:${args.step}:${args.toolName}:${args.toolCallId}`;
-    }
-    withToolExecutionMetadata(options, ctx) {
-        const baseOptions = options ?? {
-            toolCallId: ctx.toolCallId,
-            messages: [],
-        };
-        const existingContext = isRecord(baseOptions.experimental_context)
-            ? baseOptions.experimental_context
-            : {};
-        return {
-            ...baseOptions,
-            toolCallId: ctx.toolCallId,
-            experimental_context: {
-                ...existingContext,
-                session: ctx.session,
-                sessionId: ctx.session.id,
-                agentId: ctx.agentId,
-                step: ctx.step,
-                turn: ctx.turn,
-                toolName: ctx.toolName,
-                toolCallId: ctx.toolCallId,
-                idempotencyKey: ctx.idempotencyKey,
-                memoryService: this.memoryService,
-            },
-        };
-    }
-}

package/dist/foundation/createFoundation.d.ts

@@ -1,32 +0,0 @@
-import type { SessionStore } from '../session/SessionStore.js';
-import type { MemoryService } from '../memory/MemoryService.js';
-import type { EnforcementRule, HarnessHooks } from '../types/index.js';
-import type { ToolExecutor } from './ToolExecutor.js';
-import type { ConversationState } from './ConversationState.js';
-import type { ConversationEventLog } from './ConversationEventLog.js';
-import type { AgentStateController } from './AgentStateController.js';
-/**
- * Configuration for creating a foundation service bundle.
- */
-export interface FoundationConfig {
-    sessionStore?: SessionStore;
-    defaultAgentId?: string;
-    enforcementRules?: EnforcementRule[];
-    hooks?: HarnessHooks;
-    memoryService?: MemoryService;
-}
-/**
- * Bundle of all foundation services. Both Runtime and VoiceEngine
- * compose this to share operational logic.
- */
-export interface Foundation {
-    toolExecutor: ToolExecutor;
-    conversationState: ConversationState;
-    eventLog: ConversationEventLog;
-    agentState: AgentStateController;
-}
-/**
- * Create a foundation service bundle with default implementations.
- * Services can be individually overridden if needed.
- */
-export declare function createFoundation(config?: FoundationConfig): Foundation;

package/dist/foundation/createFoundation.js

@@ -1,33 +0,0 @@
-import { DefaultToolExecutor } from './DefaultToolExecutor.js';
-import { DefaultConversationState } from './DefaultConversationState.js';
-import { DefaultConversationEventLog } from './DefaultConversationEventLog.js';
-import { DefaultAgentStateController } from './DefaultAgentStateController.js';
-import { ToolEnforcer } from '../guards/ToolEnforcer.js';
-import { defaultEnforcementRules } from '../guards/rules.js';
-import { HookRunner } from '../hooks/HookRunner.js';
-import { MemoryStore } from '../session/stores/MemoryStore.js';
-/**
- * Create a foundation service bundle with default implementations.
- * Services can be individually overridden if needed.
- */
-export function createFoundation(config = {}) {
-    const sessionStore = config.sessionStore ?? new MemoryStore();
-    const defaultAgentId = config.defaultAgentId ?? 'default';
-    const enforcer = new ToolEnforcer(config.enforcementRules ?? defaultEnforcementRules);
-    const hookRunner = new HookRunner(config.hooks);
-    return {
-        toolExecutor: new DefaultToolExecutor({
-            enforcer,
-            hookRunner,
-            memoryService: config.memoryService,
-        }),
-        conversationState: new DefaultConversationState({
-            sessionStore,
-            defaultAgentId,
-        }),
-        eventLog: new DefaultConversationEventLog({
-            sessionStore,
-        }),
-        agentState: new DefaultAgentStateController(),
-    };
-}

package/dist/hooks/HookRunner.d.ts

@@ -1,37 +0,0 @@
-import type { HarnessHooks, RunContext, StepResult, ToolCallRecord, HarnessStreamPart, Session, TurnUsage, ConversationOutcomeRecord, TurnEndHookResult, TurnSummary } from '../types/index.js';
-import type { SessionEndMetadata } from '../types/telemetry.js';
-import type { ModelMessage } from 'ai';
-type HookErrorHandler = (hookName: string, error: Error) => void;
-export declare class HookRunner {
-    private hooks;
-    private errorHandler;
-    constructor(hooks?: HarnessHooks, errorHandler?: HookErrorHandler);
-    /** Check if a specific hook is configured. */
-    has(hookName: string): boolean;
-    run<K extends keyof HarnessHooks>(hookName: K, ...args: NonNullable<HarnessHooks[K]> extends (...args: infer P) => unknown ? P : never): Promise<void>;
-    onStart(context: RunContext): Promise<void>;
-    onEnd(context: RunContext, result: {
-        success: boolean;
-        error?: Error;
-    }): Promise<void>;
-    onStepStart(context: RunContext, step: number): Promise<void>;
-    onStepEnd(context: RunContext, step: number, result: StepResult): Promise<void>;
-    onTokensUpdate(context: RunContext, turn: TurnUsage): Promise<void>;
-    onToolCall(context: RunContext, call: ToolCallRecord): Promise<void>;
-    onToolResult(context: RunContext, call: ToolCallRecord): Promise<void>;
-    onToolError(context: RunContext, call: ToolCallRecord, error: Error): Promise<void>;
-    onTurnEnd(context: RunContext, summary: TurnSummary): Promise<TurnEndHookResult | void>;
-    onAgentStart(context: RunContext, agentId: string): Promise<void>;
-    onAgentEnd(context: RunContext, agentId: string): Promise<void>;
-    onHandoff(context: RunContext, from: string, to: string, reason: string): Promise<void>;
-    onError(context: RunContext, error: Error): Promise<void>;
-    onMessage(context: RunContext, message: ModelMessage): Promise<void>;
-    onStreamPart(context: RunContext, part: HarnessStreamPart): Promise<void>;
-    onSessionEnd(session: Session, metadata: SessionEndMetadata): Promise<void>;
-    onConversationEnd(session: Session, outcome: ConversationOutcomeRecord): Promise<void>;
-    merge(additionalHooks: HarnessHooks): void;
-    setHooks(hooks: HarnessHooks): void;
-    getHooks(): HarnessHooks;
-}
-export declare function createHookRunner(hooks?: HarnessHooks, errorHandler?: HookErrorHandler): HookRunner;
-export {};

package/dist/hooks/HookRunner.js

@@ -1,111 +0,0 @@
-const defaultErrorHandler = (hookName, error) => {
-    console.error(`[HookRunner] Hook "${hookName}" failed:`, error.message);
-};
-export class HookRunner {
-    hooks;
-    errorHandler;
-    constructor(hooks = {}, errorHandler) {
-        this.hooks = hooks;
-        this.errorHandler = errorHandler ?? defaultErrorHandler;
-    }
-    /** Check if a specific hook is configured. */
-    has(hookName) {
-        return Boolean(this.hooks[hookName]);
-    }
-    async run(hookName, ...args) {
-        const hook = this.hooks[hookName];
-        if (!hook)
-            return;
-        try {
-            await hook(...args);
-        }
-        catch (error) {
-            this.errorHandler(String(hookName), error);
-        }
-    }
-    async onStart(context) {
-        await this.run('onStart', context);
-    }
-    async onEnd(context, result) {
-        await this.run('onEnd', context, result);
-    }
-    async onStepStart(context, step) {
-        await this.run('onStepStart', context, step);
-    }
-    async onStepEnd(context, step, result) {
-        await this.run('onStepEnd', context, step, result);
-    }
-    async onTokensUpdate(context, turn) {
-        await this.run('onTokensUpdate', context, turn);
-    }
-    async onToolCall(context, call) {
-        await this.run('onToolCall', context, call);
-    }
-    async onToolResult(context, call) {
-        await this.run('onToolResult', context, call);
-    }
-    async onToolError(context, call, error) {
-        await this.run('onToolError', context, call, error);
-    }
-    async onTurnEnd(context, summary) {
-        const hook = this.hooks.onTurnEnd;
-        if (!hook)
-            return;
-        try {
-            return await hook(context, summary);
-        }
-        catch (error) {
-            this.errorHandler('onTurnEnd', error);
-        }
-    }
-    async onAgentStart(context, agentId) {
-        await this.run('onAgentStart', context, agentId);
-    }
-    async onAgentEnd(context, agentId) {
-        await this.run('onAgentEnd', context, agentId);
-    }
-    async onHandoff(context, from, to, reason) {
-        await this.run('onHandoff', context, from, to, reason);
-    }
-    async onError(context, error) {
-        await this.run('onError', context, error);
-    }
-    async onMessage(context, message) {
-        await this.run('onMessage', context, message);
-    }
-    async onStreamPart(context, part) {
-        await this.run('onStreamPart', context, part);
-    }
-    async onSessionEnd(session, metadata) {
-        await this.run('onSessionEnd', session, metadata);
-    }
-    async onConversationEnd(session, outcome) {
-        await this.run('onConversationEnd', session, outcome);
-    }
-    merge(additionalHooks) {
-        const hooks = this.hooks;
-        for (const [key, hook] of Object.entries(additionalHooks)) {
-            const existing = hooks[key];
-            if (!hook)
-                continue;
-            if (existing) {
-                hooks[key] = (async (...args) => {
-                    await existing(...args);
-                    await hook(...args);
-                });
-            }
-            else {
-                hooks[key] = hook;
-            }
-        }
-    }
-    setHooks(hooks) {
-        this.hooks = hooks;
-    }
-    getHooks() {
-        return { ...this.hooks };
-    }
-}
-export function createHookRunner(hooks, errorHandler) {
-    return new HookRunner(hooks, errorHandler);
-}

package/dist/hooks/builtin/logging.d.ts

@@ -1,5 +0,0 @@
-import type { HarnessHooks } from '../../types/index.js';
-type LogLevel = 'debug' | 'info' | 'warn' | 'error';
-export declare const loggingHooks: HarnessHooks;
-export declare function createLoggingHooks(logFn: (level: LogLevel, message: string, data?: Record<string, unknown>) => void): HarnessHooks;
-export {};

package/dist/hooks/builtin/logging.js

@@ -1,98 +0,0 @@
-function log(level, message, context, data) {
-    const entry = {
-        timestamp: new Date().toISOString(),
-        level,
-        component: 'kuralle',
-        message,
-        traceId: context?.session.id,
-        data,
-    };
-    console.log(JSON.stringify(entry));
-}
-export const loggingHooks = {
-    onStart: async (context) => {
-        log('info', 'Agent run started', context, {
-            sessionId: context.session.id,
-            agentId: context.agentId,
-            userId: context.session.userId,
-        });
-    },
-    onEnd: async (context, result) => {
-        const duration = Date.now() - context.startTime;
-        log('info', 'Agent run completed', context, {
-            success: result.success,
-            error: result.error?.message,
-            duration,
-            steps: context.stepCount,
-            tokens: context.totalTokens,
-            handoffs: context.handoffStack.length,
-        });
-    },
-    onStepStart: async (context, step) => {
-        log('debug', `Step ${step} started`, context, { step, agentId: context.agentId });
-    },
-    onStepEnd: async (context, step, result) => {
-        log('debug', `Step ${step} completed`, context, {
-            step,
-            finishReason: result.finishReason,
-            toolCalls: result.toolCalls.length,
-            tokens: result.tokensUsed,
-        });
-    },
-    onToolCall: async (context, call) => {
-        log('info', `Tool called: ${call.toolName}`, context, {
-            toolCallId: call.toolCallId,
-            toolName: call.toolName,
-            args: call.args,
-        });
-    },
-    onToolResult: async (context, call) => {
-        log('debug', `Tool completed: ${call.toolName}`, context, {
-            toolCallId: call.toolCallId,
-            toolName: call.toolName,
-            success: call.success,
-            durationMs: call.durationMs,
-            resultPreview: JSON.stringify(call.result)?.slice(0, 200),
-        });
-    },
-    onToolError: async (context, call, error) => {
-        log('error', `Tool failed: ${call.toolName}`, context, {
-            toolCallId: call.toolCallId,
-            toolName: call.toolName,
-            error: error.message,
-            stack: error.stack,
-        });
-    },
-    onHandoff: async (context, from, to, reason) => {
-        log('info', `Agent handoff: ${from} -> ${to}`, context, { from, to, reason });
-    },
-    onError: async (context, error) => {
-        log('error', 'Agent error', context, {
-            error: error.message,
-            stack: error.stack,
-            step: context.stepCount,
-        });
-    },
-    onAgentStart: async (context, agentId) => {
-        log('info', `Agent started: ${agentId}`, context, { agentId });
-    },
-    onAgentEnd: async (context, agentId) => {
-        log('info', `Agent ended: ${agentId}`, context, { agentId });
-    },
-};
-export function createLoggingHooks(logFn) {
-    const customLog = (level, message, context, data) => {
-        logFn(level, message, {
-            ...data,
-            traceId: context?.session.id,
-            timestamp: new Date().toISOString(),
-        });
-    };
-    return {
-        onStart: async (ctx) => customLog('info', 'Agent started', ctx, { agentId: ctx.agentId }),
-        onEnd: async (ctx, r) => customLog('info', 'Agent ended', ctx, { success: r.success }),
-        onToolCall: async (ctx, c) => customLog('info', `Tool: ${c.toolName}`, ctx, { args: c.args }),
-        onHandoff: async (ctx, f, t, r) => customLog('info', `Handoff: ${f}->${t}`, ctx, { reason: r }),
-        onError: async (ctx, e) => customLog('error', 'Error', ctx, { error: e.message }),
-    };
-}

package/dist/hooks/builtin/metrics.d.ts

@@ -1,7 +0,0 @@
-import type { HarnessHooks } from '../../types/index.js';
-import type { Metrics } from '../../types/index.js';
-import { InMemoryMetricsService } from '../../services/MetricsService.js';
-export { Metrics };
-export declare class InMemoryMetrics extends InMemoryMetricsService implements Metrics {
-}
-export declare function createMetricsHooks(metrics: Metrics): HarnessHooks;

package/dist/hooks/builtin/metrics.js

@@ -1,60 +0,0 @@
-import { InMemoryMetricsService } from '../../services/MetricsService.js';
-// Re-export as alias for compatibility
-export class InMemoryMetrics extends InMemoryMetricsService {
-}
-export function createMetricsHooks(metrics) {
-    const toolStartTimes = new Map();
-    return {
-        onStart: async (context) => {
-            metrics.increment('agent.starts', 1, { agent: context.agentId });
-            metrics.gauge('agent.active', 1);
-        },
-        onEnd: async (context, result) => {
-            const duration = Date.now() - context.startTime;
-            metrics.increment(result.success ? 'agent.success' : 'agent.failure');
-            metrics.gauge('agent.active', -1);
-            metrics.timing('agent.duration', duration);
-            metrics.histogram('agent.steps', context.stepCount);
-            metrics.histogram('agent.tokens', context.totalTokens);
-            metrics.histogram('agent.handoffs', context.handoffStack.length);
-        },
-        onToolCall: async (_context, call) => {
-            metrics.increment('tool.calls', 1, { tool: call.toolName });
-            toolStartTimes.set(call.toolCallId, Date.now());
-        },
-        onToolResult: async (_context, call) => {
-            const startTime = toolStartTimes.get(call.toolCallId);
-            if (startTime) {
-                metrics.timing('tool.duration', Date.now() - startTime, { tool: call.toolName });
-                toolStartTimes.delete(call.toolCallId);
-            }
-            metrics.increment('tool.success', 1, { tool: call.toolName });
-        },
-        onToolError: async (_context, call) => {
-            const startTime = toolStartTimes.get(call.toolCallId);
-            if (startTime) {
-                metrics.timing('tool.duration', Date.now() - startTime, { tool: call.toolName });
-                toolStartTimes.delete(call.toolCallId);
-            }
-            metrics.increment('tool.errors', 1, { tool: call.toolName });
-        },
-        onHandoff: async (_context, from, to) => {
-            metrics.increment('agent.handoffs', 1, { from, to });
-        },
-        onError: async () => {
-            metrics.increment('agent.errors');
-        },
-        onStreamPart: async (_context, part) => {
-            // Capture flow-level metrics emitted as custom stream events
-            if (part.type === 'custom' && typeof part.name === 'string' && part.name.startsWith('flow.')) {
-                const data = part.data;
-                if (data && typeof data.durationMs === 'number') {
-                    metrics.timing(part.name, data.durationMs);
-                }
-                else {
-                    metrics.increment(part.name);
-                }
-            }
-        },
-    };
-}

package/dist/hooks/builtin/observability.d.ts

@@ -1,20 +0,0 @@
-import type { HarnessHooks } from '../../types/index.js';
-import type { Metrics, SessionTrace, TraceStreamEvent } from '../../types/telemetry.js';
-export interface ObservabilityConfig {
-    /** Where to send the final SessionTrace. Default: console. */
-    exporter?: 'console' | 'json' | ((trace: SessionTrace) => Promise<void>);
-    /** Output file for `json` exporter. Default: `./.kuralle-traces/session-<id>.json` */
-    outputPath?: string;
-    /** Include message text in span events (PII risk). Default: false. */
-    includeContent?: boolean;
-    /** Optional metrics service for timings alongside spans. */
-    metrics?: Metrics;
-    /** Service name stored on spans. */
-    serviceName?: string;
-    /**
-     * Optional live trace stream (e.g. Kuralle Studio WebSocket). Fire-and-forget;
-     * keep handlers synchronous or schedule async work without blocking the harness.
-     */
-    traceStream?: (event: TraceStreamEvent) => void;
-}
-export declare function createObservabilityHooks(config?: ObservabilityConfig): HarnessHooks;