transactional-ai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 omar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+# Transactional AI
+
+**A reliability protocol for AI Agents.**
+Implement the Saga Pattern with persistent rollback and state recovery for Long-Running Machine (LLM) operations.
+
+[![npm version](https://img.shields.io/npm/v/transactional-ai.svg)](https://www.npmjs.com/package/transactional-ai)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Why use this?
+AI Agents are flaky. Steps fail, APIs time out, and hallucinations happen.
+`transactional-ai` gives you:
+1.  **Automatic Rollbacks**: If step 3 fails, steps 2 and 1 are compensated (undone) automatically.
+2.  **Persistence**: Transactions survive process crashes using Redis or File storage.
+3.  **Observability**: Inspect running transactions via the built-in CLI.
+
+## Installation
+
+```bash
+npm install transactional-ai
+```
+
+---
+
+## Quick Start
+
+### 1. The "Litmus Test" (Basic Usage)
+Define a transaction where every action has a compensating rollback action.
+
+```typescript
+import { Transaction } from 'transactional-ai';
+
+// 1. Create a named transaction (required for resumability)
+const agent = new Transaction('user-onboarding-123');
+
+agent
+  .step({
+    name: 'create-file',
+    execute: async (ctx) => {
+       // Do the work
+       const file = await googleDrive.createFile('report.txt');
+       return file.id; 
+    },
+    compensate: async (fileId) => {
+       // Undo the work
+       await googleDrive.deleteFile(fileId);
+    }
+  })
+  .step({
+    name: 'email-report',
+    execute: async (ctx) => {
+       // Use previous results via context or external state
+       await emailService.send(ctx.result);
+    },
+    compensate: async () => {
+       await emailService.recallLast();
+    }
+  });
+
+// 2. Run it
+await agent.run({ initialData: 'foo' });
+```
+
+### Adding Persistence (Redis)
+To survive process crashes, simply provide a storage adapter.
+
+```typescript
+import { Transaction, RedisStorage } from 'transactional-ai';
+
+const storage = new RedisStorage('redis://localhost:6379');
+const agent = new Transaction('workflow-id-555', storage);
+
+// If the process crashes here, running this code again
+// will automatically SKIP completed steps and resume at the failure point.
+agent
+  .step({ /* ... */ })
+  .step({ /* ... */ });
+
+await agent.run();
+```
+
+---
+
+## CLI Inspector
+You don't need a complex dashboard to see what your agents are doing. Use the included CLI to inspect transaction logs directly from your terminal.
+
+```bash
+# Inspect a specific transaction ID (File Storage)
+npx tai-inspect workflow-id-555
+
+# Inspect using Redis
+export REDIS_URL="redis://localhost:6379"
+npx tai-inspect workflow-id-555
+```
+
+Output:
+
+```
+🔍 Inspecting: workflow-id-555
+     Source: RedisStorage
+
+     STEP NAME            | STATUS
+     ------------------------------------
+     ├── create-file      | ✅ completed
+     │       └-> Result: "file_xyz123"
+     ├── email-report     | ❌ failed
+     └── (comp) create-f..| ✅ completed
+```
+
+---
+
+## Advanced Usage
+
+### Audit Mode (Governance)
+By default, logs are cleared upon success to save storage space. To keep a permanent audit trail for compliance (e.g., "Why did the agent do this?"), enable Audit Mode:
+
+```typescript
+const agent = new Transaction('id', storage, {
+    cleanupOnSuccess: false
+});
+```
+
+### Manual Rollbacks
+The library handles rollbacks automatically on error. You can trigger them manually by throwing an error inside any step:
+
+```typescript
+// Define a step that throws an error to trigger rollback
+agent.step({
+    name: 'check-balance',
+    execute: async (ctx) => {
+        const balance = await getBalance(ctx.userId);
+        if (balance < 10) {
+             // Throwing an error automatically triggers the compensation 
+             // for all previous steps.
+             throw new Error("Insufficient funds"); 
+        }
+    },
+    compensate: async () => {
+        // No compensation needed for a read-only check
+    }
+});
+```
+
+---
+
+## Roadmap
+[x] Core Saga Engine (Execute/Compensate)
+
+[x] Persistence Adapters (File, Redis)
+
+[x] Resumability (Skip completed steps)
+
+[x] CLI Inspector (tai-inspect)
+
+[ ] Concurrent Transaction Locking
+
+[ ] Postgres/SQL Storage Adapter
+
+---
+
+## License
+MIT

package/dist/bin/inspect.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=inspect.d.ts.map

package/dist/bin/inspect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../bin/inspect.ts"],"names":[],"mappings":""}

package/dist/bin/inspect.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const RedisStorage_1 = require("../engine/RedisStorage");
+const FileStorage_1 = require("../engine/FileStorage");
+async function main() {
+    const [, , txId] = process.argv;
+    if (!txId) {
+        console.error("Usage: npx transactional-ai inspect <transaction-id>");
+        process.exit(1);
+    }
+    // Auto-detect storage based on Env Var
+    const storage = process.env.REDIS_URL
+        ? new RedisStorage_1.RedisStorage(process.env.REDIS_URL)
+        : new FileStorage_1.FileStorage();
+    console.log(`\n🔍 Inspecting Transaction: ${txId}`);
+    console.log(`   Source: ${storage.constructor.name}\n`);
+    const history = await storage.load(txId);
+    if (!history) {
+        console.error("❌ Transaction not found.");
+        process.exit(1);
+    }
+    console.log("   STEP NAME            | STATUS ");
+    console.log("   ------------------------------------");
+    history.forEach((step, index) => {
+        const isLast = index === history.length - 1;
+        // Simple ASCII Tree
+        const prefix = isLast ? "└──" : "├──";
+        // Status Icon
+        const icon = step.status === 'completed' ? '✅' : '⏳';
+        console.log(`   ${prefix} ${step.name.padEnd(20)} | ${icon} ${step.status}`);
+        // If there is a result and it's small, show it
+        if (step.result && typeof step.result === 'string' && step.result.length < 50) {
+            console.log(`       └-> Result: ${step.result}`);
+        }
+    });
+    console.log("\n");
+    if (storage instanceof RedisStorage_1.RedisStorage) {
+        await storage.disconnect();
+    }
+}
+main().catch(console.error);
+//# sourceMappingURL=inspect.js.map

package/dist/bin/inspect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.js","sourceRoot":"","sources":["../../bin/inspect.ts"],"names":[],"mappings":";;;AACA,yDAAsD;AACtD,uDAAoD;AAEpD,KAAK,UAAU,IAAI;IACjB,MAAM,CAAC,EAAC,EAAE,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAE/B,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,CAAC,KAAK,CAAC,sDAAsD,CAAC,CAAC;QACtE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,uCAAuC;IACvC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS;QACnC,CAAC,CAAC,IAAI,2BAAY,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC;QACzC,CAAC,CAAC,IAAI,yBAAW,EAAE,CAAC;IAEtB,OAAO,CAAC,GAAG,CAAC,gCAAgC,IAAI,EAAE,CAAC,CAAC;IACpD,OAAO,CAAC,GAAG,CAAC,cAAc,OAAO,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC,CAAC;IAExD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEzC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;QAC1C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC;IACjD,OAAO,CAAC,GAAG,CAAC,yCAAyC,CAAC,CAAC;IAEvD,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;QAC9B,MAAM,MAAM,GAAG,KAAK,KAAK,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;QAC5C,oBAAoB;QACpB,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;QAEtC,cAAc;QACd,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;QAErD,OAAO,CAAC,GAAG,CAAC,MAAM,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,IAAI,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QAE7E,+CAA+C;QAC/C,IAAI,IAAI,CAAC,MAAM,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;YAC7E,OAAO,CAAC,GAAG,CAAC,sBAAsB,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QACpD,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAElB,IAAI,OAAO,YAAY,2BAAY,EAAE,CAAC;QACpC,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC;IAC7B,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC"}

package/dist/engine/FileStorage.d.ts

@@ -0,0 +1,10 @@
+import { StorageAdapter } from './Storage';
+import { StepContext } from './Transaction';
+export declare class FileStorage implements StorageAdapter {
+    private dir;
+    init(): Promise<void>;
+    save(txId: string, state: StepContext[]): Promise<void>;
+    load(txId: string): Promise<StepContext[] | null>;
+    clear(txId: string): Promise<void>;
+}
+//# sourceMappingURL=FileStorage.d.ts.map

package/dist/engine/FileStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileStorage.d.ts","sourceRoot":"","sources":["../../engine/FileStorage.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,qBAAa,WAAY,YAAW,cAAc;IAChD,OAAO,CAAC,GAAG,CAAiD;IAEtD,IAAI;IAIJ,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAKvD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC;IASjD,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGzC"}

package/dist/engine/FileStorage.js

@@ -0,0 +1,38 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileStorage = void 0;
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+class FileStorage {
+    dir = path_1.default.join(process.cwd(), '.transaction-logs');
+    async init() {
+        try {
+            await promises_1.default.mkdir(this.dir, { recursive: true });
+        }
+        catch { }
+    }
+    async save(txId, state) {
+        await this.init();
+        await promises_1.default.writeFile(path_1.default.join(this.dir, `${txId}.json`), JSON.stringify(state, null, 2));
+    }
+    async load(txId) {
+        try {
+            const data = await promises_1.default.readFile(path_1.default.join(this.dir, `${txId}.json`), 'utf-8');
+            return JSON.parse(data);
+        }
+        catch {
+            return null;
+        }
+    }
+    async clear(txId) {
+        try {
+            await promises_1.default.unlink(path_1.default.join(this.dir, `${txId}.json`));
+        }
+        catch { }
+    }
+}
+exports.FileStorage = FileStorage;
+//# sourceMappingURL=FileStorage.js.map

package/dist/engine/FileStorage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileStorage.js","sourceRoot":"","sources":["../../engine/FileStorage.ts"],"names":[],"mappings":";;;;;;AAAA,2DAA6B;AAC7B,gDAAwB;AAIxB,MAAa,WAAW;IACd,GAAG,GAAG,cAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,mBAAmB,CAAC,CAAC;IAE5D,KAAK,CAAC,IAAI;QACR,IAAI,CAAC;YAAC,MAAM,kBAAE,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAA,CAAC;IACjE,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,IAAY,EAAE,KAAoB;QAC3C,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,MAAM,kBAAE,CAAC,SAAS,CAAC,cAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,OAAO,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAC1F,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,IAAY;QACrB,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,kBAAE,CAAC,QAAQ,CAAC,cAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;YAC7E,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,IAAY;QACtB,IAAI,CAAC;YAAC,MAAM,kBAAE,CAAC,MAAM,CAAC,cAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAA,CAAC;IACxE,CAAC;CACF;AAxBD,kCAwBC"}

package/dist/engine/RedisStorage.d.ts

@@ -0,0 +1,16 @@
+import { StorageAdapter } from './Storage';
+import { StepContext } from './Transaction';
+export declare class RedisStorage implements StorageAdapter {
+    private redis;
+    private ttlSeconds;
+    /**
+     * @param connectionString Redis connection URL (e.g., "redis://localhost:6379")
+     * @param ttlSeconds How long to keep logs (default: 1 hour)
+     */
+    constructor(connectionString: string, ttlSeconds?: number);
+    save(txId: string, state: StepContext[]): Promise<void>;
+    load(txId: string): Promise<StepContext[] | null>;
+    clear(txId: string): Promise<void>;
+    disconnect(): Promise<void>;
+}
+//# sourceMappingURL=RedisStorage.d.ts.map

package/dist/engine/RedisStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RedisStorage.d.ts","sourceRoot":"","sources":["../../engine/RedisStorage.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,qBAAa,YAAa,YAAW,cAAc;IACjD,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,UAAU,CAAS;IAE3B;;;OAGG;gBACS,gBAAgB,EAAE,MAAM,EAAE,UAAU,SAAO;IAKjD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAOvD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC;IAKjD,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlC,UAAU;CAGjB"}

package/dist/engine/RedisStorage.js

@@ -0,0 +1,38 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisStorage = void 0;
+const ioredis_1 = __importDefault(require("ioredis"));
+class RedisStorage {
+    redis;
+    ttlSeconds;
+    /**
+     * @param connectionString Redis connection URL (e.g., "redis://localhost:6379")
+     * @param ttlSeconds How long to keep logs (default: 1 hour)
+     */
+    constructor(connectionString, ttlSeconds = 3600) {
+        this.redis = new ioredis_1.default(connectionString);
+        this.ttlSeconds = ttlSeconds;
+    }
+    async save(txId, state) {
+        const key = `tx:${txId}`;
+        await this.redis.set(key, JSON.stringify(state));
+        // Reset expiration timer on every update so active transactions don't expire
+        await this.redis.expire(key, this.ttlSeconds);
+    }
+    async load(txId) {
+        const data = await this.redis.get(`tx:${txId}`);
+        return data ? JSON.parse(data) : null;
+    }
+    async clear(txId) {
+        await this.redis.del(`tx:${txId}`);
+    }
+    // Helper to close connection when app shuts down
+    async disconnect() {
+        await this.redis.quit();
+    }
+}
+exports.RedisStorage = RedisStorage;
+//# sourceMappingURL=RedisStorage.js.map

package/dist/engine/RedisStorage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RedisStorage.js","sourceRoot":"","sources":["../../engine/RedisStorage.ts"],"names":[],"mappings":";;;;;;AAAA,sDAA4B;AAI5B,MAAa,YAAY;IACf,KAAK,CAAQ;IACb,UAAU,CAAS;IAE3B;;;OAGG;IACH,YAAY,gBAAwB,EAAE,UAAU,GAAG,IAAI;QACrD,IAAI,CAAC,KAAK,GAAG,IAAI,iBAAK,CAAC,gBAAgB,CAAC,CAAC;QACzC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,IAAY,EAAE,KAAoB;QAC3C,MAAM,GAAG,GAAG,MAAM,IAAI,EAAE,CAAC;QACzB,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;QACjD,6EAA6E;QAC7E,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IAChD,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,IAAY;QACrB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;QAChD,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,IAAY;QACtB,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;IACrC,CAAC;IAED,iDAAiD;IACjD,KAAK,CAAC,UAAU;QACd,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IAC1B,CAAC;CACF;AAjCD,oCAiCC"}

package/dist/engine/Storage.d.ts

@@ -0,0 +1,7 @@
+import { StepContext } from './Transaction';
+export interface StorageAdapter {
+    save(transactionId: string, state: StepContext[]): Promise<void>;
+    load(transactionId: string): Promise<StepContext[] | null>;
+    clear(transactionId: string): Promise<void>;
+}
+//# sourceMappingURL=Storage.d.ts.map

package/dist/engine/Storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Storage.d.ts","sourceRoot":"","sources":["../../engine/Storage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,CAAC;IAC3D,KAAK,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C"}

package/dist/engine/Storage.js

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

package/dist/engine/Storage.js.map

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

package/dist/engine/Transaction.d.ts

@@ -0,0 +1,26 @@
+import { StorageAdapter } from './Storage';
+export type StepContext<T = any> = {
+    name: string;
+    result?: T;
+    status: 'completed' | 'pending';
+};
+export type StepDefinition<T> = {
+    do: () => Promise<T> | T;
+    undo: (result: T) => Promise<void> | void;
+};
+type TransactionOptions = {
+    cleanupOnSuccess?: boolean;
+};
+export declare class Transaction {
+    private stepStack;
+    private history;
+    private id;
+    private storage?;
+    private cleanupOnSuccess;
+    constructor(id: string, storage?: StorageAdapter, options?: TransactionOptions);
+    run(workflow: (tx: Transaction) => Promise<void>): Promise<void>;
+    step<T>(name: string, definition: StepDefinition<T>): Promise<T>;
+    private rollback;
+}
+export {};
+//# sourceMappingURL=Transaction.d.ts.map

package/dist/engine/Transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Transaction.d.ts","sourceRoot":"","sources":["../../engine/Transaction.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAE3C,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,GAAG,IAAI;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,CAAC,CAAC;IACX,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI;IAC9B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACzB,IAAI,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC3C,CAAC;AASF,KAAK,kBAAkB,GAAG;IACxB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF,qBAAa,WAAW;IACtB,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,OAAO,CAAC,CAAiB;IACjC,OAAO,CAAC,gBAAgB,CAAU;gBAEtB,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,EAAE,OAAO,GAAE,kBAAuB;IAO5E,GAAG,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBhE,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;YAgCxD,QAAQ;CAWvB"}

package/dist/engine/Transaction.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Transaction = void 0;
+class Transaction {
+    stepStack = [];
+    history = new Map();
+    id;
+    storage;
+    cleanupOnSuccess;
+    constructor(id, storage, options = {}) {
+        this.id = id;
+        this.storage = storage;
+        // Default to TRUE (clean up) unless told otherwise
+        this.cleanupOnSuccess = options.cleanupOnSuccess ?? true;
+    }
+    async run(workflow) {
+        // 1. Load previous state if storage is provided
+        if (this.storage) {
+            const savedState = await this.storage.load(this.id);
+            if (savedState) {
+                console.log(`[Transaction] 🔄 Resuming ${this.id} with ${savedState.length} completed steps.`);
+                savedState.forEach(s => this.history.set(s.name, s.result));
+                // Note: We can't re-hydrate the 'undo' functions until the code runs again.
+                // The 'step' method handles re-hydrating the stack.
+            }
+        }
+        try {
+            await workflow(this);
+            // CHANGED: Only clear if flag is true
+            if (this.storage && this.cleanupOnSuccess) {
+                await this.storage.clear(this.id);
+            }
+        }
+        catch (error) {
+            console.error(`\n🔴 [Transaction Failed] Error: ${error instanceof Error ? error.message : error}`);
+            await this.rollback();
+            throw error;
+        }
+    }
+    async step(name, definition) {
+        // 1. Check if we already did this step (Resumability!)
+        if (this.history.has(name)) {
+            console.log(`⏩ [Skip: ${name}] Already completed.`);
+            const result = this.history.get(name);
+            // CRITICAL: We still need to push the undo handler to the stack 
+            // so we can rollback if a LATER step fails.
+            this.stepStack.push({ name, undo: () => definition.undo(result) });
+            return result;
+        }
+        // 2. If not, Execute
+        console.log(`➡️  [Do: ${name}] Executing...`);
+        const result = await definition.do();
+        // 3. Update State
+        this.stepStack.push({ name, undo: () => definition.undo(result) });
+        // 4. Persist
+        if (this.storage) {
+            const currentHistory = this.stepStack.map(s => ({
+                name: s.name,
+                result: s.name === name ? result : this.history.get(s.name), // simplified for demo
+                status: 'completed'
+            }));
+            // In a real app, map the full history properly
+            await this.storage.save(this.id, currentHistory);
+        }
+        return result;
+    }
+    async rollback() {
+        const stepsToUndo = [...this.stepStack].reverse();
+        for (const step of stepsToUndo) {
+            console.log(`⬅️  [Undo: ${step.name}] Reverting...`);
+            try {
+                await step.undo();
+            }
+            catch (err) {
+                console.error(`   ❌ [CRITICAL] Undo failed for '${step.name}'`, err);
+            }
+        }
+        // Clear storage after rollback so we don't resume into a broken state
+        if (this.storage)
+            await this.storage.clear(this.id);
+        this.stepStack = [];
+    }
+}
+exports.Transaction = Transaction;
+//# sourceMappingURL=Transaction.js.map

package/dist/engine/Transaction.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { Transaction } from './engine/Transaction';
+export type { StepContext, StepDefinition } from './engine/Transaction';
+export { StorageAdapter } from './engine/Storage';
+export { FileStorage } from './engine/FileStorage';
+export { RedisStorage } from './engine/RedisStorage';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGxE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisStorage = exports.FileStorage = exports.Transaction = void 0;
+// Export the core engine
+var Transaction_1 = require("./engine/Transaction");
+Object.defineProperty(exports, "Transaction", { enumerable: true, get: function () { return Transaction_1.Transaction; } });
+var FileStorage_1 = require("./engine/FileStorage");
+Object.defineProperty(exports, "FileStorage", { enumerable: true, get: function () { return FileStorage_1.FileStorage; } });
+var RedisStorage_1 = require("./engine/RedisStorage");
+Object.defineProperty(exports, "RedisStorage", { enumerable: true, get: function () { return RedisStorage_1.RedisStorage; } });
+// We do NOT export the internal 'examples' or 'bin' scripts.
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":";;;AAAA,yBAAyB;AACzB,oDAAmD;AAA1C,0GAAA,WAAW,OAAA;AAKpB,oDAAmD;AAA1C,0GAAA,WAAW,OAAA;AACpB,sDAAqD;AAA5C,4GAAA,YAAY,OAAA;AAErB,6DAA6D"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "transactional-ai",
+  "version": "0.1.0",
+  "description": "A reliability protocol for AI Agents. Saga pattern with persistent rollback.",
+  "main": "dist/index.js",
+  "bin": {
+    "tai-inspect": "dist/bin/inspect.js"
+  },
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "postbuild": "chmod +x dist/bin/inspect.js",
+    "test": "jest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "transaction",
+    "saga",
+    "reliability",
+    "llm"
+  ],
+  "author": "Your Name",
+  "license": "MIT",
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.1",
+    "@types/ioredis": "^5.0.0",
+    "@types/jest": "^30.0.0",
+    "jest": "^30.2.0",
+    "jest-environment-jsdom": "^30.2.0",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "ts-jest": "^29.4.6",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@prisma/client": "6.15.0",
+    "ioredis": "^5.9.1",
+    "node-fetch": "^3.3.2",
+    "openai": "^6.15.0",
+    "prisma": "6.15.0"
+  }
+}