Durable execution

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

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 sends wake hints through Redis while the task store owns execution state.
Event and artifact records persist bounded replay and snapshot references.
Protocol bridges 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.

Ship

Identity and boundaries

Recovery and upgrades

Operating the service

Durable execution

Choose a store

Admit work explicitly

Make effects replay-aware

Persist approval and cancellation

Deliver and expose tasks

​Choose a store

​Admit work explicitly

​Make effects replay-aware

​Persist approval and cancellation

​Deliver and expose tasks

Choose a store

Admit work explicitly

Make effects replay-aware

Persist approval and cancellation

Deliver and expose tasks