Gateway Durable Runs

Gateway agents journal every turn by default so a restart resumes without re-firing tools or re-billing LLM calls

Gateway agents journal every turn by default, so a gateway restart resumes an interrupted run instead of re-firing side-effecting tools or re-billing LLM calls. No flag needed — it auto-enables whenever your session store is durable (the shipped default). Two explicit opt-outs are supported for the zero-overhead path.

Quick Start

Migration (PR #4218). Prior releases required gateway.durable_runs: true to opt in. The default is now on whenever your session store is durable — no config change needed to gain crash-safe resume. Want the old zero-overhead behaviour? Set gateway.durable_runs: false or gateway.reliability: "off".

1. Zero-config default (crash-safe out of the box)

   Sessions persist by default, so durable runs are already on — no gateway: block required:

   # gateway.yaml
   agents:
     order_processor:
       instructions: "Charge the card and ship the order."
       tools: [charge_card, ship_order, notify_customer]
   

   Restart the gateway mid-run and the interrupted turn resumes — recorded tool results replay from the RunJournal instead of re-charging the card or re-billing the model.

2. Opt out (zero-overhead path)

   Two explicit escape hatches turn durable runs off:

   # gateway.yaml — either one opts out
   gateway:
     durable_runs: false     # explicit off
     # reliability: "off"    # immediate-teardown posture also forces off
   

   In-memory sessions disable it too — with session.persist: false there is no durable store to journal against, so durable runs silently stay off.

3. Override per agent

   A per-agent durable flag wins in both directions — opt one agent out even when the gateway default is on, or opt one in even when it’s off:

   gateway:
     durable_runs: false      # gateway-wide off
   
   agents:
     order_processor:
       instructions: "Charge the card and ship the order."
       durable: true          # this one agent is durable
     chit_chat:
       instructions: "Small talk only."
       # inherits the gateway default (non-durable)
   
4. Toggle the default off from the environment

   gateway.durable_runs accepts an ${ENV_VAR}-substituted string. Because ${DURABLE} renders as a string, the value is coerced explicitly — "false"/"0"/"no"/"off"/"" disable, and "true"/"1"/"yes"/"on" enable:

   # ${DURABLE} → "false" from the environment
   gateway:
     durable_runs: ${DURABLE}   # "false"/"0"/"no"/"off"/"" disable; "true"/"1"/"yes"/"on" enable
   

   "false" really means false here. Without this coercion, bool("false") would be truthy and silently enable durability.

---

How It Works

Each gateway agent journals its turn to the core RunJournal; a restart re-drives the loop from the top, replaying journalled steps and running only the un-journalled ones. Whether journalling runs at all is decided from config plus the effective session store.

Role	Responsibility
Gateway	Consults gateway.durable_runs when explicitly set; otherwise auto-enables when the effective session store is durable (self._session_store is not None)
Agent	Journals every model and tool boundary to the core journal
RunJournal	Records results so a restart replays instead of re-executing
Per-agent durable	Overrides the gateway default for a single agent

Choosing whether durable runs run

Precedence ladder: per-agent durable > explicit gateway.durable_runs > gateway.reliability: "off" (forces off) > effective session store (auto-on when durable, off when in-memory).

The durable-runs decision is re-evaluated on every load path — initial load, full-restart reload, and selective reload — so restarting the gateway keeps durability wired.

Zero overhead when off. On an opted-out path the execution hot path is unchanged and ExecutionConfig is never imported.

Graceful degrade. If ExecutionConfig can’t be imported (an older core), the gateway logs a warning and the agent runs non-durably — the gateway never fails to start over durability.

---

How to opt out

There are three ways to end up with durable_runs=false, plus one silent fallback:

1. Explicit off — set gateway.durable_runs: false.
2. Reliability off — set gateway.reliability: "off" (the immediate-teardown posture forces durable runs off for the zero-overhead path).
3. No durable store — set session.persist: false; with no store to journal against, durable runs auto-default to off.
4. Silent fallback — session.persist: true but the persistent store failed to initialise (e.g. absent or read-only ~). The gateway logs the fallback and stays non-durable — worth checking, because operators otherwise assume their intent is honoured.

---

Configuration Options

Config path	Type	Default	Effect
gateway.durable_runs	bool (accepts env-substituted string forms)	true when a durable session store is present (the shipped default); false otherwise or when reliability: "off"	When truthy, every gateway agent is constructed with execution=ExecutionConfig(durable=True) so each turn is journalled to the core RunJournal.
gateway.reliability	str	unset	"off" forces durable_runs off (immediate-teardown, zero-overhead posture). See Gateway Reliability.
session.persist	bool	true	false removes the durable store, so the auto-default disables durable runs. See Gateway Session Persistence.
agents.<id>.durable	bool (accepts string forms)	inherits gateway.durable_runs	Per-agent override — opts a single agent in (or out) regardless of the gateway-wide default.

The underlying agent primitive is ExecutionConfig(durable=True) — see that page for journal_path, resume_run_id, and the resume contract.

---

Common Patterns

Fleet-wide durability with a chit-chat escape hatch — durable runs are already on by default, so opt out only the agents that make small talk:

# no gateway.durable_runs needed — on by default

agents:
  order_processor:
    instructions: "Charge the card and ship the order."
    tools: [charge_card, ship_order]
  chit_chat:
    instructions: "Small talk only."
    durable: false           # no journalling for stateless banter

Toggle by environment — durable in production, off in ephemeral CI:

gateway:
  durable_runs: ${DURABLE}   # export DURABLE=true in prod, DURABLE=false in CI

---

Best Practices

Point journal_path at a persistent volume in containers

The default ~/.praisonai/runs/journal.db is lost when a container is recreated. Configure a mounted volume so the journal survives restarts — see Durable Tool Runs.

Verify the store actually initialised

Durable runs only auto-enable when the session store instantiates. On an absent or read-only home directory the store degrades to in-memory and durable runs silently stay off — check the gateway log for the fallback if you expected crash-safe resume.

Per-agent durable is your escape hatch

Small-talk agents don’t need journalling. Set durable: false on them, keeping the hot path clean for stateless turns even while the gateway default is on.

Compose with session persistence

Durable gateway runs and session persistence are different layers — one resumes the in-flight turn, the other restores conversation history. Both survive a restart and work together.

---

Related

Durable Tool Runs

The underlying agent primitive — ExecutionConfig(durable=True).

Run-State Journal

The SQLite journal durable runs write to.

Gateway Session Persistence

The durable store durable runs auto-enable against.

Gateway Reliability

reliability: "off" forces durable runs off.