fix: make gateway reliability safe by default (#3438)

[praisonai-triage-agent]

Fixes #3438

Summary

The gateway shipped an unsafe default reliability posture: running it the obvious way (BotOS(agent=...), praisonai gateway start, or a minimal gateway.yaml) gave no admission ceiling and only a 5s drain, so a burst could fan out unboundedly and a rolling restart could cut in-flight turns. The production machinery already existed — only the default was unsafe.

This changes the unset (None) posture that resolve_reliability resolves to a safe-by-default deployment, keying off bind posture, keeping all explicit overrides:

• Unset + loopback bind → bounded admission ceiling + fair wait queue + strict outbound ordering, with a snappy 5s drain.
• Unset + non-loopback bind (a real deployment) → the full production window (15s drain).
• reliability="off" → explicit opt-out to today's immediate-teardown / no-backpressure behaviour.
• reliability="default" → the explicit legacy posture (5s drain, no ceiling) for callers who ask for it.
• Explicit drain_timeout / max_concurrent_runs / admission_policy still always win.

Changes

• bots/_reliability.py: add bind_host-aware default resolution + _is_externally_bound helper; unset posture now yields admission + drain; docstrings updated.
• cli/features/gateway.py: always resolve reliability in the no-config path and thread the bind host so an external bind comes up with backpressure.
• Tests updated/added in test_reliability.py and test_outbox_ordering.py.

Layer placement

Wrapper (praisonai-bot gateway runtime). No new public knobs added — only the default value each of the existing CLI/YAML/Python surfaces resolves to.

Test plan

• python -m pytest src/praisonai-bot/tests/unit/bots/test_reliability.py test_outbox_ordering.py — 36 passed
• Remaining bots-suite failures confirmed pre-existing (missing pydantic/aiohttp optional deps), unrelated to this change

Generated with Claude Code

[MervinPraison]

@coderabbitai review

[MervinPraison]

/review

[qodo-code-review]

Qodo reviews are paused for this user.

Troubleshooting steps vary by plan Learn more →

On a Teams plan?
Reviews resume once this user has a paid seat and their Git account is linked in Qodo.
Link Git account →

Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center?
These require an Enterprise plan - Contact us
Contact us →

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Warning

Review limit reached

@MervinPraison, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 12 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 5f290f13-4992-474f-822a-a66a599ed497

📥 Commits

Reviewing files that changed from the base of the PR and between 54b4334 and 03b0d93.

📒 Files selected for processing (4)

• src/praisonai-bot/praisonai_bot/bots/_reliability.py
• src/praisonai-bot/praisonai_bot/cli/features/gateway.py
• src/praisonai-bot/tests/unit/bots/test_outbox_ordering.py
• src/praisonai-bot/tests/unit/bots/test_reliability.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/issue-3438-20260727-0929

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

This PR makes the gateway’s unset reliability posture safe by default.

• Adds bind-aware reliability resolution with bounded admission, queueing, strict outbound ordering, and appropriate drain windows.
• Applies reliability resolution to no-config CLI startup.
• Preserves explicit default, off, and caller-provided overrides.
• Adds coverage for loopback classification, admission defaults, drain behavior, and outbound ordering.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains, and the prior loopback-classification issue is addressed through IP-based loopback detection with regression coverage.

Important Files Changed

Filename	Overview
src/praisonai-bot/praisonai_bot/bots/_reliability.py	Introduces bind-aware safe defaults and fixes the previously reported handling of noncanonical loopback IP addresses using numeric IP classification.
src/praisonai-bot/praisonai_bot/cli/features/gateway.py	Always resolves reliability in no-config startup and passes the effective bind host into resolution.
src/praisonai-bot/tests/unit/bots/test_reliability.py	Covers safe defaults, external and loopback drain windows, explicit legacy behavior, and the prior loopback-address finding.
src/praisonai-bot/tests/unit/bots/test_outbox_ordering.py	Updates ordering expectations for the new safe unset posture while preserving explicit legacy presets.

_{Reviews (2): Last reviewed commit: "fix: recognize all loopback bind forms i..." | Re-trigger Greptile}

[MervinPraison]

@claude You are the FINAL architecture reviewer. If the branch is under MervinPraison/PraisonAI (not a fork), you are able to make modifications to this branch and push directly. SCOPE: Focus ONLY on Python packages (praisonaiagents, praisonai). Do NOT modify praisonai-rust or praisonai-ts. Read ALL comments above from Gemini, Qodo, CodeRabbit, and Copilot carefully before responding.

Phase 1: Review per AGENTS.md

1. Protocol-driven: check heavy implementations vs core SDK
2. Backward compatible: ensure zero feature regressions
3. Performance: no hot-path regressions
4. SDK value: review in depth whether the change genuinely adds value to the SDK — never add features for the sake of adding them. It must strengthen the SDK (simpler, more user-friendly, robust, world-class, secure). If it does not clearly add value, request changes or recommend rejecting/closing rather than merging scope creep
5. Do not bloat the Agent class with additional params — only if absolutely required; we already support many params.
6. Repo routing: agent-callable tools → PraisonAI-Tools; lifecycle plugins → PraisonAI-Plugins; optional sandbox backends → PraisonAI-Plugins (praisonai.sandbox entry point) — request changes if wrongly added to praisonaiagents/

Phase 2: FIX Valid Issues
7. For any VALID bugs or architectural flaws found by Gemini, CodeRabbit, Qodo, Copilot, or any other reviewer: implement the fix
8. Also independently identify and fix any gaps or issues you find in the changed code — do not rely only on prior reviewer feedback
9. Push all code fixes directly to THIS branch (do NOT create a new PR)
10. Comment a summary of exact files modified and what you skipped

Phase 3: Final Verdict
11. If all issues are resolved, approve the PR / close the Issue
12. If blocking issues remain, request changes / leave clear action items

[MervinPraison]

@claude You are the FINAL architecture reviewer. If the branch is under MervinPraison/PraisonAI (not a fork), you are able to make modifications to this branch and push directly. SCOPE: Focus ONLY on Python packages (praisonaiagents, praisonai). Do NOT modify praisonai-rust or praisonai-ts. Read ALL comments above from Gemini, Qodo, CodeRabbit, and Copilot carefully before responding.

Phase 1: Review per AGENTS.md

1. Protocol-driven: check heavy implementations vs core SDK
2. Backward compatible: ensure zero feature regressions
3. Performance: no hot-path regressions
4. SDK value: review in depth whether the change genuinely adds value to the SDK — never add features for the sake of adding them. It must strengthen the SDK (simpler, more user-friendly, robust, world-class, secure). If it does not clearly add value, request changes or recommend rejecting/closing rather than merging scope creep
5. Do not bloat the Agent class with additional params — only if absolutely required; we already support many params.
6. Repo routing: agent-callable tools → PraisonAI-Tools; lifecycle plugins → PraisonAI-Plugins; optional sandbox backends → PraisonAI-Plugins (praisonai.sandbox entry point) — request changes if wrongly added to praisonaiagents/

Phase 2: FIX Valid Issues
7. For any VALID bugs or architectural flaws found by Gemini, CodeRabbit, Qodo, Copilot, or any other reviewer: implement the fix
8. Also independently identify and fix any gaps or issues you find in the changed code — do not rely only on prior reviewer feedback
9. Push all code fixes directly to THIS branch (do NOT create a new PR)
10. Comment a summary of exact files modified and what you skipped

Phase 3: Final Verdict
11. If all issues are resolved, approve the PR / close the Issue
12. If blocking issues remain, request changes / leave clear action items

[praisonai-triage-agent]

Claude finished @MervinPraison's task —— View job

---

Final Architecture Review — PR #3442 ✅

• Read AGENTS.md + repo guidelines
• Review changed files (_reliability.py, gateway.py, tests)
• Assess reviewer feedback (Greptile loopback classification)
• Fix valid issue + add tests
• Run tests — 37 passed
• Push to branch

---

Phase 1 — Architecture review (per AGENTS.md)

Check	Verdict
Layer placement	✅ Correct. All changes in the wrapper (praisonai-bot gateway runtime). Core praisonaiagents/ untouched. No praisonai-rust/praisonai-ts touched.
Protocol-driven	✅ No heavy impl leaks into core; resolve_reliability composes onto existing BotOS args.
Backward compatible	✅ Explicit drain_timeout/max_concurrent_runs/admission_policy and reliability="default"/"off" all preserve prior behaviour. Only the unset posture changes — the stated intent of #3438.
Performance	✅ Resolution runs once at gateway startup, not on any hot path.
SDK value	✅ Genuine hardening: a safe-by-default deployment posture without adding public knobs. Not scope creep.
No Agent bloat	✅ Agent class not modified; no new params.

Phase 2 — Fixes implemented

Greptile finding (valid): _is_externally_bound used a literal allowlist (127.0.0.1, ::1, …), so valid loopback binds like 127.0.0.2, 127.255.255.255, and expanded 0:0:0:0:0:0:0:1 were misclassified as external and given the 15s production drain instead of the intended 5s loopback window.

Fix (bots/_reliability.py): classify loopback numerically via the stdlib ipaddress module (ip_address(...).is_loopback), keeping the known non-IP hostnames ("", localhost, loopback) as an explicit allowlist. A literal IP that isn't loopback → external; a non-IP DNS name → external (conservative, correct). No new deps, no new public surface.

Test (test_reliability.py): added test_unset_noncanonical_loopback_bind_stays_snappy covering 127.0.0.2, 127.255.255.255, 0:0:0:0:0:0:0:1, and [::1].

Files modified this review:

• src/praisonai-bot/praisonai_bot/bots/_reliability.py
• src/praisonai-bot/tests/unit/bots/test_reliability.py

Skipped: Qodo (reviews paused) and CodeRabbit (rate-limited) left no actionable items; no other reviewer findings outstanding.

Phase 3 — Verdict

✅ Approve. The change is minimal, backward-compatible, correctly layered in the wrapper, and the one valid reviewer finding is now fixed with coverage. python -m pytest test_reliability.py test_outbox_ordering.py → 37 passed.

Note: I can't submit a formal GitHub approval (disabled for security); treating this as an approving review.

Commit: becf0f30f · · Branch: claude/issue-3438-20260727-0929

[praisonai-triage-agent]

@claude CI failed on HEAD becf0f30. Please fix the failures below and push to this branch.

Failed checks

• github-actions / detect-and-trigger — https://github.com/MervinPraison/PraisonAI/actions/runs/30255287461/job/89942320466
• github-actions / detect-and-trigger — https://github.com/MervinPraison/PraisonAI/actions/runs/30255287483/job/89942320286
• github-actions / claude-review-recovery — https://github.com/MervinPraison/PraisonAI/actions/runs/30255284712/job/89942311368

Failures (extracted)

(Could not extract pytest details — see job logs above.)

Critical review first

Before changing code or tests, decide which side is wrong:

1. Legitimate feature change — the PR intent is correct but implementation or tests need updating. Preserve SDK guarantees; update tests only when behaviour intentionally changed and document why.
2. Regression / bug in this PR — the failure exposes a real breakage introduced here. Fix the implementation; do not weaken, skip, or delete tests just to go green.
3. Pre-existing flake or unrelated failure — say so explicitly; prefer fixing the root cause over masking it.

SDK guardrails (AGENTS.md):

• Agent-callable tools → PraisonAI-Tools; lifecycle plugins → PraisonAI-Plugins; sandbox backends → PraisonAI-Plugins (praisonai.sandbox) — not praisonaiagents/.
• Do not disturb core SDK contracts to accommodate a wrapper/feature change.
• Tests must continue to guard backward compatibility and hot-path behaviour — passing CI by lowering test standards is not acceptable.
• If the feature does not genuinely add SDK value, recommend reverting or narrowing scope instead of patching around failures.

What to do

1. State your verdict: legitimate fix, regression fix, or needs human review — and why (1–3 sentences).
2. Fix root cause with minimal changes; never bloat the Agent class with extra params.
3. Run failing tests locally with targeted pytest, plus any related SDK tests touched by the PR.
4. Push to this branch and comment: files changed, review verdict, and why tests still protect SDK behaviour.

[praisonai-triage-agent]

Claude finished @MervinPraison's task —— View job

---

Final Architecture Review + CI Triage — PR #3442 ✅

• Investigate CI failure on HEAD becf0f30
• Review changed files (_reliability.py, gateway.py, tests)
• Run tests locally
• Verdict

---

CI failure triage — verdict: pre-existing infra flake, not a code regression

The three failing checks are not test failures. All three are GitHub API rate-limit (403) errors inside orchestration workflow scripts — nothing to do with the PR code:

Check	Root cause
detect-and-trigger (×2)	403 API rate limit exceeded for user ID 454862 in .github/scripts/merge-gate.js → ci-failure-claude.js (loadPrContext)
claude-review-recovery	Same 403 rate limit in "Sync pipeline status labels" (x-ratelimit-remaining: 0)

These are transient GitHub-API rate limits on the actor account, not a breakage introduced by this PR. They fix themselves once the limit window resets (a re-run will pass). No code or test change can address them, and per the guardrails I will not weaken/skip any tests to go green.

The actual pytest suite for this PR passes locally:

python -m pytest tests/unit/bots/test_reliability.py tests/unit/bots/test_outbox_ordering.py
37 passed

(The triage message's "Could not extract pytest details" is because there were no pytest details — the failing jobs never ran pytest.)

---

Phase 1 — Architecture review (per AGENTS.md)

Check	Verdict
Layer placement	✅ All changes in the wrapper (praisonai-bot gateway runtime). Core praisonaiagents/ untouched; no praisonai-rust/praisonai-ts.
Protocol-driven	✅ resolve_reliability composes onto existing BotOS args; no heavy impl leaks into core.
Backward compatible	✅ Explicit drain_timeout/max_concurrent_runs/admission_policy and reliability="default"/"off" preserve prior behaviour. Only the unset posture changes — the exact intent of #3438.
Performance	✅ Resolution runs once at gateway startup; not on any hot path.
SDK value	✅ Genuine hardening (safe-by-default deployment) with no new public knobs — not scope creep.
No Agent bloat	✅ Agent class unmodified; no new params.
Routing	✅ Wrapper CLI/runtime change; correctly placed.

Phase 2 — Reviewer findings

• Greptile — loopback allowlist: already fixed in becf0f30f. _is_externally_bound now classifies loopback numerically via ipaddress.is_loopback, so 127.0.0.2, 127.255.255.255, 0:0:0:0:0:0:0:1, [::1] all resolve to the snappy loopback drain. Verified all edge cases pass:

  127.0.0.2, 127.255.255.255, 0:0:0:0:0:0:0:1, [::1] → loopback (snappy)
  0.0.0.0, ::, 192.168.1.5, example.com          → external (production)
  

• Qodo / CodeRabbit: reviews paused / rate-limited — no actionable items left.

No additional bugs or gaps found on independent review.

Phase 3 — Verdict

✅ Approve. The change is minimal, backward-compatible, correctly layered in the wrapper, and the one valid reviewer finding is already fixed with coverage (37 passed). The reported CI failures are transient GitHub-API rate limits in workflow orchestration, unrelated to this PR — a re-run should clear them. No code changes required.

Note: I can't submit a formal GitHub approval (disabled for security); treat this as an approving review. No new commit — nothing to fix in the PR code.
· Branch: claude/issue-3438-20260727-0929