Summary

• Problem: transient Telegram sendChatAction failures (network / 429 / temporary 5xx) can keep firing repeatedly, creating noisy retry loops and log spam.
• Why it matters: typing indicators are best-effort, so repeated failures should not keep hammering Telegram or interfere with normal reply delivery.
• What changed: kept the existing 401 suspend behavior, and added a separate transient cooldown path that temporarily suppresses repeated sendChatAction calls until a later recovery.
• What did NOT change (scope boundary): this PR does not change typingMode config behavior, message delivery flow, or Telegram channel startup/runtime wiring outside the dedicated handler.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes Telegram sendChatAction retry spam during transient failures openclaw/openclaw#55811
• Related Telegram typingMode: 'never' not working - sendChatAction 401 errors persist openclaw/openclaw#48943
• This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

• Root cause: the dedicated Telegram sendChatAction handler only had global backoff / suspension behavior for 401s, but transient failures still retried on every later call path.
• Missing detection / guardrail: the handler had no cooldown state for transient network / rate-limit / temporary server failures, and the dedicated test file did not currently lock in that behavior.
• Prior context (git blame, prior PR, issue, or refactor if known): the current per-account guard already existed for 401 token failures in sendchataction-401-backoff.ts.
• Why this regressed now: as more users hit Telegram transient failures, the handler protected the invalid-token case but not the best-effort transient case.
• If unknown, what was ruled out: this PR does not treat typingMode config propagation as the root cause for this specific issue.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: extensions/telegram/src/sendchataction-401-backoff.test.ts
• Scenario the test should lock in: transient failures enter cooldown, repeated calls are suppressed during cooldown, recovery clears transient state, and 401 suspension semantics still work independently.
• Why this is the smallest reliable guardrail: the bug lives in the dedicated per-account handler state machine, so direct unit coverage is the narrowest reliable test.
• Existing test that already covers this (if any): extensions/telegram/src/send.test.ts -t "sends typing" still covers the normal typing send seam.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

• Repeated transient sendChatAction failures no longer keep retrying on every call path.
• 401 invalid-token behavior is unchanged.
• No config or default changes.

Diagram (if applicable)

Before:
transient sendChatAction failure -> next typing call retries immediately -> repeated failures/log spam

After:
transient sendChatAction failure -> cooldown starts -> repeated typing calls skipped -> later success clears cooldown

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No

Repro + Verification

Environment

• OS: macOS
• Runtime/container: local pnpm workspace
• Model/provider: N/A
• Integration/channel (if any): Telegram
• Relevant config (redacted): existing Telegram channel config

Steps

1. Simulate repeated transient sendChatAction failures.
2. Trigger repeated handler calls during the cooldown window.
3. Verify repeated calls are suppressed and later recovery clears the transient state.

Expected

• transient failures do not suspend the handler permanently
• repeated calls during cooldown do not keep calling Telegram
• later success restores normal behavior
• 401 behavior still suspends as before

Actual

• matches expected in targeted local verification

Evidence

• Failing test/log before + passing after

Human Verification (required)

• Verified scenarios:
  • transient network failure cooldown
  • transient recovery path
  • 429 transient handling
  • 5xx transient handling
  • unexpected non-transient error still throws
  • 401 semantics remain active
  • mixed 401 -> transient -> 401 sequence preserves 401 counter
• Edge cases checked:
  • cooldown suppression is global per handler
  • Date.now-driven cooldown expiry path
• What you did not verify:
  • live Telegram outage against the real API
  • broader typingMode configuration behavior

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No

Risks and Mitigations

• Risk: treating some Telegram-side failures as transient could suppress useful signal for a short period.
  • Mitigation: only network / 429 / temporary 5xx go through cooldown; unexpected non-transient errors still throw, and 401 still suspends.

🤖 AI-assisted (Codex), tested with focused local verification