@kuralle-agents/core 0.13.0 → 0.15.0

package/dist/foundation/DefaultConversationEventLog.js

@@ -1,205 +0,0 @@
-import crypto from 'node:crypto';
-import { isRecord } from '../utils/isRecord.js';
-/** Working memory key for the runtime event log array. */
-const EVENT_LOG_KEY = 'runtimeEventLog';
-/** Working memory key for accumulated assistant text between flushes. */
-const ASSISTANT_TEXT_KEY = '__ariaAssistantText';
-/** Working memory key for turn tracking. */
-const SESSION_TURN_KEY = '__ariaSessionTurn';
-/** Max event entries before oldest are evicted. */
-const MAX_ENTRIES = 2000;
-/** Stream part types that trigger a checkpoint save. */
-const CHECKPOINT_TYPES = new Set([
-    'tool-result',
-    'tool-error',
-    'flow-transition',
-]);
-/**
- * Default conversation event log extracted from SessionEventManager + Runtime checkpoint logic.
- *
- * Handles:
- * - Recording stream parts into session working memory
- * - Text-delta accumulation and flush on terminal events
- * - Value truncation at depth 5 for safe serialization
- * - Checkpoint determination and persistence
- */
-export class DefaultConversationEventLog {
-    sessionStore;
-    constructor(config) {
-        this.sessionStore = config.sessionStore;
-    }
-    record(context, part) {
-        // Fast path: text-delta only accumulates text — no UUID, no base object
-        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.delta;
-            return;
-        }
-        const base = {
-            id: crypto.randomUUID(),
-            sessionId: context.session.id,
-            agentId: context.agentId,
-            turn: this.getSessionTurn(context.session),
-            timestamp: new Date().toISOString(),
-        };
-        switch (part.type) {
-            case 'input':
-                this.appendEvent(context, { ...base, type: 'user', text: part.text, userId: part.userId });
-                return;
-            case 'tool-call':
-                this.appendEvent(context, {
-                    ...base,
-                    type: 'tool_call',
-                    toolCallId: part.toolCallId,
-                    toolName: part.toolName,
-                    args: this.toEventLogValue(part.args),
-                });
-                return;
-            case 'tool-result':
-                this.appendEvent(context, {
-                    ...base,
-                    type: 'tool_result',
-                    toolCallId: part.toolCallId,
-                    toolName: part.toolName,
-                    result: this.toEventLogValue(part.result),
-                });
-                return;
-            case 'tool-error':
-                this.appendEvent(context, {
-                    ...base,
-                    type: 'tool_error',
-                    toolCallId: part.toolCallId,
-                    toolName: part.toolName,
-                    error: part.error,
-                });
-                return;
-            case 'flow-transition':
-                this.appendEvent(context, {
-                    ...base,
-                    type: 'transition',
-                    kind: 'flow',
-                    from: part.from,
-                    to: part.to,
-                });
-                return;
-            case 'handoff':
-                this.appendEvent(context, {
-                    ...base,
-                    type: 'transition',
-                    kind: 'handoff',
-                    from: part.from,
-                    to: part.to,
-                    reason: part.reason,
-                });
-                return;
-            case 'turn-end':
-                this.flushAssistantText(context, 'turn-end');
-                return;
-            case 'done':
-                this.flushAssistantText(context, 'done');
-                return;
-            case 'error':
-                this.flushAssistantText(context, 'error');
-                return;
-            case 'text-clear':
-                delete context.session.workingMemory[ASSISTANT_TEXT_KEY];
-                return;
-            default:
-                return;
-        }
-    }
-    async checkpoint(session) {
-        const now = new Date();
-        session.updatedAt = now;
-        if (session.metadata) {
-            session.metadata.lastActiveAt = now;
-        }
-        // Strip non-serializable pending extraction promises before save —
-        // they can't survive JSON.stringify (Redis/Postgres) or structuredClone (cache).
-        const pending = session.__pendingExtractions;
-        delete session.__pendingExtractions;
-        await this.sessionStore.save(session);
-        // Restore so in-process turn tracking continues
-        if (pending?.length) {
-            session.__pendingExtractions = pending;
-        }
-    }
-    shouldCheckpoint(part) {
-        return CHECKPOINT_TYPES.has(part.type);
-    }
-    cleanup(session) {
-        delete session.workingMemory[ASSISTANT_TEXT_KEY];
-    }
-    // --- Private helpers (extracted from SessionEventManager) ---
-    getSessionTurn(session) {
-        const value = session.workingMemory[SESSION_TURN_KEY];
-        return typeof value === 'number' && Number.isFinite(value) ? value : 0;
-    }
-    appendEvent(context, entry) {
-        const current = context.session.workingMemory[EVENT_LOG_KEY];
-        let events;
-        if (Array.isArray(current)) {
-            events = current;
-        }
-        else {
-            events = [];
-            context.session.workingMemory[EVENT_LOG_KEY] = events;
-        }
-        events.push(entry);
-        if (events.length > MAX_ENTRIES) {
-            events.splice(0, events.length - MAX_ENTRIES);
-        }
-        // Touch session
-        const now = new Date();
-        context.session.updatedAt = now;
-        if (context.session.metadata) {
-            context.session.metadata.lastActiveAt = now;
-        }
-    }
-    flushAssistantText(context, trigger) {
-        const textRaw = context.session.workingMemory[ASSISTANT_TEXT_KEY];
-        const text = (typeof textRaw === 'string' ? textRaw : '').trim();
-        if (text.length > 0) {
-            this.appendEvent(context, {
-                id: crypto.randomUUID(),
-                sessionId: context.session.id,
-                agentId: context.agentId,
-                turn: this.getSessionTurn(context.session),
-                type: 'assistant_final',
-                trigger,
-                text,
-                timestamp: new Date().toISOString(),
-            });
-        }
-        delete context.session.workingMemory[ASSISTANT_TEXT_KEY];
-    }
-    toEventLogValue(value, depth = 0) {
-        if (value === null || value === undefined) {
-            return value;
-        }
-        if (depth >= 5) {
-            return '[truncated]';
-        }
-        if (value instanceof Date) {
-            return value.toISOString();
-        }
-        if (value instanceof Error) {
-            return { name: value.name, message: value.message };
-        }
-        if (Array.isArray(value)) {
-            return value.slice(0, 50).map(item => this.toEventLogValue(item, depth + 1));
-        }
-        if (typeof value === 'function') {
-            return '[function]';
-        }
-        if (isRecord(value)) {
-            const out = {};
-            for (const [k, v] of Object.entries(value).slice(0, 50)) {
-                out[k] = this.toEventLogValue(v, depth + 1);
-            }
-            return out;
-        }
-        return value;
-    }
-}

package/dist/foundation/DefaultConversationState.d.ts

@@ -1,36 +0,0 @@
-import type { ModelMessage } from 'ai';
-import type { ChannelId, Session, WorkingMemory } from '../types/index.js';
-import type { SessionStore } from '../session/SessionStore.js';
-import type { ConversationState } from './ConversationState.js';
-export interface DefaultConversationStateConfig {
-    sessionStore: SessionStore;
-    defaultAgentId: string;
-}
-/**
- * Default conversation state implementation extracted from Runtime.
- *
- * Handles:
- * - Session load/create/save/delete via SessionStore
- * - Message appending with normalization
- * - Turn counting
- * - Working memory access
- */
-export declare class DefaultConversationState implements ConversationState {
-    private sessionStore;
-    private defaultAgentId;
-    constructor(config: DefaultConversationStateConfig);
-    load(sessionId: string, userId?: string): Promise<Session>;
-    save(session: Session): Promise<void>;
-    delete(sessionId: string): Promise<void>;
-    workingMemory(session: Session): WorkingMemory;
-    appendUserMessage(session: Session, text: string): void;
-    appendAssistantMessage(session: Session, text: string): void;
-    appendMessage(session: Session, message: ModelMessage): void;
-    getSessionTurn(session: Session): number;
-    bumpSessionTurn(session: Session): number;
-    touchSession(session: Session): void;
-    createSession(id: string, defaultAgentId: string, userId?: string, opts?: {
-        channelId?: ChannelId;
-        conversationId?: string;
-    }): Session;
-}

package/dist/foundation/DefaultConversationState.js

@@ -1,103 +0,0 @@
-import { SessionWorkingMemory } from '../runtime/WorkingMemory.js';
-import { normalizeModelMessage } from '../utils/messageNormalization.js';
-/** Internal working memory key for turn tracking. */
-const SESSION_TURN_KEY = '__ariaSessionTurn';
-/**
- * Default conversation state implementation extracted from Runtime.
- *
- * Handles:
- * - Session load/create/save/delete via SessionStore
- * - Message appending with normalization
- * - Turn counting
- * - Working memory access
- */
-export class DefaultConversationState {
-    sessionStore;
-    defaultAgentId;
-    constructor(config) {
-        this.sessionStore = config.sessionStore;
-        this.defaultAgentId = config.defaultAgentId;
-    }
-    async load(sessionId, userId) {
-        const existing = await this.sessionStore.get(sessionId);
-        if (existing) {
-            return existing;
-        }
-        return this.createSession(sessionId, this.defaultAgentId, userId);
-    }
-    async save(session) {
-        this.touchSession(session);
-        await this.sessionStore.save(session);
-    }
-    async delete(sessionId) {
-        await this.sessionStore.delete(sessionId);
-    }
-    workingMemory(session) {
-        return new SessionWorkingMemory(session);
-    }
-    appendUserMessage(session, text) {
-        const message = {
-            role: 'user',
-            content: [{ type: 'text', text }],
-        };
-        this.appendMessage(session, message);
-    }
-    appendAssistantMessage(session, text) {
-        const message = {
-            role: 'assistant',
-            content: [{ type: 'text', text }],
-        };
-        this.appendMessage(session, message);
-    }
-    appendMessage(session, message) {
-        const normalized = normalizeModelMessage(message);
-        if (normalized) {
-            session.messages.push(normalized);
-            this.touchSession(session);
-        }
-    }
-    getSessionTurn(session) {
-        const value = session.workingMemory[SESSION_TURN_KEY];
-        return typeof value === 'number' && Number.isFinite(value) ? value : 0;
-    }
-    bumpSessionTurn(session) {
-        const next = this.getSessionTurn(session) + 1;
-        session.workingMemory[SESSION_TURN_KEY] = next;
-        this.touchSession(session);
-        return next;
-    }
-    touchSession(session) {
-        const now = new Date();
-        session.updatedAt = now;
-        if (session.metadata) {
-            session.metadata.lastActiveAt = now;
-        }
-    }
-    createSession(id, defaultAgentId, userId, opts) {
-        const now = new Date();
-        const channelId = opts?.channelId ?? 'web';
-        const conversationId = opts?.conversationId ?? id;
-        return {
-            id,
-            conversationId,
-            channelId,
-            userId,
-            messages: [],
-            createdAt: now,
-            updatedAt: now,
-            workingMemory: {},
-            currentAgent: defaultAgentId,
-            activeAgentId: defaultAgentId,
-            state: {},
-            metadata: {
-                createdAt: now,
-                lastActiveAt: now,
-                totalTokens: 0,
-                totalSteps: 0,
-                handoffHistory: [],
-            },
-            agentStates: {},
-            handoffHistory: [],
-        };
-    }
-}

package/dist/foundation/DefaultToolExecutor.d.ts

@@ -1,57 +0,0 @@
-import type { Session, ToolCallRecord } from '../types/index.js';
-import type { ToolExecutor, ExecutableTool } from './ToolExecutor.js';
-import type { ToolEnforcer } from '../guards/ToolEnforcer.js';
-import type { HookRunner } from '../hooks/HookRunner.js';
-import type { MemoryService } from '../memory/MemoryService.js';
-export interface DefaultToolExecutorConfig {
-    enforcer: ToolEnforcer;
-    hookRunner: HookRunner;
-    memoryService?: MemoryService;
-    /** Default timeout in milliseconds for tool execution. Defaults to 30000 (30s). */
-    defaultToolTimeoutMs?: number;
-}
-/**
- * Error thrown when a tool execution exceeds the configured timeout.
- */
-export declare class ToolTimeoutError extends Error {
-    readonly toolName: string;
-    readonly timeoutMs: number;
-    constructor(toolName: string, timeoutMs: number);
-}
-/**
- * Default tool executor extracted from Runtime.wrapToolsWithEnforcement().
- *
- * Handles:
- * - Enforcement checks via ToolEnforcer
- * - Idempotency key generation
- * - Context enrichment (experimental_context)
- * - Error propagation via HookRunner
- */
-export declare class DefaultToolExecutor implements ToolExecutor {
-    private enforcer;
-    private hookRunner;
-    private memoryService?;
-    private defaultToolTimeoutMs?;
-    constructor(config: DefaultToolExecutorConfig);
-    execute(args: {
-        session: Session;
-        userId?: string;
-        agentId: string;
-        toolName: string;
-        tool: ExecutableTool;
-        input: unknown;
-        toolCallId?: string;
-        abortSignal?: AbortSignal;
-        step?: number;
-        turn?: number;
-        toolCallHistory?: ToolCallRecord[];
-    }): Promise<unknown>;
-    buildIdempotencyKey(args: {
-        sessionId: string;
-        agentId: string;
-        step: number;
-        toolName: string;
-        toolCallId: string;
-    }): string;
-    private withToolExecutionMetadata;
-}

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 {};