Gateway Durable Runs

Gateway agents journal every turn so an interrupted turn can be resumed by run id — recorded tool results replay instead of re-firing side effects

Gateway agents journal every turn by default, so an interrupted turn can be resumed by run id without re-firing side-effecting tools or re-billing LLM calls. The gateway does not auto-resume on restart — you resume a turn yourself with ExecutionConfig(durable=True, resume_run_id=..., journal_path=...), the same journal, and the recorded task (see Resuming an interrupted turn). No flag needed for journalling — 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

1. Zero-config default (every turn is journalled)

   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; the interrupted turn is left running in the RunJournal. To finish it without re-charging the card or re-billing the model, resume it by run id — see Resuming an interrupted turn.

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

How It Works

Each gateway agent journals its turn to the core RunJournal whenever durable runs are on — decided from config plus the effective session store. Resuming is a separate, manual step: a turn resumed by run id replays journalled steps and runs only the un-journalled ones.

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).

Resuming an interrupted turn

Nothing resumes interrupted turns automatically. List them from the journal and resume each with its recorded task:

from praisonaiagents import Agent, ExecutionConfig
from praisonaiagents.runtime import RunJournal

journal = RunJournal()  # default ~/.praisonai/runs/journal.db — pass the gateway's journal_path if set
for run_id in journal.interrupted_runs():
    meta = journal.run_meta(run_id)
    agent = Agent(
        name=meta.agent,
        instructions="Charge the card and ship the order.",
        execution=ExecutionConfig(durable=True, resume_run_id=run_id),
    )
    agent.chat(meta.task)  # must be the recorded task

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

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

Related