@action-llama/action-llama 0.15.0 → 0.16.0

package/dist/shared/persistence/backends/sqlite.js

@@ -0,0 +1,250 @@
+/**
+ * SQLite backend for unified persistence layer.
+ *
+ * Implements the PersistenceBackend interface with SQLite storage,
+ * combining key-value operations, event sourcing, and query capabilities
+ * in a single database with optimized indexes and transaction support.
+ */
+import Database from "better-sqlite3";
+import { mkdirSync } from "fs";
+import { dirname } from "path";
+import { randomUUID } from "crypto";
+export class SqliteBackend {
+    dbPath;
+    db;
+    stmts = {};
+    sweepTimer;
+    transactionDepth = 0;
+    constructor(dbPath) {
+        this.dbPath = dbPath;
+        if (dbPath !== ":memory:") {
+            mkdirSync(dirname(dbPath), { recursive: true });
+        }
+        this.db = new Database(dbPath);
+        this.db.pragma("journal_mode = WAL");
+        this.db.pragma("synchronous = NORMAL");
+        this.db.pragma("cache_size = 1000");
+        this.db.pragma("temp_store = memory");
+    }
+    async init() {
+        // Create tables
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS kv_store (
+        namespace TEXT NOT NULL,
+        key TEXT NOT NULL,
+        value TEXT NOT NULL,
+        expires_at INTEGER,
+        created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
+        updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
+        PRIMARY KEY (namespace, key)
+      )
+    `);
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS events (
+        id TEXT PRIMARY KEY,
+        stream TEXT NOT NULL,
+        type TEXT NOT NULL,
+        data TEXT NOT NULL,
+        metadata TEXT,
+        timestamp INTEGER NOT NULL,
+        version INTEGER NOT NULL DEFAULT 1,
+        sequence INTEGER NOT NULL
+      )
+    `);
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS snapshots (
+        stream TEXT NOT NULL,
+        type TEXT NOT NULL,
+        data TEXT NOT NULL,
+        event_id TEXT NOT NULL,
+        created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
+        PRIMARY KEY (stream, type)
+      )
+    `);
+        // Create indexes
+        this.db.exec("CREATE INDEX IF NOT EXISTS idx_kv_expires ON kv_store(expires_at) WHERE expires_at IS NOT NULL");
+        this.db.exec("CREATE INDEX IF NOT EXISTS idx_kv_namespace ON kv_store(namespace)");
+        this.db.exec("CREATE INDEX IF NOT EXISTS idx_events_stream ON events(stream, sequence)");
+        this.db.exec("CREATE INDEX IF NOT EXISTS idx_events_type ON events(stream, type, timestamp)");
+        this.db.exec("CREATE INDEX IF NOT EXISTS idx_events_timestamp ON events(stream, timestamp)");
+        this.db.exec("CREATE INDEX IF NOT EXISTS idx_snapshots_stream ON snapshots(stream)");
+        // Prepare statements
+        this.stmts = {
+            // Key-value operations
+            kvGet: this.db.prepare(`
+        SELECT value FROM kv_store 
+        WHERE namespace = ? AND key = ? AND (expires_at IS NULL OR expires_at > ?)
+      `),
+            kvSet: this.db.prepare(`
+        INSERT OR REPLACE INTO kv_store (namespace, key, value, expires_at, updated_at) 
+        VALUES (?, ?, ?, ?, ?)
+      `),
+            kvDelete: this.db.prepare("DELETE FROM kv_store WHERE namespace = ? AND key = ?"),
+            kvDeleteAll: this.db.prepare("DELETE FROM kv_store WHERE namespace = ?"),
+            kvList: this.db.prepare(`
+        SELECT key, value FROM kv_store 
+        WHERE namespace = ? AND (expires_at IS NULL OR expires_at > ?)
+        ORDER BY key
+      `),
+            // Event operations
+            eventAppend: this.db.prepare(`
+        INSERT INTO events (id, stream, type, data, metadata, timestamp, version, sequence)
+        VALUES (?, ?, ?, ?, ?, ?, ?, (
+          SELECT COALESCE(MAX(sequence), 0) + 1 FROM events WHERE stream = ?
+        ))
+      `),
+            eventReplay: this.db.prepare(`
+        SELECT id, stream, type, data, metadata, timestamp, version, sequence
+        FROM events 
+        WHERE stream = ?
+          AND (? IS NULL OR type = ?)
+          AND (? IS NULL OR timestamp >= ?)
+          AND (? IS NULL OR timestamp < ?)
+        ORDER BY sequence ASC
+        LIMIT ? OFFSET ?
+      `),
+            eventCount: this.db.prepare(`
+        SELECT COUNT(*) as count FROM events 
+        WHERE stream = ?
+          AND (? IS NULL OR type = ?)
+          AND (? IS NULL OR timestamp >= ?)
+          AND (? IS NULL OR timestamp < ?)
+      `),
+            eventListStreams: this.db.prepare("SELECT DISTINCT stream FROM events ORDER BY stream"),
+            // Snapshot operations
+            snapshotGet: this.db.prepare("SELECT data FROM snapshots WHERE stream = ? AND type = ?"),
+            snapshotSet: this.db.prepare(`
+        INSERT OR REPLACE INTO snapshots (stream, type, data, event_id, created_at)
+        VALUES (?, ?, ?, ?, ?)
+      `),
+            // Cleanup
+            sweep: this.db.prepare("DELETE FROM kv_store WHERE expires_at IS NOT NULL AND expires_at <= ?"),
+        };
+        // Start periodic cleanup of expired KV entries
+        this.sweepTimer = setInterval(() => this.sweep(), 60_000);
+        if (this.sweepTimer.unref)
+            this.sweepTimer.unref();
+    }
+    // Key-value operations
+    async kvGet(namespace, key) {
+        const row = this.stmts.kvGet.get(namespace, key, Date.now());
+        return row ? JSON.parse(row.value) : null;
+    }
+    async kvSet(namespace, key, value, ttlMs) {
+        const expiresAt = ttlMs ? Date.now() + ttlMs : null;
+        const now = Date.now();
+        this.stmts.kvSet.run(namespace, key, JSON.stringify(value), expiresAt, now);
+    }
+    async kvDelete(namespace, key) {
+        this.stmts.kvDelete.run(namespace, key);
+    }
+    async kvDeleteAll(namespace) {
+        this.stmts.kvDeleteAll.run(namespace);
+    }
+    async kvList(namespace) {
+        const rows = this.stmts.kvList.all(namespace, Date.now());
+        return rows.map(row => ({ key: row.key, value: JSON.parse(row.value) }));
+    }
+    // Event operations
+    async eventAppend(stream, event) {
+        const id = randomUUID();
+        const timestamp = Date.now();
+        this.stmts.eventAppend.run(id, stream, event.type, JSON.stringify(event.data), event.metadata ? JSON.stringify(event.metadata) : null, timestamp, event.version, stream // for the sequence subquery
+        );
+        return {
+            id,
+            timestamp,
+            type: event.type,
+            data: event.data,
+            metadata: event.metadata,
+            version: event.version,
+        };
+    }
+    async *eventReplay(stream, query) {
+        const type = query?.type || null;
+        const from = query?.from || null;
+        const to = query?.to || null;
+        const limit = Math.min(query?.limit || 1000, 10000); // Cap at 10k for safety
+        const offset = query?.offset || 0;
+        const rows = this.stmts.eventReplay.all(stream, type, type, from, from, to, to, limit, offset);
+        for (const row of rows) {
+            yield {
+                id: row.id,
+                type: row.type,
+                data: JSON.parse(row.data),
+                metadata: row.metadata ? JSON.parse(row.metadata) : undefined,
+                timestamp: row.timestamp,
+                version: row.version,
+            };
+        }
+    }
+    async eventGetSnapshot(stream, type) {
+        const row = this.stmts.snapshotGet.get(stream, type);
+        return row ? JSON.parse(row.data) : null;
+    }
+    async eventSaveSnapshot(stream, type, data, eventId) {
+        const now = Date.now();
+        this.stmts.snapshotSet.run(stream, type, JSON.stringify(data), eventId, now);
+    }
+    async eventListStreams() {
+        const rows = this.stmts.eventListStreams.all();
+        return rows.map(row => row.stream);
+    }
+    // Query operations
+    async querySql(query, params = []) {
+        try {
+            const stmt = this.db.prepare(query);
+            return stmt.all(...params);
+        }
+        catch (error) {
+            throw new Error(`SQL query failed: ${error instanceof Error ? error.message : 'unknown error'}`);
+        }
+    }
+    // Transaction operations
+    async transactionBegin() {
+        if (this.transactionDepth === 0) {
+            this.db.exec("BEGIN");
+        }
+        this.transactionDepth++;
+    }
+    async transactionCommit() {
+        this.transactionDepth--;
+        if (this.transactionDepth === 0) {
+            this.db.exec("COMMIT");
+        }
+    }
+    async transactionRollback() {
+        this.transactionDepth--;
+        if (this.transactionDepth === 0) {
+            this.db.exec("ROLLBACK");
+        }
+    }
+    async transactionRun(fn) {
+        await this.transactionBegin();
+        try {
+            const result = await fn();
+            await this.transactionCommit();
+            return result;
+        }
+        catch (error) {
+            await this.transactionRollback();
+            throw error;
+        }
+    }
+    // Cleanup and maintenance
+    sweep() {
+        const now = Date.now();
+        const result = this.stmts.sweep.run(now);
+        if (result.changes > 0) {
+            console.debug(`Cleaned up ${result.changes} expired KV entries`);
+        }
+    }
+    async close() {
+        if (this.sweepTimer) {
+            clearInterval(this.sweepTimer);
+            this.sweepTimer = undefined;
+        }
+        this.db.close();
+    }
+}
+//# sourceMappingURL=sqlite.js.map

package/dist/shared/persistence/backends/sqlite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite.js","sourceRoot":"","sources":["../../../../src/shared/persistence/backends/sqlite.ts"],"names":[],"mappings":"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"}

package/dist/shared/persistence/event-store.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Event sourcing utilities and helpers.
+ *
+ * Provides event versioning, schema evolution helpers, and common event patterns
+ * used throughout the Action Llama system.
+ */
+import type { Event, EventStream } from "./index.js";
+/** Common event types used across the system */
+export declare namespace EventTypes {
+    const RUN_STARTED = "run.started";
+    const RUN_COMPLETED = "run.completed";
+    const RUN_FAILED = "run.failed";
+    const CALL_INITIATED = "call.initiated";
+    const CALL_COMPLETED = "call.completed";
+    const CALL_FAILED = "call.failed";
+    const WORK_QUEUED = "work.queued";
+    const WORK_DEQUEUED = "work.dequeued";
+    const WORK_DROPPED = "work.dropped";
+    const LOCK_ACQUIRED = "lock.acquired";
+    const LOCK_RELEASED = "lock.released";
+    const LOCK_EXPIRED = "lock.expired";
+    const SESSION_CREATED = "session.created";
+    const SESSION_EXPIRED = "session.expired";
+}
+/** Event metadata standard fields */
+export interface EventMetadata {
+    /** Source system/component that generated the event */
+    source?: string;
+    /** Correlation ID for tracing related events */
+    correlationId?: string;
+    /** User or system that triggered the event */
+    actor?: string;
+    /** Additional tags for filtering/grouping */
+    tags?: string[];
+}
+/** Helper for creating events with proper defaults */
+export declare function createEvent(type: string, data: any, metadata?: EventMetadata, version?: number): Omit<Event, 'id' | 'timestamp'>;
+/** Schema evolution helper */
+export interface EventMigration {
+    fromVersion: number;
+    toVersion: number;
+    migrate: (event: Event) => Event;
+}
+export declare class EventMigrator {
+    private migrations;
+    addMigration(eventType: string, migration: EventMigration): void;
+    migrate(event: Event, targetVersion: number): Event;
+}
+/** Event stream wrapper with additional utilities */
+export declare class EventStreamWrapper {
+    private stream;
+    constructor(stream: EventStream);
+    /** Append a typed event */
+    appendTyped<T>(type: string, data: T, metadata?: EventMetadata, version?: number): Promise<Event>;
+    /** Replay events from the stream */
+    replay(query?: import("./index.js").EventQuery): AsyncIterable<Event>;
+    /** Get snapshot from the stream */
+    getSnapshot<T>(type: string): Promise<T | null>;
+    /** Save snapshot to the stream */
+    saveSnapshot<T>(type: string, data: T, eventId: string): Promise<void>;
+    /** Replay events of a specific type */
+    replayType<T>(type: string, from?: number, to?: number): AsyncIterable<Event & {
+        data: T;
+    }>;
+    /** Build a projection from events */
+    buildProjection<T>(initialState: T, reducer: (state: T, event: Event) => T, from?: number): Promise<T>;
+    /** Get the latest event of a specific type */
+    getLatestEvent(type: string): Promise<Event | null>;
+}
+/** Common projection builders */
+export declare namespace Projections {
+    /** Count events by type */
+    function eventCounts(events: AsyncIterable<Event>): Promise<Map<string, number>>;
+    /** Group events by time window */
+    function timeWindow(events: AsyncIterable<Event>, windowMs: number): Promise<Map<number, Event[]>>;
+}
+//# sourceMappingURL=event-store.d.ts.map

package/dist/shared/persistence/event-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-store.d.ts","sourceRoot":"","sources":["../../../src/shared/persistence/event-store.ts"],"names":[],"mappings":"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"}

package/dist/shared/persistence/event-store.js

@@ -0,0 +1,139 @@
+/**
+ * Event sourcing utilities and helpers.
+ *
+ * Provides event versioning, schema evolution helpers, and common event patterns
+ * used throughout the Action Llama system.
+ */
+/** Common event types used across the system */
+export var EventTypes;
+(function (EventTypes) {
+    // Run lifecycle events
+    EventTypes.RUN_STARTED = "run.started";
+    EventTypes.RUN_COMPLETED = "run.completed";
+    EventTypes.RUN_FAILED = "run.failed";
+    // Call events 
+    EventTypes.CALL_INITIATED = "call.initiated";
+    EventTypes.CALL_COMPLETED = "call.completed";
+    EventTypes.CALL_FAILED = "call.failed";
+    // Work queue events
+    EventTypes.WORK_QUEUED = "work.queued";
+    EventTypes.WORK_DEQUEUED = "work.dequeued";
+    EventTypes.WORK_DROPPED = "work.dropped";
+    // Lock events
+    EventTypes.LOCK_ACQUIRED = "lock.acquired";
+    EventTypes.LOCK_RELEASED = "lock.released";
+    EventTypes.LOCK_EXPIRED = "lock.expired";
+    // Session events
+    EventTypes.SESSION_CREATED = "session.created";
+    EventTypes.SESSION_EXPIRED = "session.expired";
+})(EventTypes || (EventTypes = {}));
+/** Helper for creating events with proper defaults */
+export function createEvent(type, data, metadata, version = 1) {
+    return {
+        type,
+        data,
+        metadata: {
+            ...metadata,
+            source: "action-llama", // Always use consistent source for audit purposes
+        },
+        version,
+    };
+}
+export class EventMigrator {
+    migrations = new Map();
+    addMigration(eventType, migration) {
+        if (!this.migrations.has(eventType)) {
+            this.migrations.set(eventType, []);
+        }
+        this.migrations.get(eventType).push(migration);
+    }
+    migrate(event, targetVersion) {
+        const migrations = this.migrations.get(event.type) || [];
+        let currentEvent = { ...event };
+        while (currentEvent.version < targetVersion) {
+            const migration = migrations.find(m => m.fromVersion === currentEvent.version);
+            if (!migration) {
+                throw new Error(`No migration found for ${event.type} from version ${currentEvent.version}`);
+            }
+            currentEvent = migration.migrate(currentEvent);
+        }
+        return currentEvent;
+    }
+}
+/** Event stream wrapper with additional utilities */
+export class EventStreamWrapper {
+    stream;
+    constructor(stream) {
+        this.stream = stream;
+    }
+    /** Append a typed event */
+    async appendTyped(type, data, metadata, version = 1) {
+        return this.stream.append(createEvent(type, data, metadata, version));
+    }
+    /** Replay events from the stream */
+    replay(query) {
+        return this.stream.replay(query);
+    }
+    /** Get snapshot from the stream */
+    getSnapshot(type) {
+        return this.stream.getSnapshot(type);
+    }
+    /** Save snapshot to the stream */
+    saveSnapshot(type, data, eventId) {
+        return this.stream.saveSnapshot(type, data, eventId);
+    }
+    /** Replay events of a specific type */
+    async *replayType(type, from, to) {
+        for await (const event of this.stream.replay({ type, from, to })) {
+            yield event;
+        }
+    }
+    /** Build a projection from events */
+    async buildProjection(initialState, reducer, from) {
+        let state = initialState;
+        for await (const event of this.stream.replay({ from })) {
+            state = reducer(state, event);
+        }
+        return state;
+    }
+    /** Get the latest event of a specific type */
+    async getLatestEvent(type) {
+        const events = [];
+        for await (const event of this.stream.replay({ type, limit: 1 })) {
+            events.push(event);
+        }
+        return events[0] || null;
+    }
+}
+/** Common projection builders */
+export var Projections;
+(function (Projections) {
+    /** Count events by type */
+    function eventCounts(events) {
+        return buildProjectionFromIterable(events, new Map(), (counts, event) => {
+            counts.set(event.type, (counts.get(event.type) || 0) + 1);
+            return counts;
+        });
+    }
+    Projections.eventCounts = eventCounts;
+    /** Group events by time window */
+    function timeWindow(events, windowMs) {
+        return buildProjectionFromIterable(events, new Map(), (windows, event) => {
+            const window = Math.floor(event.timestamp / windowMs) * windowMs;
+            if (!windows.has(window)) {
+                windows.set(window, []);
+            }
+            windows.get(window).push(event);
+            return windows;
+        });
+    }
+    Projections.timeWindow = timeWindow;
+})(Projections || (Projections = {}));
+async function buildProjectionFromIterable(events, initialState, reducer) {
+    let state = initialState;
+    for await (const event of events) {
+        state = reducer(state, event);
+    }
+    return state;
+}
+//# sourceMappingURL=event-store.js.map

package/dist/shared/persistence/event-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-store.js","sourceRoot":"","sources":["../../../src/shared/persistence/event-store.ts"],"names":[],"mappings":"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"}

package/dist/shared/persistence/index.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Unified persistence layer combining key-value storage, event sourcing, and query capabilities.
+ *
+ * Replaces the fragmented StateStore/StatsStore/WorkQueue pattern with a single abstraction
+ * that supports namespaces, TTL, and append-only event storage for features like replay,
+ * audit, and high availability.
+ */
+export interface Event {
+    /** Unique event identifier */
+    id: string;
+    /** Event type/category */
+    type: string;
+    /** Event data payload */
+    data: any;
+    /** Event metadata (source, correlation id, etc.) */
+    metadata?: Record<string, any>;
+    /** Event timestamp (milliseconds since epoch) */
+    timestamp: number;
+    /** Event version for schema evolution */
+    version: number;
+}
+export interface EventQuery {
+    /** Event type filter */
+    type?: string;
+    /** Start timestamp (inclusive) */
+    from?: number;
+    /** End timestamp (exclusive) */
+    to?: number;
+    /** Maximum number of events to return */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}
+export interface EventStream {
+    /** Append an event to the stream */
+    append(event: Omit<Event, 'id' | 'timestamp'>): Promise<Event>;
+    /** Replay events from the stream */
+    replay(query?: EventQuery): AsyncIterable<Event>;
+    /** Get the latest snapshot for a given type */
+    getSnapshot<T>(type: string): Promise<T | null>;
+    /** Save a snapshot to optimize future replays */
+    saveSnapshot<T>(type: string, data: T, eventId: string): Promise<void>;
+    /** Subscribe to new events (optional - for real-time features) */
+    subscribe?(callback: (event: Event) => void): () => void;
+}
+export interface PersistenceStore {
+    /** Key-value operations with namespacing */
+    kv: {
+        /** Get a value by namespace and key */
+        get<T>(namespace: string, key: string): Promise<T | null>;
+        /** Set a value with optional TTL */
+        set<T>(namespace: string, key: string, value: T, opts?: {
+            ttl?: number;
+        }): Promise<void>;
+        /** Delete a single key */
+        delete(namespace: string, key: string): Promise<void>;
+        /** Delete all keys in a namespace */
+        deleteAll(namespace: string): Promise<void>;
+        /** List all non-expired entries in a namespace */
+        list<T>(namespace: string): Promise<Array<{
+            key: string;
+            value: T;
+        }>>;
+    };
+    /** Event sourcing operations */
+    events: {
+        /** Get or create an event stream */
+        stream(name: string): EventStream;
+        /** List available streams */
+        listStreams(): Promise<string[]>;
+    };
+    /** Query operations for analytics */
+    query: {
+        /** Execute a SQL query for analytics (backend-specific) */
+        sql<T>(query: string, params?: any[]): Promise<T[]>;
+    };
+    /** Transaction operations */
+    transaction<T>(fn: (store: PersistenceStore) => Promise<T>): Promise<T>;
+    /** Close the store and release resources */
+    close(): Promise<void>;
+}
+export interface PersistenceBackend {
+    /** Initialize the backend (create tables, etc.) */
+    init(): Promise<void>;
+    /** Implement the key-value operations */
+    kvGet<T>(namespace: string, key: string): Promise<T | null>;
+    kvSet<T>(namespace: string, key: string, value: T, ttlMs?: number): Promise<void>;
+    kvDelete(namespace: string, key: string): Promise<void>;
+    kvDeleteAll(namespace: string): Promise<void>;
+    kvList<T>(namespace: string): Promise<Array<{
+        key: string;
+        value: T;
+    }>>;
+    /** Implement the event operations */
+    eventAppend(stream: string, event: Omit<Event, 'id' | 'timestamp'>): Promise<Event>;
+    eventReplay(stream: string, query?: EventQuery): AsyncIterable<Event>;
+    eventGetSnapshot<T>(stream: string, type: string): Promise<T | null>;
+    eventSaveSnapshot<T>(stream: string, type: string, data: T, eventId: string): Promise<void>;
+    eventListStreams(): Promise<string[]>;
+    /** Implement query operations */
+    querySql<T>(query: string, params?: any[]): Promise<T[]>;
+    /** Implement transaction operations */
+    transactionBegin(): Promise<void>;
+    transactionCommit(): Promise<void>;
+    transactionRollback(): Promise<void>;
+    transactionRun<T>(fn: () => Promise<T>): Promise<T>;
+    /** Close and cleanup */
+    close(): Promise<void>;
+}
+export interface PersistenceConfig {
+    type: "sqlite" | "memory";
+    path?: string;
+    maxSize?: number;
+}
+/**
+ * Create a persistence store from configuration.
+ */
+export declare function createPersistenceStore(config: PersistenceConfig): Promise<PersistenceStore>;
+//# sourceMappingURL=index.d.ts.map

package/dist/shared/persistence/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shared/persistence/index.ts"],"names":[],"mappings":"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"}