Saga Engine

Transactional middleware for AI agents — Ctrl+Z for the real world.


Saga Engine implements the Saga pattern for AI agents and autonomous systems. When your agent books a flight, reserves a hotel, and then fails to rent a car — Saga Engine automatically cancels the hotel and flight in reverse order.

Why Saga Engine?

AI agents are increasingly performing real-world actions: booking travel, processing payments, managing infrastructure. But what happens when step 5 of 7 fails?

Without Saga Engine: Manual cleanup, inconsistent state, frustrated users.

With Saga Engine: Automatic rollback, consistent state, reliable operations.

``typescript
const result = await orchestrator.execute(bookTripSaga, {
flight: { from: 'NYC', to: 'LAX' },
hotel: { city: 'Los Angeles', nights: 3 },
car: { pickup: 'LAX' }
});

if (!result.success) {
// Flight and hotel automatically cancelled
console.log('Booking failed, all changes rolled back');
}
`

Features

- Automatic Compensation — Define rollback logic once, executed automatically on failure
- Type-Safe — Full TypeScript support with generics for input/output types
- Pluggable Storage — In-memory for dev, Redis/Postgres for production
- Observable — Rich event system for monitoring and debugging
- Crash Recovery — Resume interrupted sagas after process restart
- Battle-Tested — 193+ tests covering edge cases and production scenarios

Installation

`bash
npm install @saga-engine/core


or

pnpm add @saga-engine/core

or

yarn add @saga-engine/core
`

Quick Start

`typescript
import { Saga, SagaOrchestrator, InMemoryStore } from '@saga-engine/core';

// 1. Define your saga with steps and compensations
const orderSaga = new Saga<{ orderId: string; amount: number }>('process-order')
.step({
name: 'reserve-inventory',
execute: async (ctx) => {
const reservation = await inventoryService.reserve(ctx.input.orderId);
return { reservationId: reservation.id };
},
compensate: async (ctx, result) => {
await inventoryService.release(result.reservationId);
}
})
.step({
name: 'charge-payment',
execute: async (ctx) => {
const charge = await paymentService.charge(ctx.input.amount);
return { chargeId: charge.id };
},
compensate: async (ctx, result) => {
await paymentService.refund(result.chargeId);
}
})
.step({
name: 'send-confirmation',
execute: async (ctx) => {
await emailService.send(ctx.input.orderId, 'Order confirmed!');
return { sent: true };
}
});

// 2. Create orchestrator with storage
const orchestrator = new SagaOrchestrator({
store: new InMemoryStore()
});

// 3. Execute the saga
const result = await orchestrator.execute(orderSaga, {
orderId: 'ORD-123',
amount: 99.99
});

if (result.success) {
console.log('Order processed:', result.stepResults);
} else {
console.log('Order failed:', result.error.message);
console.log('Compensated:', result.compensated);
}
`

Core Concepts

$3

A saga is a sequence of steps that form a logical transaction. Each step can have:
- execute — The action to perform
- compensate — The rollback action (optional)

`typescript
const saga = new Saga('saga-name')
.step({ name: 'step-1', execute: async (ctx) => {...}, compensate: async (ctx, result) => {...} })
.step({ name: 'step-2', execute: async (ctx) => {...} });
`

$3

Each step receives a context with:
- sagaId — Unique execution ID
- input — The input provided when starting the saga
- stepResults — Results from previous steps (Map)

`typescript
execute: async (ctx) => {
const previousResult = ctx.stepResults.get('previous-step');
return { processed: ctx.input.data };
}
`

$3

When a step fails, compensation runs in reverse order for all completed steps:

`
Step 1: reserve-inventory ✅
Step 2: charge-payment ✅
Step 3: send-email ❌ FAILED

Compensation:
→ charge-payment.compensate() // Refund
→ reserve-inventory.compensate() // Release
`

$3

`typescript
const orchestrator = new SagaOrchestrator({
store: new InMemoryStore(),
onCompensationFailure: 'continue', // 'retry' | 'continue' | 'halt'
compensationRetries: 3, // For 'retry' strategy
compensationRetryDelay: 1000 // Milliseconds between retries
});
`

Events

Monitor saga execution with events:

`typescript
orchestrator.on('saga:started', (state) => {
console.log(Saga ${state.sagaName} started);
});

orchestrator.on('step:executed', (state, stepName, result) => {
console.log(Step ${stepName} completed:, result);
});

orchestrator.on('step:failed', (state, stepName, error) => {
console.log(Step ${stepName} failed:, error.message);
});

orchestrator.on('compensation:started', (state) => {
console.log('Starting rollback...');
});

orchestrator.on('compensation:completed', (state) => {
console.log('Rollback complete');
});

orchestrator.on('saga:completed', (state) => {
console.log('Saga completed successfully');
});

orchestrator.on('saga:failed', (state, error) => {
console.log('Saga failed:', error.message);
});
`

Storage Adapters

$3

`typescript
import { InMemoryStore } from '@saga-engine/core';

const store = new InMemoryStore();
`

$3

`typescript
import { RedisStore } from '@saga-engine/redis';

const store = new RedisStore({
url: 'redis://localhost:6379',
keyPrefix: 'saga:'
});
`

$3

`typescript
import { PostgresStore } from '@saga-engine/postgres';

const store = new PostgresStore({
connectionString: process.env.DATABASE_URL
});
`

$3

Implement the StateStore interface:

`typescript
interface StateStore {
create(state: SagaState): Promise;
get(sagaId: string): Promise;
updateStatus(sagaId: string, status: SagaStatus, completedAt?: Date): Promise;
updateStep(sagaId: string, stepName: string, stepState: Partial): Promise;
getPendingSagas(): Promise;
delete?(sagaId: string): Promise;
close?(): Promise;
}
`

Crash Recovery

Recover interrupted sagas on startup:

`typescript
const orchestrator = new SagaOrchestrator({ store: redisStore });

// On application startup
await orchestrator.recover();
`

Examples

$3

`typescript
const processOrderSaga = new Saga('process-order')
.step({
name: 'validate-cart',
execute: async (ctx) => {
const valid = await cartService.validate(ctx.input.cartId);
if (!valid) throw new Error('Invalid cart');
return { validated: true };
}
})
.step({
name: 'reserve-inventory',
execute: async (ctx) => {
const items = await inventoryService.reserve(ctx.input.items);
return { reservedItems: items };
},
compensate: async (ctx, result) => {
await inventoryService.release(result.reservedItems);
}
})
.step({
name: 'process-payment',
execute: async (ctx) => {
const payment = await paymentService.charge({
amount: ctx.input.total,
customerId: ctx.input.customerId
});
return { paymentId: payment.id };
},
compensate: async (ctx, result) => {
await paymentService.refund(result.paymentId);
}
})
.step({
name: 'create-shipment',
execute: async (ctx) => {
const shipment = await shippingService.create({
address: ctx.input.shippingAddress,
items: ctx.stepResults.get('reserve-inventory').reservedItems
});
return { trackingNumber: shipment.tracking };
},
compensate: async (ctx, result) => {
await shippingService.cancel(result.trackingNumber);
}
});
`

$3

`typescript
const agentTaskSaga = new Saga('agent-task')
.step({
name: 'acquire-resources',
execute: async (ctx) => {
const resources = await resourceManager.acquire(ctx.input.requirements);
return { resourceIds: resources.map(r => r.id) };
},
compensate: async (ctx, result) => {
await resourceManager.release(result.resourceIds);
}
})
.step({
name: 'execute-action',
execute: async (ctx) => {
const result = await actionExecutor.run(ctx.input.action);
return { actionResult: result };
},
compensate: async (ctx, result) => {
await actionExecutor.undo(result.actionResult);
}
})
.step({
name: 'commit-changes',
execute: async (ctx) => {
await changeTracker.commit(ctx.sagaId);
return { committed: true };
}
});
`

Integration with AI Frameworks

$3

`typescript
import { Tool } from 'langchain/tools';

const bookingTool = new Tool({
name: 'book-travel',
description: 'Book flights and hotels with automatic rollback on failure',
func: async (input: string) => {
const params = JSON.parse(input);
const result = await orchestrator.execute(bookTripSaga, params);
return JSON.stringify(result);
}
});
`

$3

`typescript
import { tool } from 'ai';

const processOrderTool = tool({
description: 'Process an order with inventory, payment, and shipping',
parameters: z.object({
orderId: z.string(),
items: z.array(z.object({ sku: z.string(), quantity: z.number() })),
customerId: z.string()
}),
execute: async (params) => {
return orchestrator.execute(orderSaga, params);
}
});
`

API Reference

$3

`typescript
new Saga(name: string)
.step(definition: StepDefinition): Saga
.addSteps(definitions: StepDefinition[]): Saga
.getStep(name: string): SagaStep | undefined
.hasSteps(): boolean
.steps: ReadonlyArray
.stepCount: number
.name: string
`

$3

`typescript
new SagaOrchestrator(options: OrchestratorOptions & { store: StateStore })
.execute(saga: Saga, input: TInput): Promise>
.recover(): Promise
.on(event: K, callback: SagaEvents[K]): void
.off(event: K, callback: SagaEvents[K]): void
`

$3

`typescript
interface SagaResult {
success: boolean;
sagaId: string;
result?: TResult; // On success
stepResults?: Map;
error?: Error; // On failure
failedStep?: string;
compensated?: boolean;
compensationErrors?: Array<{ step: string; error: Error }>;
}

interface SagaContext {
sagaId: string;
input: TInput;
stepResults: Map;
}

interface StepDefinition {
name: string;
execute: (ctx: SagaContext) => Promise;
compensate?: (ctx: SagaContext, result: TResult) => Promise;
}
`

Enterprise Features

Looking for advanced features? Check out Saga Engine Cloud:

- Hosted State Management — Durable storage with global replication
- Observability Dashboard — Real-time monitoring, tracing, and analytics
- Team Collaboration — Role-based access control and audit logs
- SLA Guarantees — 99.99% uptime with dedicated support

Contact us for Enterprise pricing →

Contributing

We welcome contributions! Please see our Contributing Guide for details.

`bash


Clone the repository

git clone https://github.com/Chetan-svg/saga-engine.git
cd saga-engine

Install dependencies

pnpm install

Run tests

pnpm test

Build

pnpm build
``

License

MIT © Verto AI LLC

---

Website •
Documentation •
Issues