fix(sandbox): point boxlite install advice at the running environment

[yudongyouqing]

Summary

• The missing-boxlite advice told users to run pip install 'raven[sandbox]', which is wrong twice over: the raven name on package indexes resolves to an unrelated project, and a global pip install bypasses the uv environment raven actually runs in (fix: raven boxlite recommends to install pip install raven[sandbox] is sloppy #640).
• Added boxlite_install_hint() to raven.sandbox: it resolves the pinned boxlite requirement from the installed distribution metadata (falling back to the bare name when metadata is absent) and renders a copy-pasteable command targeting the running interpreter, e.g. uv pip install --python /path/to/venv/bin/python boxlite==0.9.5.
• The onboarding screen keeps its translatable line in the zh catalog and prints the command on its own untranslatable line; build_executor's ImportError message uses the same hint.
• The two init-failure messages that fire after the boxlite import already succeeded no longer suggest a reinstall; they keep the platform bullets naming the actual causes.

Type

• Fix

Verification

• Relevant tests pass locally
• Relevant lint / type checks pass locally
• User-facing docs or screenshots are updated when needed

Commands run on macOS, Python 3.12, on top of a clean checkout of main:

• uv run pytest tests/test_sandbox_unit.py tests/test_cli_onboard_commands.py tests/test_i18n_boundary.py tests/test_i18n_prompts.py -q -> 467 passed. The new tests (TestBoxliteInstallHint, TestInitFailureAdvice, one TestBuildExecutor case, one onboard screen case) were each watched failing before the fix.
• uv run --frozen --python 3.12 --all-extras pytest -q -> 27002 passed, 109 skipped, 21 failed. The 21 failures reproduce identically on unmodified main (verified by stashing this change): test_agents_research_tools.py (13), test_agents_research_verbatim_sink.py (5), test_simulation_scenario.py and test_simulation_suite.py (2), test_rpc_files.py::test_a_host_without_libreoffice_says_so (1, LibreOffice not installed locally). None touch the changed modules.
• uv run ruff check and ruff format --check on the six touched files -> clean.
• make lint-imports -> 10 kept, 0 broken.
• make check-source-language -> pass.

Risk

• Security impact considered

• Backward compatibility considered

• Rollback path is clear for risky changes

• User-visible change: three messages read differently (the onboarding hint, the build_executor ImportError, two executor init-failure messages). No API, config, or behavior change beyond the wording. The hint assumes uv on PATH, which every documented install path already requires.

• Rollback is a straight revert of this commit.

Related Issues

Fixes #640

[0xKT]

Review of head 94219d5. The direction is right and CI is green. Two one-line fixes before merge; two follow-ups filed as issues, neither blocks this PR.

ID	tier	where	summary
R1	before-merge	raven/cli/onboard_commands.py:1845	the hint line is hard-wrapped at console width, so the copied command splits in two
R2	before-merge	scripts/boxlite_cli.py:167, scripts/boxlite_cli.py:625	two more copies of pip install raven[sandbox]
F1	follow-up, #844	raven/updates/upgrade.py:437	raven upgrade removes a boxlite installed per this hint
F2	follow-up, #845	raven/channels/adapters/whatsapp/bridge.py:143, raven/market/install.py:213	other hints that install raven by name

R1

• where: raven/cli/onboard_commands.py:1845
• problem: console.print wraps at console width (80 when stdout is not a TTY). With a uv tool install path such as /home/<user>/.local/share/uv/tools/raven/bin/python the line is about 95 characters, and Rich breaks it after the interpreter path. Copied as shown, it runs as two commands: uv pip install --python <path> with no package, then boxlite==0.9.5. The current test checks a substring, so it passes either way.
• fix: console.print(f" [dim] {boxlite_install_hint()}[/dim]", soft_wrap=True). raven/cli/agents_commands.py:43 uses Console(soft_wrap=True) for its copy-pasteable commands already.
• verify: add a test next to test_sandbox_boxlite_missing_advises_the_running_environment that pins a long interpreter path and asserts the hint arrives in one piece:

monkeypatch.setattr("sys.executable", "/home/someone/.local/share/uv/tools/raven/bin/python")
# ... same questionary / _probe_boxlite / _failure_choice patches as the existing test ...
onboard_commands._step2_sandbox(skip=False, non_interactive=False)
assert boxlite_install_hint() in capsys.readouterr().out

Checked on this head: red without the fix (the output holds .../raven/bin/python\nboxlite==0.9.5), green with it.

R2

• where: scripts/boxlite_cli.py:167, scripts/boxlite_cli.py:625
• problem: both still print pip install raven[sandbox], the advice fix: raven boxlite recommends to install pip install raven[sandbox] is sloppy #640 asks to remove.
• fix: the script runs from a checkout, and docs/sandbox/boxlite_cli.md:13 documents uv sync --extra sandbox for it, so print that in both places.
• verify: git grep -n "pip install raven\[sandbox\]" -- raven scripts returns nothing (today it returns exactly these two lines).

F1 (#844)

raven upgrade runs uv tool install --reinstall-package raven ..., falling back to --force. Both sync the tool environment to the release requirement set, which has no sandbox extra, so a boxlite installed with this hint is gone after the next upgrade. A configured boxlite backend then fails to start. This PR is still a strict improvement on main, because the old advice never installed the right package at all. Details and a reproduction are in the issue.

F2 (#845)

pip install --force-reinstall raven (WhatsApp bridge) and uv tool install raven --with <pkg> (market) have the same root cause as #640, on paths this PR does not touch.

[yudongyouqing]

Thanks for the detailed review. R1 and R2 are addressed in 323d8b7:

• R1: the hint now prints with soft_wrap=True, and there's a test next to test_sandbox_boxlite_missing_advises_the_running_environment that pins a long uv tool interpreter path and asserts the hint arrives in one piece (red without the fix, green with it).
• R2: both messages in scripts/boxlite_cli.py now print uv sync --extra sandbox; git grep "pip install raven\[sandbox\]" -- raven scripts comes back empty.

Happy to adjust further if anything's off.

[0xKT]

Merged in 0cf70f5, and #640 is closed with it. Thank you, @yudongyouqing!

This was a careful fix. The new advice installs boxlite into the interpreter Raven actually runs under, with the version taken from the package metadata instead of hard-coded, and the init-failure messages no longer tell people to reinstall something that is already installed. You also turned R1 and R2 around quickly, and the new test fails without the fix, which is exactly what we want.

Thanks again, and you are very welcome to pick up more issues here.