refactor(gateway): extract platform routing helpers from run.py

[andrexibiza]

Related #54962 #55138 #55190 #55304

What

Extracts the platform-routing helper cluster out of the 26k-line gateway/run.py god-file into a focused module, gateway/platform_routing.py:

• _gateway_platform_value — platform identity normalization (enum/string)
• _gateway_surface_passes_raw_text + _GATEWAY_RAW_TEXT_PLATFORMS — which surfaces keep raw status/error text
• _non_conversational_metadata — Discord lifecycle/status marker
• _home_target_env_var / _home_thread_env_var — home-channel env var resolution
• _platform_has_bot_credential — token-platform credential check
• _platform_config_key — Platform enum → config.yaml key mapping

All bodies are verbatim moves — zero behavior change. gateway/run.py re-exports every name so existing importers (gateway/slash_commands.py, the /sethome tests, the multiplex tests) keep working unchanged. New focused tests land in tests/gateway/test_platform_routing.py.

Why

This is the extraction requested in issue #54962 (duplicate #55138, same author, same body, filed 5h later — this PR closes #55138 as the duplicate). The repository rubric explicitly wants god-file refactors: "Refactor god-files into clean modules… a declared refactor's request IS the extraction." Sibling extractions from gateway/run.py (#55190 text_sanitizer, #55304 display_helpers) received keep_open salvageability=medium sweeper verdicts citing exactly this direction — "consistent with the repository's stated goal of breaking up gateway/run.py" — before dying on execution, not on direction. This PR completes the pattern for the routing policy cluster.

How to test

bash scripts/run_tests.sh tests/gateway/test_platform_routing.py tests/gateway/test_home_target_env_var.py
bash scripts/run_tests.sh tests/gateway/test_64674_multiplex_primary_token_scope.py
bash scripts/run_tests.sh tests/gateway/test_discord_slash_commands.py tests/gateway/test_slash_access.py tests/gateway/test_destructive_slash_confirm.py

The new test file exercises the real import path and real call paths (no mocks), including a backward-compat assertion that every name is still importable from gateway.run. The three existing suites cover the external importers (slash_commands.py _home_target_env_var/_platform_config_key consumers, multiplex _platform_has_bot_credential consumers).

Platforms tested

• Windows 10 native (git-bash), Python 3.11 — scripts/run_tests.sh per-file subprocess isolation, all pass (48 tests across 6 files)
• python scripts/check-windows-footguns.py --diff HEAD~1 — clean (3 files)
• git diff --check — clean

Why this matters to users

Nothing user-visible changes today — this is pure code organization. What it buys: the platform routing policy (which surfaces get raw text, how home channels resolve, how credentials are checked) moves from a file so large that a single edit risks touching unrelated gateway logic, into a small module that can be reviewed and tested in isolation. Future gateway fixes and platform additions get a smaller, safer blast radius, and new contributors can find routing policy without scanning 26k lines. Maintainers get a merged precedent for the remaining gateway/run.py extraction work.

Addresses #54962 · closes #55138

Part of #54962
Part of #55138

Part of #78647
Part of #78791

[GottZ]

This was generated by AI during triage.

Summary

One PR addresses this issue complex. #77376 extracts a focused cluster of platform identity, routing-policy, home-target, credential, and config-key helpers from gateway/run.py, but it does not implement the requested platform adapter ABC or move webhook parsing, event translation, and message serialization into adapters.

Related pull requests

• #77376 fixes — (+252/-78) — partial extraction with a concrete salvage path: the diff moves eight existing routing helpers into gateway/platform_routing.py, re-exports them from gateway/run.py for compatibility, and adds focused tests; it reduces the god-file without addressing the issue's broader adapter-interface architecture.

Suggested consolidation

Keep #77376 open with a salvage path focused on the independently testable helper extraction and backward-compatible re-exports. Treat #55138 as a duplicate of canonical issue #54962; there are no duplicate PRs to close in this complex, while the broader ABC and adapter-owned payload/event/serialization work should remain tracked separately from #77376's narrower diff.

Complex graph

flowchart LR
    classDef open fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
    classDef merged fill:#dcfce7,stroke:#15803d,color:#14532d
    classDef closed fill:#e5e7eb,stroke:#6b7280,color:#1f2937
    classDef unverified fill:#f3f4f6,stroke:#9ca3af,color:#374151
    classDef best stroke-width:3px,stroke:#b45309
    classDef target stroke-width:3px,stroke:#4338ca
    I55138(["issue #55138 (open)"])
    P77376["PR #77376 (open)"]
    P77376 -->|fixes| I55138
    class I55138 open
    class P77376 open
    class P77376 target
    click I55138 "https://github.com/NousResearch/hermes-agent/issues/55138"
    click P77376 "https://github.com/NousResearch/hermes-agent/pull/77376"

Loading

Graph: solid arrow = fixes / best fix, dashed arrow = partial or unverified (see edge label); boxed group = PRs duplicating each other; amber border = best fix; indigo border = target; gray node = closed (state tag in the node label).

Cross-PR triage: Reviewed 1 pull request and 2 issues in this complex. Each diff was read against this issue; Assessment working set: 16 kB of PR diffs, 5 kB of issue/PR text, 1 kB of discussion (2 comments), 0 verify verdicts. verdicts reflect diff content, not PR titles. Part of an automated triage batch.

[andrexibiza]

Thanks for the triage — this PR already implements the salvage path the verdict endorses (independently testable helper extraction + backward-compatible re-exports), so no further changes are needed within its scope. The broader platform-adapter ABC and adapter-owned payload/event/serialization work stays tracked separately, per the recommendation.

Validation on the PR head 173590dd2:

• scripts/run_tests.sh on the 6 affected suites — 48 passed, 0 failed: test_platform_routing 18, test_discord_slash_commands 13, test_slash_access 7, test_64674_multiplex 6, test_home_target_env_var 2, test_destructive_slash_confirm 2
• git diff --check — clean
• python scripts/check-windows-footguns.py --diff HEAD~1 — clean (3 files)
• CI on the PR: "All required checks pass", including the blocking ruff enforcement job