Your lightweight open-source personal agent.
Python agent-frameworkai-agentai-agentschatbotchatopsdiscord-botllm-agentsllmslocal-llmmcpmodel-context-protocolmulti-agentopenai-compatibleopenclawpersonal-ai-assistantpythonself-hostedtelegram-bot-ai-assistantwebuiworkflow-automation
fix: modernize dependency recovery guidance (#5282)
chengyongruff6deda17882
diff --git a/docs/guides/configure-langfuse-observability.md b/docs/guides/configure-langfuse-observability.mdindex 140a24d05..b979f4c99 100644--- a/docs/guides/configure-langfuse-observability.md+++ b/docs/guides/configure-langfuse-observability.md@@ -27,7 +27,7 @@ nanobot agent -m "Hello!"Install Langfuse:```bash-python -m pip install langfuse+nanobot plugins enable langfuse```## Minimal working examplediff --git a/docs/provider-cookbook.md b/docs/provider-cookbook.mdindex f7a6b40db..3eb2ef509 100644--- a/docs/provider-cookbook.md+++ b/docs/provider-cookbook.md@@ -549,7 +549,7 @@ This recipe applies after the agent works and you want observability for OpenAI-Install the optional package in the same Python environment that runs nanobot:```bash-python -m pip install langfuse+nanobot plugins enable langfuse```Set the environment variables before starting nanobot:diff --git a/nanobot/agent/tools/web.py b/nanobot/agent/tools/web.pyindex c2d8e011c..ec4523a86 100644--- a/nanobot/agent/tools/web.py+++ b/nanobot/agent/tools/web.py@@ -458,7 +458,10 @@ class WebSearchTool(Tool):Olostep_BaseError, # pyright: ignore[reportUnknownVariableType])except ImportError:- return ToolResult.error("Error: olostep package not installed. Run: pip install olostep")+ return ToolResult.error(+ "Error: Olostep support is not installed. "+ "Run `nanobot plugins enable olostep`."+ )async_olostep = cast(Any, AsyncOlostep)olostep_base_error = cast(type[Exception], Olostep_BaseError)api_key = self.config.api_key or os.environ.get("OLOSTEP_API_KEY", "")diff --git a/nanobot/channels/weixin/runtime.py b/nanobot/channels/weixin/runtime.pyindex bd2e49166..3d1e3af01 100644--- a/nanobot/channels/weixin/runtime.py+++ b/nanobot/channels/weixin/runtime.py@@ -1683,7 +1683,10 @@ def _encrypt_aes_ecb(data: bytes, aes_key_b64: str) -> bytes:encryptor = cipher_obj.encryptor()return encryptor.update(padded) + encryptor.finalize()except ImportError:- logger.warning("Cannot encrypt media: install 'pycryptodome' or 'cryptography'")+ logger.warning(+ "Cannot encrypt media. Run `nanobot plugins enable weixin` "+ "to install WeChat support."+ )return data@@ -1715,7 +1718,10 @@ def _decrypt_aes_ecb(data: bytes, aes_key_b64: str) -> bytes:decryptor = cipher_obj.decryptor()decrypted = decryptor.update(data) + decryptor.finalize()except ImportError:- logger.warning("Cannot decrypt media: install 'pycryptodome' or 'cryptography'")+ logger.warning(+ "Cannot decrypt media. Run `nanobot plugins enable weixin` "+ "to install WeChat support."+ )return datareturn _pkcs7_unpad_safe(decrypted)diff --git a/nanobot/channels/weixin/tests/test_weixin_channel.py b/nanobot/channels/weixin/tests/test_weixin_channel.pyindex 1338a7162..46ba4e058 100644--- a/nanobot/channels/weixin/tests/test_weixin_channel.py+++ b/nanobot/channels/weixin/tests/test_weixin_channel.py@@ -1080,6 +1080,32 @@ def test_decrypt_aes_ecb_strips_valid_pkcs7_padding() -> None:assert decrypted == plaintext+def test_missing_aes_dependency_recommends_weixin_plugin(monkeypatch) -> None:+ real_import = __import__++ def fake_import(name, *args, **kwargs):+ if name.startswith(("Crypto", "cryptography")):+ raise ImportError("missing AES dependency")+ return real_import(name, *args, **kwargs)++ warnings: list[str] = []+ monkeypatch.setattr("builtins.__import__", fake_import)+ monkeypatch.setattr(+ weixin_mod.logger,+ "warning",+ lambda message, *args: warnings.append(message.format(*args)),+ )+ key_b64 = "MDEyMzQ1Njc4OWFiY2RlZg=="+ data = b"unencrypted media"++ assert _encrypt_aes_ecb(data, key_b64) == data+ assert _decrypt_aes_ecb(data, key_b64) == data+ assert warnings == [+ "Cannot encrypt media. Run `nanobot plugins enable weixin` to install WeChat support.",+ "Cannot decrypt media. Run `nanobot plugins enable weixin` to install WeChat support.",+ ]++class _DummyDownloadResponse:def __init__(self, content: bytes, status_code: int = 200) -> None:self.content = contentdiff --git a/nanobot/cli/onboard.py b/nanobot/cli/onboard.pyindex 27571a438..b28647f7c 100644--- a/nanobot/cli/onboard.py+++ b/nanobot/cli/onboard.py@@ -32,6 +32,7 @@ from nanobot.cli.models import ()from nanobot.config.loader import get_config_path, load_config, resolve_config_env_varsfrom nanobot.config.schema import Config, ModelPresetConfig+from nanobot.providers.oauth_guidance import OAUTH_CLI_KIT_MISSING_MESSAGEconsole = Console()@@ -1674,7 +1675,7 @@ def _quick_start_oauth_login(config: Config, provider_name: str) -> bool:login_oauth_interactive,)except ImportError:- console.print("[red]oauth_cli_kit not installed. Run: pip install oauth-cli-kit[/red]")+ console.print(f"[red]{OAUTH_CLI_KIT_MISSING_MESSAGE}[/red]")return Falsetry:diff --git a/nanobot/cli/provider.py b/nanobot/cli/provider.pyindex 3d2c0a626..d0769bc99 100644--- a/nanobot/cli/provider.py+++ b/nanobot/cli/provider.py@@ -12,6 +12,7 @@ import typerfrom rich.console import Consolefrom nanobot import __logo__+from nanobot.providers.oauth_guidance import OAUTH_CLI_KIT_MISSING_MESSAGEif TYPE_CHECKING:from nanobot.providers.registry import ProviderSpec@@ -74,7 +75,7 @@ def _required_module_attribute(module_name: str, attribute: str) -> object:def _load_openai_oauth_client() -> tuple[_GetOAuthToken, _LoginOAuthInteractive]:- """Load the optional untyped OAuth client behind a typed boundary."""+ """Load the untyped OAuth client behind a typed boundary."""return (cast(_GetOAuthToken, _required_module_attribute("oauth_cli_kit", "get_token")),cast(@@ -85,7 +86,7 @@ def _load_openai_oauth_client() -> tuple[_GetOAuthToken, _LoginOAuthInteractive]def _load_openai_oauth_storage() -> tuple[_OAuthProviderConfig, _FileTokenStorageFactory]:- """Load the optional untyped OAuth storage API behind a typed boundary."""+ """Load the untyped OAuth storage API behind a typed boundary."""return (cast(_OAuthProviderConfig,@@ -241,7 +242,7 @@ def _login_openai_codex() -> None:f"[green]✓ Authenticated with OpenAI Codex[/green] [dim]{token.account_id}[/dim]")except ImportError:- console.print("[red]oauth_cli_kit not installed. Run: pip install oauth-cli-kit[/red]")+ console.print(f"[red]{OAUTH_CLI_KIT_MISSING_MESSAGE}[/red]")raise typer.Exit(1)@@ -250,7 +251,7 @@ def _logout_openai_codex() -> None:try:provider_config, storage_factory = _load_openai_oauth_storage()except ImportError:- console.print("[red]oauth_cli_kit not installed. Run: pip install oauth-cli-kit[/red]")+ console.print(f"[red]{OAUTH_CLI_KIT_MISSING_MESSAGE}[/red]")raise typer.Exit(1)storage = storage_factory(token_filename=provider_config.token_filename)@@ -309,7 +310,7 @@ def _logout_github_copilot() -> None:try:from nanobot.providers.github_copilot_provider import get_storageexcept ImportError:- console.print("[red]oauth_cli_kit not installed. Run: pip install oauth-cli-kit[/red]")+ console.print(f"[red]{OAUTH_CLI_KIT_MISSING_MESSAGE}[/red]")raise typer.Exit(1)storage = get_storage()diff --git a/nanobot/providers/oauth_guidance.py b/nanobot/providers/oauth_guidance.pynew file mode 100644index 000000000..1f3315402--- /dev/null+++ b/nanobot/providers/oauth_guidance.py@@ -0,0 +1,6 @@+"""Shared recovery guidance for OAuth dependency failures."""++OAUTH_CLI_KIT_MISSING_MESSAGE = (+ "This nanobot installation is missing the required oauth-cli-kit package. "+ "Reinstall or upgrade nanobot-ai using the same installation method."+)diff --git a/nanobot/providers/openai_compat_provider.py b/nanobot/providers/openai_compat_provider.pyindex e66f98d3d..d6e7e47bd 100644--- a/nanobot/providers/openai_compat_provider.py+++ b/nanobot/providers/openai_compat_provider.py@@ -586,7 +586,7 @@ class OpenAICompatProvider(LLMProvider):if os.environ.get("LANGFUSE_SECRET_KEY"):logger.warning("LANGFUSE_SECRET_KEY is set but langfuse is not installed; "- "install with `pip install langfuse` to enable tracing"+ "run `nanobot plugins enable langfuse` to enable tracing")from openai import AsyncOpenAI as _AsyncOpenAIAsyncOpenAI = _AsyncOpenAIdiff --git a/nanobot/webui/settings_api.py b/nanobot/webui/settings_api.pyindex 877c35b03..1c77a293e 100644--- a/nanobot/webui/settings_api.py+++ b/nanobot/webui/settings_api.py@@ -4,7 +4,7 @@ The WebSocket channel owns transport/authentication. This module owns thesettings payload shape and the allowlisted config mutations exposed to WebUI."""-# oauth-cli-kit is an optional dependency and does not publish type stubs.+# oauth-cli-kit does not publish type stubs.# pyright: reportMissingTypeStubs=falsefrom __future__ import annotations@@ -36,6 +36,7 @@ from nanobot.providers.image_generation import (get_image_gen_provider,image_gen_provider_names,)+from nanobot.providers.oauth_guidance import OAUTH_CLI_KIT_MISSING_MESSAGEfrom nanobot.providers.registry import PROVIDERS, create_dynamic_spec, find_by_namefrom nanobot.security.network import is_loopback_hostfrom nanobot.security.workspace_access import workspace_sandbox_status@@ -1794,9 +1795,7 @@ def login_oauth_provider(query: QueryParams) -> dict[str, Any]:try:from nanobot.providers.openai_codex_oauth import start_openai_codex_oauth_loginexcept ImportError:- raise WebUISettingsError(- "oauth_cli_kit not installed. Run: pip install oauth-cli-kit", status=500- ) from None+ raise WebUISettingsError(OAUTH_CLI_KIT_MISSING_MESSAGE, status=500) from Nonetry:proxy = resolve_config_env_vars(load_config()).providers.openai_codex.proxy or None@@ -1834,9 +1833,7 @@ def login_oauth_provider(query: QueryParams) -> dict[str, Any]:login_github_copilot,)except ImportError:- raise WebUISettingsError(- "oauth_cli_kit not installed. Run: pip install oauth-cli-kit", status=500- ) from None+ raise WebUISettingsError(OAUTH_CLI_KIT_MISSING_MESSAGE, status=500) from Nonetoken = get_github_copilot_login_status()if not token:@@ -1934,18 +1931,14 @@ def logout_oauth_provider(query: QueryParams) -> dict[str, Any]:from oauth_cli_kit.providers import OPENAI_CODEX_PROVIDERfrom oauth_cli_kit.storage import FileTokenStorageexcept ImportError:- raise WebUISettingsError(- "oauth_cli_kit not installed. Run: pip install oauth-cli-kit", status=500- ) from None+ raise WebUISettingsError(OAUTH_CLI_KIT_MISSING_MESSAGE, status=500) from None_clear_webui_oauth_flows(spec.name)token_path = FileTokenStorage(token_filename=OPENAI_CODEX_PROVIDER.token_filename).get_token_path()elif spec.name == "github_copilot":try:from nanobot.providers.github_copilot_provider import get_storageexcept ImportError:- raise WebUISettingsError(- "oauth_cli_kit not installed. Run: pip install oauth-cli-kit", status=500- ) from None+ raise WebUISettingsError(OAUTH_CLI_KIT_MISSING_MESSAGE, status=500) from Nonetoken_path = get_storage().get_token_path()elif spec.name == "xai_grok":from nanobot.providers.xai_oauth import logout_xai_oauthdiff --git a/tests/agent/test_onboard_logic.py b/tests/agent/test_onboard_logic.pyindex 7a28133ec..e075f4511 100644--- a/tests/agent/test_onboard_logic.py+++ b/tests/agent/test_onboard_logic.py@@ -1092,6 +1092,23 @@ class TestMainMenuUpdate:assert config.providers.openai.api_key == "${UNRELATED_MISSING_KEY}"assert config.providers.openai_codex.proxy == "${CODEX_PROXY}"+ def test_quick_start_openai_codex_reports_incomplete_installation(self, monkeypatch):+ import oauth_cli_kit++ messages: list[str] = []+ monkeypatch.delattr(oauth_cli_kit, "get_token")+ monkeypatch.setattr(+ onboard_wizard.console,+ "print",+ lambda message, *args, **kwargs: messages.append(str(message)),+ )++ assert onboard_wizard._quick_start_oauth_login(Config(), "openai_codex") is False+ assert messages == [+ "[red]This nanobot installation is missing the required oauth-cli-kit package. "+ "Reinstall or upgrade nanobot-ai using the same installation method.[/red]"+ ]+def test_quick_start_openai_codex_runs_interactive_login_for_bad_cached_token(self, monkeypatch):diff --git a/tests/cli/test_commands.py b/tests/cli/test_commands.pyindex 510d59164..4c79c91a0 100644--- a/tests/cli/test_commands.py+++ b/tests/cli/test_commands.py@@ -686,7 +686,10 @@ def test_provider_login_openai_codex_handles_missing_oauth_symbol(monkeypatch):result = runner.invoke(app, ["provider", "login", "openai-codex"])assert result.exit_code == 1- assert "oauth_cli_kit not installed" in result.stdout+ assert (+ "This nanobot installation is missing the required oauth-cli-kit package. "+ "Reinstall or upgrade nanobot-ai using the same installation method."+ ) in re.sub(r"\s+", " ", result.stdout)assert result.exception is not Nonediff --git a/tests/providers/test_openai_compat_timeout.py b/tests/providers/test_openai_compat_timeout.pyindex 519d22ec2..fd9a38752 100644--- a/tests/providers/test_openai_compat_timeout.py+++ b/tests/providers/test_openai_compat_timeout.py@@ -1,5 +1,6 @@from unittest.mock import patch, sentinel+from nanobot.providers import openai_compat_providerfrom nanobot.providers.openai_compat_provider import OpenAICompatProviderfrom nanobot.providers.registry import ProviderSpec@@ -59,3 +60,22 @@ async def test_openai_compat_provider_timeout_can_be_overridden_by_env(monkeypatawait provider._ensure_client()assert mock_async_openai.call_args.kwargs["timeout"] == 45.0+++async def test_missing_langfuse_warning_recommends_plugin_command(monkeypatch) -> None:+ monkeypatch.setenv("LANGFUSE_SECRET_KEY", "secret")+ monkeypatch.setattr(openai_compat_provider, "AsyncOpenAI", None)++ with (+ patch("importlib.util.find_spec", return_value=None),+ patch("openai.AsyncOpenAI") as mock_async_openai,+ patch("nanobot.providers.openai_compat_provider.logger.warning") as mock_warning,+ ):+ provider = OpenAICompatProvider(api_key="test-key", api_base="https://example.com/v1")+ await provider._ensure_client()++ mock_warning.assert_called_once_with(+ "LANGFUSE_SECRET_KEY is set but langfuse is not installed; "+ "run `nanobot plugins enable langfuse` to enable tracing"+ )+ mock_async_openai.assert_called_once()diff --git a/tests/tools/test_web_search_tool.py b/tests/tools/test_web_search_tool.pyindex c9130b5d3..82eb68c1c 100644--- a/tests/tools/test_web_search_tool.py+++ b/tests/tools/test_web_search_tool.py@@ -820,4 +820,6 @@ async def test_olostep_package_missing_returns_install_hint(monkeypatch):tool = _tool(provider="olostep", api_key="olostep-key")result = await tool.execute(query="test query")- assert result == "Error: olostep package not installed. Run: pip install olostep"+ assert result == (+ "Error: Olostep support is not installed. Run `nanobot plugins enable olostep`."+ )diff --git a/tests/webui/test_settings_api.py b/tests/webui/test_settings_api.pyindex 3d92b0356..1151d902f 100644--- a/tests/webui/test_settings_api.py+++ b/tests/webui/test_settings_api.py@@ -1624,7 +1624,10 @@ def test_openai_codex_oauth_login_reports_missing_oauth_cli_kit(with pytest.raises(WebUISettingsError) as exc:login_oauth_provider({"provider": ["openai-codex"]})- assert "oauth_cli_kit not installed. Run: pip install oauth-cli-kit" in str(exc.value)+ assert str(exc.value) == (+ "This nanobot installation is missing the required oauth-cli-kit package. "+ "Reinstall or upgrade nanobot-ai using the same installation method."+ )def test_github_copilot_oauth_login_reports_missing_oauth_cli_kit(@@ -1642,7 +1645,10 @@ def test_github_copilot_oauth_login_reports_missing_oauth_cli_kit(with pytest.raises(WebUISettingsError) as exc:login_oauth_provider({"provider": ["github-copilot"]})- assert "oauth_cli_kit not installed. Run: pip install oauth-cli-kit" in str(exc.value)+ assert str(exc.value) == (+ "This nanobot installation is missing the required oauth-cli-kit package. "+ "Reinstall or upgrade nanobot-ai using the same installation method."+ )def test_xai_grok_login_starts_fresh_browser_flow_with_proxy(