feat: add sandbox image viewing tool

docs/telegram-setup.md

@@ -199,7 +199,13 @@ To verify image input, select a vision-capable model, send a Telegram photo,
 and optionally add a caption as the instruction. Without a caption, Blacki asks
 the model to describe the image. Native photo input is limited to 10 MB;
 documents, audio, video, and voice messages continue to use the sandbox upload
-path. A model that does not support images will return the normal photo
+path. When an image is sent as a Telegram file/document, Blacki exposes its
+`/workspace/uploads/...` path to the agent and the agent can call
+`sandbox_view_image` to attach it as a visual input. Call the tool once per
+image when several files are present; each image remains a separate model
+input rather than being combined into a collage. The tool accepts a path below
+`/workspace`, validates common PNG, JPEG, GIF, WebP, and BMP files, and is
+read-only. A model that does not support images will return the normal photo
 processing error without changing the selected model.
 
 ## Tool notifications

src/blacki/agent.py

@@ -284,9 +284,19 @@ def create_app(agent: LlmAgent | None = None) -> App:
         DeclarativeDbPlugin,
         StoredPreferencesPlugin,
     )
+    from blacki.sandbox import (
+        SandboxMultimodalToolResultsPlugin,
+        sandbox_enabled,
+    )
     from blacki.user_files import UserFilesPromptPlugin, user_files_enabled
 
+    sandbox_tools_enabled = sandbox_enabled()
     plugins: list[BasePlugin] = [
+        *(
+            [SandboxMultimodalToolResultsPlugin(name="sandbox_multimodal_results")]
+            if sandbox_tools_enabled
+            else []
+        ),
         TelegramModelOverridePlugin(name="telegram_model_override"),
         GlobalInstructionPlugin(return_global_instruction),
         DomainPolicyPlugin(name="domain_policy"),

src/blacki/prompt.py

@@ -210,6 +210,7 @@
         "sandbox_list_files",
         "sandbox_send_file_to_user",
         "sandbox_execute_code",
+        "sandbox_view_image",
         "McpSkillToolset",
     }
 )

src/blacki/registry.py

@@ -225,6 +225,7 @@ def _build_sandbox_tools() -> list[Any]:
             sandbox_read_file,
             sandbox_run_command,
             sandbox_send_file_to_user,
+            sandbox_view_image,
             sandbox_write_file,
         )
 
@@ -235,6 +236,7 @@ def _build_sandbox_tools() -> list[Any]:
             sandbox_list_files,
             sandbox_send_file_to_user,
             sandbox_execute_code,
+            sandbox_view_image,
         ]
     except ImportError as e:  # pragma: no cover
         logger.warning("Failed to load Sandbox tools: %s", e)

src/blacki/sandbox/__init__.py

@@ -2,8 +2,10 @@
 
 from .code_interpreter import sandbox_execute_code
 from .config import SandboxConfig, load_sandbox_config
+from .images import SandboxMultimodalToolResultsPlugin, sandbox_view_image
 from .manager import SandboxManager, get_sandbox_manager, reset_sandbox_manager
 from .tools import (
+    sandbox_enabled,
     sandbox_list_files,
     sandbox_read_file,
     sandbox_run_command,
@@ -17,10 +19,13 @@
     "get_sandbox_manager",
     "load_sandbox_config",
     "reset_sandbox_manager",
+    "sandbox_enabled",
     "sandbox_list_files",
     "sandbox_read_file",
     "sandbox_run_command",
     "sandbox_send_file_to_user",
     "sandbox_write_file",
     "sandbox_execute_code",
+    "sandbox_view_image",
+    "SandboxMultimodalToolResultsPlugin",
 ]