donobu 1.0.0

package/dist/esm/persistence/AgentsPersistenceSqlite.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentsPersistenceSqlite = void 0;
+const DonobuAgentType_1 = require("../models/DonobuAgentType");
+/**
+ * A persistence implementation that stores agent-to-config mappings in SQLite.
+ */
+class AgentsPersistenceSqlite {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    static async create(db) {
+        return new AgentsPersistenceSqlite(db);
+    }
+    async set(agent, gptConfigName) {
+        const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO agent_configs (agent, config_name)
+      VALUES (?, ?)
+    `);
+        stmt.run(agent, gptConfigName);
+    }
+    async get(agent) {
+        const stmt = this.db.prepare(`
+      SELECT config_name FROM agent_configs
+      WHERE agent = ?
+    `);
+        const row = stmt.get(agent);
+        return row ? row.config_name : null;
+    }
+    async getAll() {
+        const stmt = this.db.prepare(`
+      SELECT agent, config_name FROM agent_configs
+    `);
+        const rows = stmt.all();
+        const result = new Map();
+        // Ensure all agents have an entry
+        for (const agent of DonobuAgentType_1.DonobuAgent) {
+            result.set(agent, null);
+        }
+        // Override with database values
+        for (const row of rows) {
+            if (DonobuAgentType_1.DonobuAgent.includes(row.agent)) {
+                result.set(row.agent, row.config_name);
+            }
+        }
+        return result;
+    }
+}
+exports.AgentsPersistenceSqlite = AgentsPersistenceSqlite;
+//# sourceMappingURL=AgentsPersistenceSqlite.js.map

package/dist/esm/persistence/AgentsPersistenceSqlite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentsPersistenceSqlite.js","sourceRoot":"","sources":["../../../src/persistence/AgentsPersistenceSqlite.ts"],"names":[],"mappings":";;;AACA,+DAAwD;AAGxD;;GAEG;AACH,MAAa,uBAAuB;IACG;IAArC,YAAqC,EAAqB;QAArB,OAAE,GAAF,EAAE,CAAmB;IAAG,CAAC;IAEvD,MAAM,CAAC,KAAK,CAAC,MAAM,CACxB,EAAqB;QAErB,OAAO,IAAI,uBAAuB,CAAC,EAAE,CAAC,CAAC;IACzC,CAAC;IAEM,KAAK,CAAC,GAAG,CACd,KAAkB,EAClB,aAA4B;QAE5B,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC;;;KAG5B,CAAC,CAAC;QAEH,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;IACjC,CAAC;IAEM,KAAK,CAAC,GAAG,CAAC,KAAkB;QACjC,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC;;;KAG5B,CAAC,CAAC;QAEH,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAA+C,CAAC;QAE1E,OAAO,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC;IACtC,CAAC;IAEM,KAAK,CAAC,MAAM;QACjB,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC;;KAE5B,CAAC,CAAC;QAEH,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAGlB,CAAC;QACJ,MAAM,MAAM,GAAG,IAAI,GAAG,EAA8B,CAAC;QAErD,kCAAkC;QAClC,KAAK,MAAM,KAAK,IAAI,6BAAW,EAAE,CAAC;YAChC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAC1B,CAAC;QAED,gCAAgC;QAChC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,IAAI,6BAAW,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAoB,CAAC,EAAE,CAAC;gBACnD,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,KAAoB,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC;YACxD,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;CACF;AAzDD,0DAyDC"}

package/dist/esm/persistence/AgentsPersistenceVolatile.d.ts

@@ -0,0 +1,13 @@
+import { DonobuAgent } from '../models/DonobuAgentType';
+import { AgentsPersistence } from './AgentsPersistence';
+/**
+ * An agents "persistence" implementation that manages state using an
+ * in-memory map.
+ */
+export declare class AgentsPersistenceVolatile implements AgentsPersistence {
+    private readonly data;
+    constructor(data?: Map<DonobuAgent, string | null>);
+    set(agent: DonobuAgent, gptConfigName: string | null): Promise<void>;
+    get(agent: DonobuAgent): Promise<string | null>;
+    getAll(): Promise<Map<DonobuAgent, string | null>>;
+}

package/dist/esm/persistence/AgentsPersistenceVolatile.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentsPersistenceVolatile = void 0;
+const DonobuAgentType_1 = require("../models/DonobuAgentType");
+/**
+ * An agents "persistence" implementation that manages state using an
+ * in-memory map.
+ */
+class AgentsPersistenceVolatile {
+    data;
+    constructor(data = new Map()) {
+        this.data = data;
+    }
+    async set(agent, gptConfigName) {
+        this.data.set(agent, gptConfigName);
+    }
+    async get(agent) {
+        return this.data.get(agent) ?? null;
+    }
+    async getAll() {
+        return new Map(DonobuAgentType_1.DonobuAgent.map((agent) => {
+            return [agent, this.data.get(agent) ?? null];
+        }));
+    }
+}
+exports.AgentsPersistenceVolatile = AgentsPersistenceVolatile;
+//# sourceMappingURL=AgentsPersistenceVolatile.js.map

package/dist/esm/persistence/AgentsPersistenceVolatile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentsPersistenceVolatile.js","sourceRoot":"","sources":["../../../src/persistence/AgentsPersistenceVolatile.ts"],"names":[],"mappings":";;;AAAA,+DAAwD;AAGxD;;;GAGG;AACH,MAAa,yBAAyB;IAEjB;IADnB,YACmB,OAAwC,IAAI,GAAG,EAAE;QAAjD,SAAI,GAAJ,IAAI,CAA6C;IACjE,CAAC;IAEG,KAAK,CAAC,GAAG,CACd,KAAkB,EAClB,aAA4B;QAE5B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;IACtC,CAAC;IAEM,KAAK,CAAC,GAAG,CAAC,KAAkB;QACjC,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC;IACtC,CAAC;IAEM,KAAK,CAAC,MAAM;QACjB,OAAO,IAAI,GAAG,CACZ,6BAAW,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;YACxB,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC;QAC/C,CAAC,CAAC,CACH,CAAC;IACJ,CAAC;CACF;AAvBD,8DAuBC"}

package/dist/esm/persistence/DonobuSqliteDb.d.ts

@@ -0,0 +1,11 @@
+import Database from 'better-sqlite3';
+/**
+ * Returns the singleton SQLite database instance.
+ * Creates the database on first call and initializes it with proper settings.
+ */
+declare function getDonobuSqliteDatabase(): Database.Database;
+/**
+ * Closes the database connection. Should be called during application shutdown.
+ */
+declare function closeDonobuSqliteDatabase(): void;
+export { getDonobuSqliteDatabase, closeDonobuSqliteDatabase };

package/dist/esm/persistence/DonobuSqliteDb.js

@@ -0,0 +1,178 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDonobuSqliteDatabase = getDonobuSqliteDatabase;
+exports.closeDonobuSqliteDatabase = closeDonobuSqliteDatabase;
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const MiscUtils_1 = require("../utils/MiscUtils");
+let instance = null;
+/**
+ * ##################################################################
+ * #                                                                #
+ * #     WARNING! WARNING! WARNING! WARNING! WARNING! WARNING!      #
+ * #                                                                #
+ * ##################################################################
+ *
+ * NEVER change existing migrations. This list is APPEND-ONLY! If you do not
+ * abide by this, YOU WILL BREAK OUR USERS!
+ */
+const migrations = [
+    {
+        // Setup the Donobu agent configs table.
+        version: 1,
+        up: (db) => {
+            db.exec(`
+CREATE TABLE IF NOT EXISTS agent_configs (
+  agent TEXT PRIMARY KEY,
+  config_name TEXT NULL
+);
+
+INSERT OR IGNORE INTO agent_configs (agent, config_name)
+VALUES ('flow-runner', NULL);`);
+        },
+    },
+    {
+        version: 2,
+        up: (db) => {
+            // Setup the Donobu flows-related tables.
+            db.exec(`
+CREATE TABLE IF NOT EXISTS flow_metadata (
+  id TEXT PRIMARY KEY,
+  name TEXT NULL,
+  metadata TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  run_mode TEXT NOT NULL,
+  state TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS tool_calls (
+  id TEXT PRIMARY KEY,
+  flow_id TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  tool_call TEXT NOT NULL,
+  FOREIGN KEY (flow_id) REFERENCES flow_metadata(id) ON DELETE CASCADE
+);
+CREATE TABLE IF NOT EXISTS binary_files (
+  id TEXT PRIMARY KEY,
+  flow_id TEXT NOT NULL,
+  file_id TEXT NOT NULL,
+  mime_type TEXT NOT NULL,
+  content BLOB,
+  FOREIGN KEY (flow_id) REFERENCES flow_metadata(id) ON DELETE CASCADE,
+  UNIQUE(flow_id, file_id)
+);
+-- Indices for better performance
+CREATE INDEX IF NOT EXISTS idx_flow_metadata_name ON flow_metadata(name);
+CREATE INDEX IF NOT EXISTS idx_flow_metadata_created_at ON flow_metadata(created_at);
+CREATE INDEX IF NOT EXISTS idx_flow_metadata_run_mode ON flow_metadata(run_mode);
+CREATE INDEX IF NOT EXISTS idx_flow_metadata_state ON flow_metadata(state);
+CREATE INDEX IF NOT EXISTS idx_flow_metadata_run_mode_state ON flow_metadata(run_mode, state);
+CREATE INDEX IF NOT EXISTS idx_tool_calls_flow_id_started ON tool_calls(flow_id, created_at);
+CREATE INDEX IF NOT EXISTS idx_tool_calls_created_at ON tool_calls(created_at);
+CREATE INDEX IF NOT EXISTS idx_binary_files_flow_file ON binary_files(flow_id, file_id);
+-- Enable foreign key support
+PRAGMA foreign_keys = ON;`);
+        },
+    },
+    {
+        // Setup the GPT configs table.
+        version: 3,
+        up: (db) => {
+            db.exec(`
+CREATE TABLE IF NOT EXISTS gpt_configs (
+  name TEXT PRIMARY KEY,
+  config TEXT NOT NULL
+);`);
+        },
+    },
+];
+/**
+ * Create the SQL schema migrations table that can be used to manage table
+ * schemas across Donobu releases.
+ */
+function initMigrationsTable(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS schema_migrations (
+      version INTEGER PRIMARY KEY,
+      applied_at TEXT NOT NULL
+    );
+  `);
+}
+function applyMigrations(db) {
+    // First, validate that no duplicate version numbers exist in the migrations
+    // array.
+    const versionCounts = new Map();
+    const duplicateVersions = [];
+    // Count occurrences of each version.
+    for (const migration of migrations) {
+        const count = (versionCounts.get(migration.version) || 0) + 1;
+        versionCounts.set(migration.version, count);
+        // If we've seen this version more than once, add it to duplicates.
+        if (count > 1 && !duplicateVersions.includes(migration.version)) {
+            duplicateVersions.push(migration.version);
+        }
+    }
+    // If we found duplicates, throw an error.
+    if (duplicateVersions.length > 0) {
+        throw new Error(`Duplicate migration version(s) detected: ${duplicateVersions.join(', ')}. ` +
+            'Each migration must have a unique version number.');
+    }
+    // Get current version.
+    const getCurrentVersionStmt = db.prepare('SELECT MAX(version) as current_version FROM schema_migrations');
+    const result = getCurrentVersionStmt.get();
+    const currentVersion = result.current_version || 0;
+    // Apply pending migrations in transaction.
+    const pendingMigrations = migrations
+        .filter((m) => m.version > currentVersion)
+        .sort((a, b) => a.version - b.version);
+    if (pendingMigrations.length > 0) {
+        const transaction = db.transaction(() => {
+            for (const migration of pendingMigrations) {
+                console.log(`Applying migration ${migration.version}...`);
+                migration.up(db);
+                // Record migration.
+                const recordMigrationStmt = db.prepare('INSERT INTO schema_migrations (version, applied_at) VALUES (?, ?)');
+                recordMigrationStmt.run(migration.version, new Date().toISOString());
+            }
+        });
+        transaction();
+    }
+}
+/**
+ * Returns the singleton SQLite database instance.
+ * Creates the database on first call and initializes it with proper settings.
+ */
+function getDonobuSqliteDatabase() {
+    if (instance) {
+        return instance;
+    }
+    const dbDirectory = MiscUtils_1.MiscUtils.baseWorkingDirectory();
+    if (!fs_1.default.existsSync(dbDirectory)) {
+        fs_1.default.mkdirSync(dbDirectory, { recursive: true });
+    }
+    const dbFilepath = path_1.default.join(MiscUtils_1.MiscUtils.baseWorkingDirectory(), 'database.sqlite');
+    // Initialize database.
+    const donobuSqliteDb = new better_sqlite3_1.default(dbFilepath);
+    // Set up database configuration.
+    donobuSqliteDb.pragma('journal_mode = WAL');
+    donobuSqliteDb.pragma('foreign_keys = ON');
+    // Set up tables.
+    initMigrationsTable(donobuSqliteDb);
+    applyMigrations(donobuSqliteDb);
+    // Update global database handle.
+    instance = donobuSqliteDb;
+    return instance;
+}
+/**
+ * Closes the database connection. Should be called during application shutdown.
+ */
+function closeDonobuSqliteDatabase() {
+    if (instance) {
+        instance.close();
+        instance = null;
+    }
+}
+//# sourceMappingURL=DonobuSqliteDb.js.map

package/dist/esm/persistence/DonobuSqliteDb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DonobuSqliteDb.js","sourceRoot":"","sources":["../../../src/persistence/DonobuSqliteDb.ts"],"names":[],"mappings":";;;;;AA2MS,0DAAuB;AAAE,8DAAyB;AA3M3D,gDAAwB;AACxB,4CAAoB;AACpB,oEAAsC;AACtC,kDAA+C;AAE/C,IAAI,QAAQ,GAA6B,IAAI,CAAC;AAO9C;;;;;;;;;GASG;AACH,MAAM,UAAU,GAAgB;IAC9B;QACE,wCAAwC;QACxC,OAAO,EAAE,CAAC;QACV,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE;YACT,EAAE,CAAC,IAAI,CAAC;;;;;;;8BAOgB,CAAC,CAAC;QAC5B,CAAC;KACF;IACD;QACE,OAAO,EAAE,CAAC;QACV,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE;YACT,yCAAyC;YACzC,EAAE,CAAC,IAAI,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BAmCY,CAAC,CAAC;QACxB,CAAC;KACF;IACD;QACE,+BAA+B;QAC/B,OAAO,EAAE,CAAC;QACV,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE;YACT,EAAE,CAAC,IAAI,CAAC;;;;GAIX,CAAC,CAAC;QACD,CAAC;KACF;CACF,CAAC;AAEF;;;GAGG;AACH,SAAS,mBAAmB,CAAC,EAAqB;IAChD,EAAE,CAAC,IAAI,CAAC;;;;;GAKP,CAAC,CAAC;AACL,CAAC;AAED,SAAS,eAAe,CAAC,EAAqB;IAC5C,4EAA4E;IAC5E,SAAS;IACT,MAAM,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAC;IAChD,MAAM,iBAAiB,GAAa,EAAE,CAAC;IAEvC,qCAAqC;IACrC,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,MAAM,KAAK,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QAC9D,aAAa,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAE5C,mEAAmE;QACnE,IAAI,KAAK,GAAG,CAAC,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;YAChE,iBAAiB,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IAED,0CAA0C;IAC1C,IAAI,iBAAiB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,4CAA4C,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;YAC1E,mDAAmD,CACtD,CAAC;IACJ,CAAC;IAED,uBAAuB;IACvB,MAAM,qBAAqB,GAAG,EAAE,CAAC,OAAO,CACtC,+DAA+D,CAChE,CAAC;IACF,MAAM,MAAM,GAAG,qBAAqB,CAAC,GAAG,EAEvC,CAAC;IACF,MAAM,cAAc,GAAG,MAAM,CAAC,eAAe,IAAI,CAAC,CAAC;IAEnD,2CAA2C;IAC3C,MAAM,iBAAiB,GAAG,UAAU;SACjC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,GAAG,cAAc,CAAC;SACzC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC;IAEzC,IAAI,iBAAiB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjC,MAAM,WAAW,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE;YACtC,KAAK,MAAM,SAAS,IAAI,iBAAiB,EAAE,CAAC;gBAC1C,OAAO,CAAC,GAAG,CAAC,sBAAsB,SAAS,CAAC,OAAO,KAAK,CAAC,CAAC;gBAC1D,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;gBACjB,oBAAoB;gBACpB,MAAM,mBAAmB,GAAG,EAAE,CAAC,OAAO,CACpC,mEAAmE,CACpE,CAAC;gBACF,mBAAmB,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;YACvE,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,WAAW,EAAE,CAAC;IAChB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,uBAAuB;IAC9B,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,WAAW,GAAG,qBAAS,CAAC,oBAAoB,EAAE,CAAC;IAErD,IAAI,CAAC,YAAE,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAChC,YAAE,CAAC,SAAS,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACjD,CAAC;IAED,MAAM,UAAU,GAAG,cAAI,CAAC,IAAI,CAC1B,qBAAS,CAAC,oBAAoB,EAAE,EAChC,iBAAiB,CAClB,CAAC;IACF,uBAAuB;IACvB,MAAM,cAAc,GAAG,IAAI,wBAAQ,CAAC,UAAU,CAAsB,CAAC;IACrE,iCAAiC;IACjC,cAAc,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAC5C,cAAc,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;IAC3C,iBAAiB;IACjB,mBAAmB,CAAC,cAAc,CAAC,CAAC;IACpC,eAAe,CAAC,cAAc,CAAC,CAAC;IAChC,iCAAiC;IACjC,QAAQ,GAAG,cAAc,CAAC;IAC1B,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,SAAS,yBAAyB;IAChC,IAAI,QAAQ,EAAE,CAAC;QACb,QAAQ,CAAC,KAAK,EAAE,CAAC;QACjB,QAAQ,GAAG,IAAI,CAAC;IAClB,CAAC;AACH,CAAC"}

package/dist/esm/persistence/FlowsPersistence.d.ts

@@ -0,0 +1,94 @@
+import { BrowserStorageState } from '../models/BrowserState';
+import { FlowMetadata } from '../models/FlowMetadata';
+import { FlowsQuery } from '../models/FlowsQuery';
+import { ToolCall } from '../models/ToolCall';
+import { VideoSegment } from '../models/VideoSegment';
+/**
+ * Result of a paginated flows query
+ */
+export interface PaginatedFlowsResult {
+    /** Flows matching the query. */
+    items: FlowMetadata[];
+    /** Token for fetching the next page (if available). */
+    nextPageToken?: string;
+}
+/**
+ * Interface for persisting data relating to DonobuFlow runs.
+ */
+export interface FlowsPersistence {
+    /**
+     * Save the given FlowMetadata for the associated flow.
+     */
+    saveMetadata(flowMetadata: FlowMetadata): Promise<void>;
+    /**
+     * Load metadata for a specific flow.
+     * @throws FlowNotFoundException if the flow is not found
+     */
+    getMetadataByFlowId(flowId: string): Promise<FlowMetadata>;
+    /**
+     * Load metadata by a given flow name.
+     * @throws FlowNotFoundException if the flow is not found
+     */
+    getMetadataByFlowName(flowName: string): Promise<FlowMetadata>;
+    /**
+     * Save a PNG screenshot for a specific flow.
+     * @returns The identifier for the saved screenshot
+     */
+    savePngScreenShot(flowId: string, bytes: Buffer): Promise<string>;
+    /**
+     * Loads a PNG screenshot.
+     */
+    getPngScreenShot(flowId: string, screenShotId: string): Promise<Buffer | null>;
+    /**
+     * Save a tool call for a specific flow.
+     */
+    saveToolCall(flowId: string, toolCall: ToolCall): Promise<void>;
+    /**
+     * Load all tool calls for a specific flow.
+     * @throws FlowNotFoundException if the flow is not found
+     */
+    getToolCalls(flowId: string): Promise<ToolCall[]>;
+    /**
+     * Get flows matching a given query.
+     */
+    getFlows(query: FlowsQuery): Promise<PaginatedFlowsResult>;
+    /**
+     * Set video data for a specific flow.
+     */
+    setVideo(flowId: string, bytes: Buffer): Promise<void>;
+    /**
+     * Get a video segment for a specific flow.
+     * @throws FlowNotFoundException if the flow is not found
+     */
+    getVideoSegment(flowId: string, startOffset: number, length: number): Promise<VideoSegment | null>;
+    /**
+     * Get a file associated with a specific flow.
+     *
+     * @throws FlowNotFoundException if the flow is not found.
+     */
+    getFlowFile(flowId: string, fileId: string): Promise<Buffer | null>;
+    /**
+     * Set a file for a specific flow.
+     */
+    setFlowFile(flowId: string, fileId: string, fileBytes: Buffer): Promise<void>;
+    /**
+     * Sets the given browser state for a specific flow.
+     *
+     * WARNING: This will NOT override the runtime browser state for a flow that
+     * is currently running. This is only for persisting the browser state for a
+     * flow that has completed so that it can be used by other flows in the
+     * future.
+     */
+    setBrowserState(flowId: string, browserState: BrowserStorageState): Promise<void>;
+    /**
+     * Get the browser state for a specific flow. Note that not all flows will
+     * have an associated persisted browser state.
+     *
+     * @throws FlowNotFoundException if the flow is not found.
+     */
+    getBrowserState(flowId: string): Promise<BrowserStorageState | null>;
+    /**
+     * Delete a specific flow and all associated data.
+     */
+    deleteFlow(flowId: string): Promise<void>;
+}

package/dist/esm/persistence/FlowsPersistence.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=FlowsPersistence.js.map

package/dist/esm/persistence/FlowsPersistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FlowsPersistence.js","sourceRoot":"","sources":["../../../src/persistence/FlowsPersistence.ts"],"names":[],"mappings":""}

package/dist/esm/persistence/FlowsPersistenceAwsS3.d.ts

@@ -0,0 +1,70 @@
+import { FlowsPersistence, PaginatedFlowsResult } from './FlowsPersistence';
+import { FlowMetadata } from '../models/FlowMetadata';
+import { ToolCall } from '../models/ToolCall';
+import { VideoSegment } from '../models/VideoSegment';
+import { BrowserStorageState } from '../models/BrowserState';
+import { FlowsQuery } from '../models/FlowsQuery';
+/**
+ * A persistence implementation that uses AWS S3.
+ * Ensure AWS credentials are properly configured in your environment,
+ * or provide them directly in the constructor.
+ */
+export declare class FlowsPersistenceAwsS3 implements FlowsPersistence {
+    private static readonly NAME_INDEX_PREFIX;
+    private static readonly RUN_MODE_INDEX_PREFIX;
+    private static readonly STATE_INDEX_PREFIX;
+    private static readonly RUN_MODE_STATE_INDEX_PREFIX;
+    private static readonly METADATA_FILENAME;
+    private static readonly BROWSER_STATE_FILENAME;
+    private static readonly SCREENSHOT_FILENAME_SUFFIX;
+    private static readonly TOOL_CALL_FILENAME_SUFFIX;
+    private static readonly VIDEO_FILENAME;
+    private readonly s3Client;
+    private readonly bucketName;
+    /**
+     * Creates a new instance of the AWS S3 persistence layer.
+     *
+     * @param bucketName The name of the S3 bucket to use for storage
+     * @param region AWS region (defaults to 'us-east-1')
+     * @param credentials Optional AWS credentials (if not provided, will use environment variables)
+     */
+    constructor(bucketName: string, region: string, credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    });
+    saveMetadata(flowMetadata: FlowMetadata): Promise<void>;
+    getMetadataByFlowId(flowId: string): Promise<FlowMetadata>;
+    getMetadataByFlowName(flowName: string): Promise<FlowMetadata>;
+    savePngScreenShot(flowId: string, bytes: Buffer): Promise<string>;
+    getPngScreenShot(flowId: string, screenShotId: string): Promise<Buffer | null>;
+    saveToolCall(flowId: string, toolCall: ToolCall): Promise<void>;
+    getToolCalls(flowId: string): Promise<ToolCall[]>;
+    getFlows(query: FlowsQuery): Promise<PaginatedFlowsResult>;
+    setVideo(flowId: string, bytes: Buffer): Promise<void>;
+    getVideoSegment(flowId: string, startOffset: number, length: number): Promise<VideoSegment | null>;
+    getFlowFile(flowId: string, fileId: string): Promise<Buffer | null>;
+    setFlowFile(flowId: string, fileId: string, fileBytes: Buffer): Promise<void>;
+    setBrowserState(flowId: string, browserState: BrowserStorageState): Promise<void>;
+    getBrowserState(flowId: string): Promise<BrowserStorageState | null>;
+    deleteFlow(flowId: string): Promise<void>;
+    /**
+     * Utility method to stream S3 object data to a Buffer
+     */
+    private streamToBuffer;
+    /**
+     * Update name-to-id index.
+     */
+    private updateNameIndex;
+    /**
+     * Update runMode-to-id index.
+     */
+    private updateRunModeIndex;
+    /**
+     * Update state-to-id index.
+     */
+    private updateStateIndex;
+    /**
+     * Update combined runMode+state-to-id index.
+     */
+    private updateRunModeStateIndex;
+}