Gateway Approval Durability

Survive gateway restarts with persisted pending approvals using the secure approval backend

Use --approval secure so pending approvals survive a gateway restart — the SQLite-backed PresentationApprovalBackend persists every decision and rehydrates outstanding requests on startup.

graph LR
    subgraph "Gateway Approval Durability"
        Agent[🤖 Agent] --> Backend[🔒 PresentationApproval\nBackend]
        Backend --> Store[(💾 SQLite\nStore)]
        Store --> Restart[🔄 Restart]
        Restart --> Rehydrate[📥 rehydrate()]
        Rehydrate --> Resolve[✅ Same request\nresolvable]
    end

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef storage fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff

    class Agent agent
    class Backend,Rehydrate process
    class Store storage
    class Restart,Resolve result

Quick Start

1. Set required env vars (CLI only)

   export PRAISONAI_APPROVAL_ACTORS="your-user-id"
   export PRAISONAI_HOME=/var/lib/praisonai   # optional, overrides ~/.praisonai

   PRAISONAI_APPROVAL_ACTORS is required when using --approval secure from the CLI. For the Python API, pass allowed_actors= directly to PresentationApprovalBackend (see next step).

2. Agent-centric example

   import os
   from praisonai.bots import ApprovalStore, PresentationApprovalBackend
   from praisonaiagents import Agent
   
   store = ApprovalStore(path=os.path.expanduser("~/.praisonai/state/approvals.sqlite"))
   backend = PresentationApprovalBackend(
       store=store,
       allowed_actors={"your-user-id"},
   )
   
   agent = Agent(
       name="Ops",
       instructions="You are a careful ops assistant. Ask before destructive commands.",
       approval=backend,
       tools=["execute_command"],
   )
   
   agent.start("Clean up /tmp/cache")
   # The gateway asks the human once. Restart the gateway — the pending request
   # is rehydrated from SQLite and the human can still Allow or Deny.

3. CLI usage

   praisonai run --approval secure agent.py

How It Works

Configuration

Default persistence paths

Override the root with PRAISONAI_HOME:

export PRAISONAI_HOME=/var/lib/praisonai
# Store will be created under /var/lib/praisonai/state/approvals.sqlite

Programmatic Override

from pathlib import Path
from praisonai.bots import ApprovalStore, PresentationApprovalBackend
from praisonaiagents import Agent
from praisonaiagents.approval import ApprovalConfig

store = ApprovalStore(path="/var/lib/praisonai/state/approvals.sqlite")
backend = PresentationApprovalBackend(
    store=store,
    allowed_actors={"user-123", "ops-team"},
    timeout=600,
)

agent = Agent(
    name="Ops",
    instructions="Ask before destructive commands.",
    approval=ApprovalConfig(backend=backend, all_tools=True),
)

PresentationApprovalBackend constructor parameters:

What Happens on Restart

• No live awaiter: the awaiting agent call was lost with the previous process. Rehydrated requests stay resolvable via the gateway UI or API. The audit trail records the terminal state.
• Expiry is preserved: rehydrate() filters by stored expires_at, so a nearly-expired approval is not inadvertently extended.
• Custody survives restart: authorized_reviewers on a pending request is persisted and rehydrated by the same SQLite store, so per-request reviewer bindings survive a gateway restart. See Per-request reviewer custody.
• Fail-open startup: a corrupted store logs the error and returns 0 — it never blocks gateway startup.

What Happens on /stop or Supersede

Pending approvals bound to a superseded turn are cancelled fail-closed via cancel_for_generation() — the awaiting tool call unwinds promptly with reason="cancelled". A resolution that arrives after the supersede is dropped and recorded with reason="superseded" in the audit trail, so a late reviewer decision never fires a stale tool or delivers a stale reply.

This binding is a no-op for approvals that carry no session_id/run_generation. See Approval Turn Liveness.

Best Practices

Related