fix(onboard): skip unreachable Telegram during non-interactive setup

[rluo8]

Summary

Fixes non-interactive onboarding so optional Telegram setup no longer aborts when Telegram validation fails. If api.telegram.org is unreachable or the bot token is rejected, onboarding now warns, disables Telegram for the run, and continues, matching the optional-component behavior.

Related Issue

Fixes #4238

Changes

• Extracted Telegram reachability probing into src/lib/onboard/telegram-reachability.ts.
• Changed Telegram network failures and 401/404 token rejection into warn-and-skip results.
• Updated messaging channel setup to remove Telegram from enabled channels when reachability validation skips it.
• Added unit coverage for valid token, invalid token, network curl failures, skip-probe override, and interactive network-failure handling.

Type of Change

• [√] Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Verification

• [√] npx prek run --all-files passes
• [√] npm test passes
• [√ ] Tests added or updated for new or changed behavior
• [√] No secrets, API keys, or credentials committed
• Docs updated for user-facing behavior changes
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: rluo8 ruluo@nvidia.com

Summary by CodeRabbit

• New Features

  • Added Telegram reachability probe during onboarding that can auto-skip or prompt to disable Telegram when unreachable; token rejection marks Telegram as skipped. Honors environment override to bypass the probe.

• Tests

  • Added tests for probe success, token rejection, network failures, override behavior, interactive prompts, and exit-on-decline.

• Refactor

  • Moved Telegram validation into a dedicated onboarding module for clearer flow.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: dbb16760-85df-4d88-8954-5ba166b40c1c

📥 Commits

Reviewing files that changed from the base of the PR and between 4248d3e and 4e330b0.

📒 Files selected for processing (1)

• src/lib/onboard.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/lib/onboard.ts

---

📝 Walkthrough

Walkthrough

Extracts Telegram reachability into a new module, wires it into onboarding (imports and deps), invokes the probe in non-interactive and interactive flows to skip/disable Telegram when appropriate, and adds Vitest tests for probe outcomes and prompts.

Changes

Telegram Reachability Probe

Layer / File(s)	Summary
Telegram reachability probe implementation src/lib/onboard/telegram-reachability.ts	New module with TELEGRAM_NETWORK_CURL_CODES, TelegramReachabilityDeps/result types, and checkTelegramReachability(token, deps) implementing env-skip, curl probe, HTTP 401/404 handling (skip), network-failure handling (auto-skip in non-interactive or interactive prompt/exit), and non-blocking warnings for other failures.
Onboard imports and deps wiring src/lib/onboard.ts	Imports checkTelegramReachability and TELEGRAM_NETWORK_CURL_CODES; constructs telegramReachabilityDeps wiring isNonInteractive, note, and promptYesNoOrDefault.
Onboard non-interactive flow: probe call and skip handling src/lib/onboard.ts	Non-interactive messaging-channel flow calls checkTelegramReachability(telegramToken, telegramReachabilityDeps) and filters out telegram if the probe returns { skipped: true }.
Onboard interactive flow: preflight probe and disable handling src/lib/onboard.ts	Interactive messaging preflight calls checkTelegramReachability and deletes telegram from enabled set when { skipped: true } is returned.
Test Suite - Probe behavior and prompts src/lib/onboard/telegram-reachability.test.ts	Vitest suite validating HTTP 200 success, network-level curl failures treated as unreachable, HTTP 401/404 token rejection (skip), NEMOCLAW_SKIP_TELEGRAM_REACHABILITY=1 override, and interactive prompt accept (skip) vs decline (exit).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~30 minutes

Possibly related issues

• #4239 — Addresses non-interactive abort when api.telegram.org is unreachable by auto-skipping Telegram on network failures.

Possibly related PRs

• NVIDIA/NemoClaw#4200 — Overlaps in messaging-channel/token validation and onboarding Telegram handling.

Suggested labels

bug, NemoClaw CLI

Suggested reviewers

• ericksoa
• cv

Poem

🐰 I hopped the net with eager paws,

I nudged the bot to check its cause,
If Telegram’s gate is closed today,
We skip it gently and hop away.
Carrots and logs guide our new way 🥕

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: skipping unreachable Telegram during non-interactive setup, which directly addresses the core objective from issue #4238.
Linked Issues check	✅ Passed	The PR successfully implements all coding requirements from #4238: reachability probing returns a skipped flag, network failures and token rejections (401/404) trigger warn-and-skip behavior instead of abort, and Telegram is removed from enabled channels when skipped.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to the Telegram reachability validation objective: extraction of probing logic to telegram-reachability.ts, handling of network/token failures as warn-and-skip, integration into onboard.ts setup paths, and test coverage for the new behavior.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

src/lib/onboard.ts (1)

5830-5861: Run targeted onboarding/messaging E2E for this behavior change.

Given this touches core onboarding and Telegram channel gating logic, please run at least cloud-e2e, sandbox-operations-e2e, channels-stop-start-e2e, and messaging-compatible-endpoint-e2e on this branch before merge.

As per coding guidelines, "src/lib/onboard.ts: This file contains core onboarding logic. Changes here affect the full sandbox creation and configuration flow." and the listed E2E test recommendations apply.

Also applies to: 5980-5986

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib/onboard.ts` around lines 5830 - 5861, Run the targeted E2E suites
covering the onboarding/messaging changes introduced in setupMessagingChannels:
execute cloud-e2e, sandbox-operations-e2e, channels-stop-start-e2e, and
messaging-compatible-endpoint-e2e against this branch to validate the
non-interactive messaging gating and Telegram reachability behavior
(checkTelegramReachability, resolveMessagingChannelSeed,
getValidatedMessagingToken/getValidatedMessagingTokenByEnvKey paths), and also
run the same tests for the related changes around lines ~5980-5986 to ensure no
regressions in sandbox creation and messaging channel startup/shutdown flows.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/lib/onboard/telegram-reachability.test.ts`:
- Around line 98-110: The test sets a process.exit spy but may leak it if an
assertion throws; wrap the spy lifecycle in a try/finally (or move to afterEach)
so restore always runs: create the exitSpy via vi.spyOn(process, "exit") before
awaiting checkTelegramReachability("123:abc", deps) and put the assertions
inside a try block, then call exitSpy.mockRestore() in finally; reference
runCurlProbe, checkTelegramReachability, makeDeps and the exitSpy to locate the
change.

---

Nitpick comments:
In `@src/lib/onboard.ts`:
- Around line 5830-5861: Run the targeted E2E suites covering the
onboarding/messaging changes introduced in setupMessagingChannels: execute
cloud-e2e, sandbox-operations-e2e, channels-stop-start-e2e, and
messaging-compatible-endpoint-e2e against this branch to validate the
non-interactive messaging gating and Telegram reachability behavior
(checkTelegramReachability, resolveMessagingChannelSeed,
getValidatedMessagingToken/getValidatedMessagingTokenByEnvKey paths), and also
run the same tests for the related changes around lines ~5980-5986 to ensure no
regressions in sandbox creation and messaging channel startup/shutdown flows.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 1414f0d5-0f08-49c7-b08f-dbc84560767f

📥 Commits

Reviewing files that changed from the base of the PR and between d312144 and 82b36f5.

📒 Files selected for processing (3)

• src/lib/onboard.ts
• src/lib/onboard/telegram-reachability.test.ts
• src/lib/onboard/telegram-reachability.ts

[wscurran]

✨
Related open issues:

• #4238 [Ubuntu 24.04][Onboard] non-interactive onboard aborts when Telegram API is unreachable

[cjagwani]

lgtm. closes #4238 with the right pattern:

• mirrors the Brave optional-integration warn-and-skip path (web-search-flow.ts) — consistent with existing codebase convention
• proper DI on isNonInteractive/note/promptYesNoOrDefault makes the module testable without globals
• net-negative on onboard.ts (10+/61-), satisfies entrypoint budget
• 401/404 token-rejected case also takes the skip path with rationale comment — correct: a rejected token can't function downstream either
• interactive default Y favors soft-fail (matches optional-integration contract)
• recovery hint in skip warning is brand-agnostic via cliName()
• test coverage hits OK, every curl code in TELEGRAM_NETWORK_CURL_CODES, 401, 404, env override, interactive prompt path

dismissed — posted without maintainer authorization