@kuralle-agents/core 0.13.0 → 0.14.0

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;