03 — How it works
Four layers. Durable claim semantics.
01
Request-ID deduplication
Every tool call gets a deterministic request_id before execution. Settled IDs return a receipt; unresolved IDs remain PENDING and require provider reconciliation.
02
Finality gating
Ambiguous agent signals block execution. Side effects only run when the outcome is confirmed final — not just probable.
03
Durable receipts
SQLite-backed by default. Every execution stored with payload and outcome. Survives process restarts. Full audit trail.
04
State machine enforcement
OPEN → RESOLVED → IN_RECONCILIATION → FINAL → SETTLED. Execution only permitted from FINAL. Replays at any state return the stored receipt.
# A new claim admits one caller
receipt = registry.execute(
request_id="payment:invoice-C123",
action="send_invoice",
payload={"to": "client@example.com", "amount": 4500},
execute_fn=send_invoice,
)
# Retry after settlement — stored receipt returned
receipt = registry.execute(
request_id="payment:invoice-C123", # same id
action="send_invoice",
payload={"to": "client@example.com", "amount": 4500},
execute_fn=send_invoice,
)
# ^ invoice was NOT sent twice
Works with any framework
Claude / MCP
OpenAI tool calls
LangChain
CrewAI
n8n
Any Python function
Official MCP Registry
io.github.azender1/safeagent
Listed April 26, 2026 · v0.1.24 · PyPI verified · registry.modelcontextprotocol.io
04 — Production proof
Built alongside a live QQQ/TQQQ trading bot.
Real money. Real retries. Real problem.
The rv_qqq bot trades QQQ signals into leveraged TQQQ/SQQQ positions via Alpaca Markets. It has retry logic built in — EXIT_RETRY_COUNT=3, EXECUTION_LOCK_SEC=15 — because broker ACK timeouts are real. When a market order times out but actually filled, the retry fires a second order. On a leveraged ETF, that's a doubled position you didn't intend.
The bot already has a manual execution lock and state machine. SafeAgent replaces part of that hand-rolled logic with a durable, tested claim guard. Provider reconciliation remains required when the outcome is uncertain.
# Without SafeAgent — hand-rolled retry guard (rv_qqq_v14_1 pattern)
def place_order_with_retry(symbol, qty, side):
last_err = None
for attempt in range(1, EXIT_RETRY_COUNT + 1):
try:
return place_order(symbol, qty, side) # ← fires twice if first timed out but filled
except Exception as e:
last_err = e
time.sleep(EXIT_RETRY_SLEEP_SEC)
raise last_err
# With SafeAgent — durable claim state and explicit unresolved outcomes
def place_order_safe(symbol, qty, side, request_id):
return registry.execute(
request_id=request_id, # e.g. "trade:TQQQ:buy:2026-04-26T09:47:00"
action=f"order_{side}_{symbol}",
payload={"symbol": symbol, "qty": qty, "side": side},
execute_fn=lambda: place_order(symbol, qty, side),
)
# ↑ settled ID → stored receipt; PENDING ID → block and reconcile
Use cases
[$]
Trading bots
Without guard → doubled position on broker timeout
Broker ACK timeout on a leveraged ETF order. SafeAgent blocks the same logical ID; provider records determine whether the first order actually exists.
[~]
Tournament settlement
Without guard → prize payout fires twice
Verification agent times out, retries, payout executes twice. The original failure mode that triggered SafeAgent's creation inside PeerPlay.
[@]
Payments & notifications
Without guard → duplicate charge, double email
Stripe charge on retry. SMTP duplicate send. Any irreversible action that needs stable identity, duplicate suppression, and provider reconciliation.
[>]
MCP tool execution
Without guard → tool fires before state confirmed
Claude or any MCP host retrying a tool call. SafeAgent sits above the tool layer — officially listed in the MCP registry as of April 26, 2026.
Duplicate Execution Risk Audit — $499
Find every place your system executes twice.
A focused audit of your agent architecture. Every retry path, every side effect boundary, every gap. Delivered as a written report with SafeAgent integration recommendations.
Request audit →