feat: add first-class local (terminal) channel to gateway

[praisonai-triage-agent]

Fixes #4455

Summary

Adds a first-class local (terminal) channel so you can converse with a running gateway agent from your own shell — no remote bot, no tokens, no webhook.

BotOS(agent=agent, platforms=["local"]).run()   # chat in your terminal, zero setup

It is a real channel (not a separate process): it joins the same BotSessionManager, identity resolver, delivery router and cross-channel mirror as every remote channel, so a conversation begun in the terminal continues seamlessly on Telegram (and deliver="local" / deliver="local:local" resolves like any other target).

Architecture (WRAPPER-only)

• Wrapper (praisonai-bot): a concrete BasePlatformAdapter transport (the TTY loop / stdin handling belongs beside the other channel implementations) + one registry entry.
• No core changes, no new dependencies. Reuses core BasePlatformAdapter / PlatformCapabilities / BotSessionManager untouched.

Changes

• bots/local.py (new) — LocalBot: stdin read loop run off the event loop (concurrent channels keep running), stdout writer, /status /new /help /stop, TTY-honest capabilities (supports_edit=False, needs_rate_limit=False, accepts_webhooks=False, markdown_dialect="plain"), supervised_inbound=False (EOF is a clean exit, not a reconnectable drop), always-ok probe(), and a LocalDescriptor for config/onboarding/prompt.
• bots/_registry.py — local lazy loader in _BUILTIN_PLATFORMS.
• bots/__init__.py — lazy LocalBot export.
• tests/unit/bots/test_local_channel.py (new) — registry wiring, capabilities, token-free/unsupervised, stdin→agent→stdout turn loop + clean EOF exit, and outbound send_message to stdout.

Tests

• test_local_channel.py — 7 passed
• registry + channel + w1 + delivery + store-backed subset — 206 passed, 6 skipped (no regressions)

Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added support for running local channels without a token.
  • Local channels now start successfully during initial launch and hot reload without requiring credentials.
  • Improved configuration handling to prevent valid token-free local channels from being marked as degraded.

[greptile-apps]

Greptile Summary

The PR completes token-free gateway support for the local terminal channel.

• Exempts local from configuration-time token validation.
• Allows token-free local startup through both initial channel creation and hot reload.

Confidence Score: 3/5

The tokenless startup fix is correct, but the outstanding terminal-reader shutdown and reconnect failures should be resolved before merging.

A blocked stdin read remains uninterruptible during shutdown, and reconnecting can start a second reader while the abandoned reader can still consume terminal input.

Files Needing Attention: src/praisonai-bot/praisonai_bot/bots/local.py

Important Files Changed

Filename	Overview
src/praisonai-bot/praisonai_bot/gateway/server.py	Consistently recognizes local as token-free across configuration validation, initial startup, and single-channel reload.

_{Reviews (3): Last reviewed commit: "fix: recognize local channel as tokenles..." | Re-trigger Greptile}

[greptile-apps]

Tokenless gateway startup broken

When a gateway config enables local without a token, the gateway's credential gate does not recognize it as token-free, so it marks the channel degraded and never starts the terminal input loop.

Knowledge Base Used:

• Bot and collaboration automation
• Gateway, daemon, and background jobs

[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: Review changes in this PR. Python SDK: praisonaiagents, praisonai. TypeScript SDK: src/praisonai-ts/. Do NOT modify src/praisonai-rust. 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 #4474 (local terminal channel) ✅

Phase 1 — Architecture (AGENTS.md): PASS.

• WRAPPER-only (praisonai-bot); zero core edits, no new deps. Reuses BasePlatformAdapter / PlatformCapabilities / BotSessionManager untouched.
• Agent class not touched, no new params.
• Genuine SDK value: a zero-setup, token-free terminal channel that joins the same session/identity/delivery/mirror as remote channels — strengthens the SDK, not scope creep.
• Correctly routed (channel adapter → wrapper).

Phase 2 — Fixed the two valid Greptile P1 issues:

• P1 Github actions fix #1 — tokenless gateway startup broken. CONFIRMED & FIXED. local was absent from the three tokenless gates in gateway/server.py, so a token-free local channel failed config validation and was skipped + marked degraded. Added "local" to:
  • load_gateway_config required-section contract (_tokenless set)
  • start_channels (is_email_platform)
  • _start_single_channel (hot-reload path)
• P1 Merge pull request #1 from MervinPraison/develop #2 — terminal read blocks shutdown. CONFIRMED & FIXED. The read now runs on a dedicated daemon thread (_read_line_async) instead of the default non-daemon asyncio executor, so a readline() still parked on an open TTY at shutdown can never join-block interpreter exit; cancellation resolves the awaiting coroutine and the orphaned read is abandoned.

Independent checks: verified the canonical schema (_config_schema.py) defaults token="" and LocalDescriptor.config_fields=[], so a token-free local passes schema validation too — no further gate needed. No test hardcodes the old tokenless tuple.

Files modified:

• src/praisonai-bot/praisonai_bot/gateway/server.py — 3 tokenless gates now include local
• src/praisonai-bot/praisonai_bot/bots/local.py — daemon-thread stdin reader (_read_line_async)
• src/praisonai-bot/tests/unit/bots/test_local_channel.py — +2 regression tests (cancelled-read clean exit; daemon-reader guard)

Skipped: nothing actionable. (Pre-existing, unrelated failures in test_pid_lock_windows.py are Windows/psutil-specific on Linux CI and untouched by this PR.)

Tests: test_local_channel.py 9 passed. Full tests/unit/bots/ + tests/unit/gateway/ → 1503 passed, 9 skipped (only the 2 unrelated pid-lock-windows failures).

Verdict: ✅ Approve — both blocking P1 issues resolved, no regressions. Ready to merge.

Job run · branch claude/issue-4455-20260827-1124

[greptile-apps]

Reconnect loses terminal input

When the local channel is reconnected or hot-reloaded while readline() is blocked, cancellation abandons the existing daemon reader and starts another reader on the same sys.stdin. The abandoned reader can consume and discard the operator's next line through its cancelled future, causing the active terminal channel to miss input or appear hung.

Knowledge Base Used:

• Bot and collaboration automation
• Gateway, daemon, and background jobs

[MervinPraison]

@claude this PR has merge conflicts with main. Please rebase onto latest main, resolve conflicts (keep this PR's intent, merge in newer main logic), run targeted tests, and force-push with --force-with-lease. Comment which files you resolved. Do not bloat the Agent class with additional params — only if absolutely required; we already support many params. Keep the resolution minimal — the aim is a lightweight and powerful package; do not introduce scope creep while resolving conflicts.

[praisonai-triage-agent]

Claude finished @MervinPraison's task —— View job

---

Rebase & Conflict Resolution — PR #4474 ✅

• Setup git identity & fetch latest main
• Rebase onto origin/main
• Resolve conflicts (keep PR intent + newer main logic)
• Run targeted tests
• Force-push with --force-with-lease
• Summarize files resolved

Rebased cleanly onto main (b5585b690) and force-pushed.

Key context

A sibling PR (#4463) for the same issue #4455 already merged a more mature local-channel implementation into main — bots/local.py (daemon-thread stdin executor with shutdown(wait=False, cancel_futures=True), ChatCommandMixin/MessageHookMixin, probe/health, message hooks, supervised_inbound=False), plus the _registry.py and __init__.py wiring. Those overlap this PR's early implementation, so _registry.py / __init__.py merged automatically and the add/add conflicts on local.py + test_local_channel.py were resolved to main's superior version.

Conflicts resolved

File	Resolution
bots/local.py	Kept main's version (#4463) — more complete; already fixes the shutdown-hang P1 via a dedicated daemon-thread executor.
tests/unit/bots/test_local_channel.py	Kept main's version (matches the mature adapter).
gateway/server.py	Merged cleanly — this PR's net contribution. Adds "local" to all three token-free gates.
bots/_registry.py, bots/__init__.py	No conflict (already on main via #4463).

Net diff vs main (this PR now contributes exactly the tokenless fix)

gateway/server.py — "local" added to the 3 token-free gates so a token-free local channel passes config validation and starts instead of being skipped/degraded:

• load_gateway_config → _tokenless = {"email", "agentmail", "signal", "local"}
• start_channels → is_email_platform tuple
• _start_single_channel (hot-reload) → is_email_platform tuple

Scope

Minimal, no scope creep. Zero core edits, no new deps, Agent class untouched. 1 file changed, +7 / -5.

Tests (targeted)

• test_local_channel.py → 8 passed
• gateway -k config → 26 passed
• full tests/unit/bots/ → 870 passed, 8 skipped (1 pre-existing, unrelated failure: test_critical_bug_fixes.py needs the praisonai wrapper pkg, not installed in this env; untouched by this PR)
• Sanity-checked: all three tokenless gates include "local".

Skipped: dropped this branch's redundant _read_line_async reimplementation — main's daemon-thread executor already resolves the same shutdown-hang P1.

Job run · branch claude/issue-4455-20260827-1124

[MervinPraison]

@coderabbitai review

[MervinPraison]

/review

[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]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 2ad940d9-47a8-4f60-9237-87dd46f904a7

📥 Commits

Reviewing files that changed from the base of the PR and between 6634dc1 and 8b21ff8.

📒 Files selected for processing (1)

• src/praisonai-bot/praisonai_bot/gateway/server.py

Included review availability: Your plan provides up to 8 included reviews per hour; 2 remain after this review.

---

📝 Walkthrough

Walkthrough

The gateway now treats local as token-free during configuration validation, initial channel startup, and hot-reload channel startup.

Changes

Local channel support

Layer / File(s)	Summary
Allow tokenless local startup src/praisonai-bot/praisonai_bot/gateway/server.py	Configuration validation and both channel-start paths now allow local channels without a token. These channels are started instead of being marked degraded as "credential unavailable".

Estimated code review effort: 2 (Simple) | ~5 minutes

Merge Risk: ⚪ Minimal · up to 8b21f

The change adds token-free local terminal channel support without identified correctness, security, availability, or deployment risk. No actionable merge-blocking risk remains after normal checks and review.

Suggested reviewers: mervinpraison

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary change: adding a first-class local terminal channel to the gateway.
Linked Issues check	✅ Passed	The changes support issue #4455 by allowing the local channel to start without a token during initial gateway configuration, normal startup, and hot reload. This directly enables token-free local ga…
Out of Scope Changes check	✅ Passed	The changes are limited to recognizing local as a tokenless gateway channel. They directly support the linked issue and introduce no unrelated scope.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 1 files.

Full details: Linked Issues check

Explanation

The changes support issue #4455 by allowing the local channel to start without a token during initial gateway configuration, normal startup, and hot reload. This directly enables token-free local gateway access alongside remote channels.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/issue-4455-20260827-1124

---

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

[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 →

[praisonai-triage-agent]

Merge gate scan — eligible for assessment. Claude merge gate will assess and may auto-merge if MERGE_GATE_VERDICT: APPROVE.

[praisonai-triage-agent]

Merged by Claude PR merge gate (claude-merge-gate.yml).
Verdict: MERGE_GATE_VERDICT: APPROVE
SHA: 8b21ff8
Method: merge