feat(telegram): show bounded async delegation activity

[0xbWy]

What does this PR do?

Telegram users can request the current asynchronous-delegation snapshot with /agents, and they receive each delegation's dispatch acknowledgement and terminal result. This PR adds the missing automatic in-between surface: it projects the existing list_async_delegations() snapshot into one plain-text Telegram status message per delegation and edits that message only when meaningful visible state changes.

The completion lane remains authoritative:

• terminal completion delivery is processed before panel work on every watcher cycle;
• every panel request and watcher cycle has a finite wall-clock budget;
• panel traffic uses an explicit single-attempt status path with no retry, sleep, rich formatting, fallback send, continuation, or typing action;
• Telegram failures and flood control remain non-fatal to the delegation and its final result.

Routing is source-aware rather than bot-global. The panel resolves the canonical originating SessionSource and selects its adapter through _adapter_for_source(). In multiplex mode it requires the exact live registered transport provenance retained by the bounded in-process source cache; persisted/restored or ambiguous sources fail closed. Forum and private-DM topics retain their exact thread/reply anchor.

Rendering is an explicit allowlist capped at 500 characters. It shows the full actionable delegation ID so the user can reference the delegation in conversation or existing control surfaces, plus normalized lifecycle state, bounded goal/role labels, in-tool or waiting state, child API-call/tool activity, and elapsed/progress/activity ages. Private context, results, errors, tool arguments, session keys, and models are excluded. Temporal ages are display-only and do not trigger edits.

Deliberate exclusions

This PR does not add delegation cancellation or steering, change async-delegation producers or persistence, add API-call budgets, or claim to solve Telegram flood control globally. Those are separate authority and transport contracts.

Related work / non-duplication

• Async Delegation View — docked agents panel + live steering (impl ready, PR linked) #70894 / feat(tui): async delegation view — docked agents panel + live steering #70899: docked TUI async-delegation visibility plus steering. This PR is Telegram-only and read-only.
• fix(gateway): emit silent lifecycle activity without progress bubbles #75022: silent lifecycle reactions. Complementary lightweight feedback, not a delegation activity panel.
• fix(telegram): per-chat send cooldown + skip progress fallback on flood control #66722 / P1 harden gateway anti-flood handling with token bucket and circuit breaker #50114: broader Telegram flood-control proposals. This PR confines bounded delivery behavior to explicit low-priority panel writes.
• fix: propagate child activity to parent during delegate_task #7295: merged child-activity propagation reused by this projection.
• feat(tui): pulse active subagent indicator #76023: closed TUI status-bar pulse; no Telegram panel overlap.
• Feature Request: /smalltalk — Side Conversations for Async Subagent Sessions #13060: stateful side-conversation commands and merge/dismiss behavior; materially broader and authority-bearing compared with this observational panel.

Implementation lineage

This is a fresh adaptation against current upstream main, distilled from a production-hardened implementation whose first iteration broadened retry behavior too far and whose correction localized single-attempt semantics to informational panel traffic. The public patch intentionally carries only the corrected generic invariants—no deployment-specific names, routing policy, authority semantics, credentials, paths, or capsule metadata.

This follows the same source-traceable contribution posture as #36892, whose core design was adapted and credited in merged #74058: give maintainers enough architectural and failure-history context to review the contract rather than presenting a context-free diff.

Related Issue

Fixes #76389

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• gateway/run.py: project native async-delegation activity to the canonical originating Telegram session with live multiplex transport provenance, bounded rendering, deduplication, rate/circuit state, lifecycle cleanup, and completion-first watcher ordering.
• plugins/platforms/telegram/adapter.py: add an explicit opt-in single-attempt plain-text status delivery mode with exact DM-topic anchors while preserving normal status behavior.
• tests/gateway/...: cover rendering/privacy, provenance persistence versus live cache, profile isolation, topic routing, flood bounds, terminal cleanup, adapter behavior, and completion priority.
• website/docs/user-guide/features/delegation.md: document Telegram background-delegation activity behavior and its informational limits.

How to Test

1. Focused and affected behavior:

   HERMES_TEST_FILE_RETRIES=0 scripts/run_tests.sh \
     tests/gateway/test_async_delegation_telegram_panel.py \
     tests/gateway/test_telegram_status_delivery.py \
     tests/gateway/test_telegram_status_update.py \
     tests/gateway/test_completion_delivery.py \
     tests/gateway/test_gateway_shutdown.py \
     tests/gateway/test_dm_topics.py \
     tests/gateway/test_telegram_thread_fallback.py \
     tests/gateway/test_gateway_silence_tokens.py \
     tests/gateway/test_first_turn_session_meta_rebaseline.py \
     tests/gateway/test_42039_duplicate_user_message.py \
     tests/gateway/test_restart_notification.py \
     tests/tools/test_async_delegation.py -q

   Result: 109 passed, 0 failed. The two new focused modules alone also completed 23 passed, 0 failed on the final candidate.

2. Gateway plus native async-delegation regression suite:

   HERMES_TEST_FILE_RETRIES=0 scripts/run_tests.sh tests/gateway tests/tools/test_async_delegation.py -q

   Result: 4,541 passed, 3 failed. The failures are unrelated baseline failures reproduced at the pinned base: one Matrix markdown-table test and two WeCom XML callback tests.

3. Complete repository suite:

   HERMES_TEST_FILE_RETRIES=0 scripts/run_tests.sh -q

   Pre-ID-correction candidate result: 23,462 passed, 34 failed, 100% complete across 2,519 files in 998.3 seconds. The exact corrected candidate has fresh focused, affected, and complete gateway-lane evidence above; a repository-wide rerun remains a publication-time gate. Fourteen additional files collected no tests because optional ACP/MCP imports were unavailable or mismatched. None of the failures or collection errors was in a changed or directly affected file. The failures spanned unrelated ACP/MCP extras, Matrix/WeCom, web-build/update fixtures, host audio/process detection, and other environment-sensitive lanes; only the three gateway failures above were separately baseline-reproduced.

4. Static checks:

   ruff check gateway/run.py plugins/platforms/telegram/adapter.py \
     tests/gateway/test_async_delegation_telegram_panel.py \
     tests/gateway/test_telegram_status_delivery.py
   python3 -m py_compile gateway/run.py plugins/platforms/telegram/adapter.py \
     tests/gateway/test_async_delegation_telegram_panel.py \
     tests/gateway/test_telegram_status_delivery.py
   git diff --check

   Result: passed. Repository-wide ty has pre-existing diagnostics; no diagnostic was reported in the changed production ranges.

5. Exact post-ID-correction independent review: APPROVE, no blocking findings. The reviewer confirmed the full native ID remains actionable and signature-bearing, measured a maximal native-ID panel at 495 ≤ 500 code points, and found no regression in allowlisting, routing, flood containment, completion ordering, or default Telegram behavior.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this feature
• The canonical complete test suite passes without unrelated baseline/environment failures
• I've added focused tests for the new contract
• Tested on Ubuntu 24.04, Linux 6.8.0-117-generic, x86_64

Documentation & Housekeeping

• Relevant delegation documentation updated
• cli-config.yaml.example: N/A — no config keys added or changed
• CONTRIBUTING.md / AGENTS.md: N/A — no contributor workflow changed
• Cross-platform impact considered: Python-only gateway/Telegram behavior; no platform-specific filesystem or process assumptions
• Tool descriptions/schemas: N/A — no model tool behavior changed

Screenshots / Logs

No UI screenshot is included because the surface is a plain-text Telegram message and no live bot/service was modified during development. Focused, affected, broad-gateway, and complete-suite evidence is reported above.

[GottZ]

This was generated by AI during triage.

Summary

One PR addresses #76389. #76390 implements the requested bounded Telegram delegation panel through source-aware routing, allowlisted in-place status updates, single-attempt delivery, completion-first ordering, and tests for routing, privacy, rate limits, and failure isolation.

Related pull requests

• feat(telegram): show bounded async delegation activity #76390 best fix — (+1180/-2) — direct implementation, not independently verified: The diff adds the missing in-progress Telegram visibility by projecting list_async_delegations() into one bounded status message per delegation, with fail-closed multiplex provenance, preserved topic/reply routing, finite I/O budgets, and non-fatal delivery failures. Its gateway lifecycle/rate-limiting logic and Telegram delivery primitive are substantial separable review units.

Suggested consolidation

Keep #76390 open with a salvage path: retain its tested source-aware panel projection and single-attempt Telegram delivery design, but split the adapter delivery primitive from the gateway panel lifecycle and rate-limiting integration so each can be reviewed independently.

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
    I76389(["issue #76389 (open)"])
    P76390["PR #76390 (open)"]
    P76390 -->|best fix| I76389
    class I76389 open
    class P76390 open
    class P76390 best
    class P76390 target
    click I76389 "https://github.com/NousResearch/hermes-agent/issues/76389"
    click P76390 "https://github.com/NousResearch/hermes-agent/pull/76390"

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 1 issue in this complex. Each diff was read against this issue; Assessment working set: 53 kB of PR diffs, 12 kB of issue/PR text, 2 verify verdicts. verdicts reflect diff content, not PR titles. Part of an automated triage batch.