> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Durable execution

> Persist task ownership and recover replay-aware work with fenced leases and an action ledger.

`DurableTaskSupervisor` persists task ownership for replay-aware host handlers. It is opt-in: ordinary `Agent.run()`, `AgentWorker`, local approvals, and conversation checkpoints keep their existing lifecycle.

## Choose a store

| Store | Guarantee |
| - | - |
| `InMemoryDurableTaskStore` | Local testing; advertises `durable: false` |
| `MongoDBDurableTaskStore` | Persisted bounded aggregates with atomic revision/lease checks and majority+journal writes |

```typescript theme={null}
import { DurableTaskSupervisor, MongoDBDurableTaskStore } from "@agentium/core";

const uri = process.env.DURABLE_MONGO_URI;
if (!uri) throw new Error("Set DURABLE_MONGO_URI");
const store = new MongoDBDurableTaskStore(uri, {
  database: "agentium",
  collection: "durable_tasks",
});
await store.initialize();
const supervisor = new DurableTaskSupervisor(store);
// Register this supervisor with your application's admission and worker lifecycle.
// Close the store when the host has stopped all users of it.
```

## Admit work explicitly

Host admission validates identity, immutable input references, manifest hash, driver version, policy revision, grant references, and budget before creating a task. Tenant/task keys identify records; they do not authenticate callers.

Each task is a bounded aggregate containing state, revision, lease/fence, attempts, reservations, and action/approval audit. The default aggregate limit is 2 MB. Keep large inputs and media in retained referenced storage.

Workers claim with an identity and execute through `supervisor.run()`. Reserve budget before host model work; reservations do not automatically meter arbitrary provider calls. Shared parent/child budgets require host coordination.

## Make effects replay-aware

A driver needs deterministic action IDs and a connector that can reconcile an uncertain external effect. Use `actions.execute()` inside the supervisor's handler, with destination, canonical arguments, and connector version.

* Reusing an action ID with different arguments fails.
* Confirmed actions return their retained result reference without redispatch.
* A recovered executing action becomes `unknown`.
* Unknown actions block the handler until fenced reconciliation establishes an outcome.

`MongoDBDurableDocumentConnector` provides an append-only MongoDB effect with a unique idempotency key and readable receipt. Other connectors must supply their own evidence. A transient HTTP 404 does not prove an effect never happened. This is not exactly-once execution and does not make arbitrary shell commands, emails, or payments safe to replay.

## Persist approval and cancellation

Approval-required actions persist a decision request before suspension and release the lease. A trusted endpoint calls `DurableActionLedger.decide()` with the reviewer, approval ID, and prepared hash. Approval consumption and dispatch intent commit atomically; a consumed approval cannot authorize another dispatch.

Cancellation first persists `cancel_requested`. The supervisor aborts local work and waits for tracked actions to settle. It acknowledges `canceled` only when no executing or unknown action remains. Lease loss prevents stale commits but cannot retract a request already sent to another service.

## Deliver and expose tasks

* [Durable queue delivery](/queue/durable) sends wake hints through Redis while the task store owns execution state.
* [Event and artifact records](/durable/records) persist bounded replay and snapshot references.
* [Protocol bridges](/durable/protocols) expose admitted tasks through HTTP, A2A, or MCP Tasks.

The host owns retention, backups, orphan cleanup, recovery sweeps, current-policy rechecks, and connector reconciliation. Local fixtures and opt-in Mongo crash tests are not evidence of production multi-region or replica-set failover behavior.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.