refactor(gateway): extract display/resolution helpers out of run.py (first slice of #54962)

[andrexibiza]

Related #18859 #54962 #55138 #55304

What does this PR do?

First scoped slice of the Extract Gateway Platform Routing from
gateway/run.py refactor (#54962, #55138): extract the pure display /
resolution helpers out of the 26,800-line god-file into a focused,
tested module.

gateway/run.py is a 26,800-line god-file. This PR pulls the first
cohesive cluster — display and thread-resolution helpers — into
gateway/display_helpers.py (201 lines) with a dedicated test module
(184 lines). Net effect: run.py shrinks by 250 lines, no behavior
change (pure move + import), and the extracted helpers get direct unit
coverage they previously lacked (34 tests).

Extracted:

• _resolve_progress_thread_id — progress/status bubble thread targeting
  (incl. the fix(gateway): respect reply_in_thread=false for Slack progress messages #18859 synthetic-thread case)
• _telegramize_command_mentions + _TELEGRAM_COMMAND_MENTION_RE
• _gateway_platform_value, _has_platform_display_override,
  _resolve_gateway_display_bool
• _coerce_gateway_timestamp, _auto_continue_freshness_window,
  _float_env, _AUTO_CONTINUE_FRESHNESS_SECS_DEFAULT

Scope honesty

The issue title promises full platform-routing extraction from a 26K-line
file — that is a multi-PR effort, not a single landable diff. This PR
ships the first verifiable slice and proves the extraction pattern
(module + tests + shrink) so follow-up slices can land the same way.
gateway/run.py still contains the platform adapters and dispatch loop;
those are separate follow-up extractions.

Credit

Cherry-picked from #55304 by @Stoltemberg (authorship preserved in git
history), conflict-resolved against current main (run.py moved on; the
stall-notify timeout constant and hygiene platform constant stay in
run.py where they're used; the extracted helpers are imported at the
extraction site).

How to test

pytest tests/gateway/test_display_helpers.py -q
# 34 passed

What platforms were tested?

• Windows 11 native: 34 passed, both files parse, imports resolve,
  git diff --check clean, attribution audit clean.

Why this matters

gateway/run.py at 26.8K lines is the largest file in the codebase;
every fix or feature in the gateway requires navigating it. This is the
first concrete step of the accepted god-file-extraction pattern
(AGENTS.md: "Refactor god-files into clean modules... even when the diff
is huge and mechanical"), and it adds real test coverage to helpers that
had none.

Part of #54962
Part of #55138 (Extract Gateway Platform Routing)

• Refactor (no behavior change)
• Bug fix
• Breaking change

Checklist

• Code follows repo style (extraction, no new deps)
• Self-review complete
• Tests added (34 for the extracted helpers)
• Suite green: 34 passed
• git diff --check clean
• Credit: extraction from refactor: extract display helpers from gateway/run.py to gateway/display_helpers.py #55304 by @Stoltemberg, cherry-picked with authorship preserved

Part of #78647

[GottZ]

This was generated by AI during triage.

Summary

Six open PRs address the duplicated #54962/#55138 request through scoped extractions from gateway/run.py: #77376 extracts platform-routing policy, #77433 display/resolution helpers, #77438 message/config helpers, #77450 compression-status matching, #77452 resume/replay helpers, and #77455 transient-error handling. These reduce the god-file through independently testable modules, but none extracts the requested adapter-owned payload/event/serialization pipeline or introduces the proposed platform ABC.

Related pull requests

• refactor(gateway): extract platform routing helpers from run.py #77376 best fix — (+252/-78) — n/a: Extracts eight platform-routing policy helpers into gateway/platform_routing.py, retains gateway.run re-exports, and adds focused compatibility tests; this is the recorded best fix for Extract Gateway Platform Routing from gateway/run.py #54962, Extract Gateway Platform Routing from gateway/run.py #55138, and [Bug]: .hermes/hermes-agent/run.py is 23,006 lines of code #67967, although it does not move payload parsing, event translation, or serialization into adapters.
• refactor(gateway): extract display/resolution helpers out of run.py (first slice of #54962) #77433 best fix — (+465/-237) — n/a: Extracts display, thread-resolution, timestamp, and timing helpers into gateway/display_helpers.py with direct tests, shrinking run.py while leaving adapters and dispatch in place. It is a recorded best fix for the broader [Bug]: .hermes/hermes-agent/run.py is 23,006 lines of code #67967 god-file issue, but overlaps refactor(gateway): extract platform routing helpers from run.py #77376 on _gateway_platform_value.
• refactor(gateway): extract message/config helpers from run.py (slice 2 of #54962) #77438 partial — (+89/-65) — n/a: The visible diff extracts Slack channel filtering, config normalization, and message-timestamp helpers into gateway/message_config_helpers.py; it is a distinct god-file reduction rather than the requested adapter-routing architecture.
• refactor(gateway): extract compression-status helpers from run.py (slice 4 of #54962) #77450 partial — (+67/-47) — n/a: Moves the compression-status template compiler and matcher into gateway/status_helpers.py, reducing run.py without changing routing behavior or adapter ownership.
• refactor(gateway): extract resume/replay helpers from run.py (slice 3 of #54962) #77452 partial — (+165/-170) — n/a: Moves resume-recovery note construction and assistant replay-field preservation into gateway/resume_replay_helpers.py; this is a standalone runtime-helper extraction, not platform routing.
• refactor(gateway): extract transient-error helpers from run.py (slice 5 of #54962) #77455 partial — (+99/-76) — n/a: Moves transient-network-error classification and the gateway loop exception handler into gateway/error_helpers.py, preserving behavior while reducing run.py outside the platform-routing concern.

Duplicates

#54962 and #55138 are duplicate issues, with #77376 carrying the structural closes edge for #55138. No listed PRs are wholesale duplicates in the visible diffs, though #77376 and #77433 both extract _gateway_platform_value and therefore require overlap resolution.

Suggested consolidation

Keep #77376 open with its independently tested platform-routing-helper extraction as the strongest salvage path and recorded best fix for #54962/#55138/#67967; close issue #55138 as a duplicate of #54962. Keep #77433 open as the recorded best-fix display-extraction slice for #67967, but author action is required to rebase onto the chosen ordering or split out its duplicated _gateway_platform_value; keep #77438, #77450, #77452, and #77455 open only as distinct salvageable god-file slices, while tracking the still-separate adapter ABC and adapter-owned payload/event/serialization work under #54962.

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
    I67967(["issue #67967 (closed)"])
    P77433["PR #77433 (open)"]
    P77433 -->|best fix| I67967
    class I67967 closed
    class P77433 open
    class P77433 best
    class P77433 target
    click I67967 "https://github.com/NousResearch/hermes-agent/issues/67967"
    click P77433 "https://github.com/NousResearch/hermes-agent/pull/77433"

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 6 pull requests and 3 issues in this complex. Each diff was read against this issue; Assessment working set: 82 kB of PR diffs, 26 kB of issue/PR text, 11 kB of discussion (10 comments), 12 verify verdicts. verdicts reflect diff content, not PR titles. Part of an automated triage batch.

[andrexibiza]

Fixed in cecc6cb — the duplicated _gateway_platform_value overlap with #77376 is resolved.

What changed

• gateway/display_helpers.py no longer defines _gateway_platform_value — the single definition stays in gateway/run.py, so the display slice and the platform-routing slice (refactor(gateway): extract platform routing helpers from run.py #77376) do not extract the same helper into two modules.
• _resolve_gateway_display_bool now takes platform_value (caller-normalized lowercase platform key) and require_platform_override_for as normalized platform keys, instead of re-normalizing internally.
• Updated the show_reasoning call site in run.py and the Mattermost tests to the new signature.
• Added direct tests for _resolve_gateway_display_bool covering the platform-only opt-in behavior (blocked without override, enabled with explicit display.platforms.<platform> override, other platforms unaffected).

Validation

• scripts/run_tests.sh: 41 passed, 0 failed (test_display_helpers, test_mattermost, test_run_cleanup_progress, test_run_progress_topics)
• Ruff: clean; git diff --check: clean; Windows footgun lint: clean

This resolves the overlap without a merge-order dependency on #77376: _gateway_platform_value remains in run.py until the platform-routing slice lands, so whichever merges first, the other applies cleanly.