stackchan-mcp 0.13.0__tar.gz → 0.14.0__tar.gz

{stackchan_mcp-0.13.0 → stackchan_mcp-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackchan-mcp
-Version: 0.13.0
+Version: 0.14.0
 Summary: Two-faced MCP gateway for StackChan (xiaozhi-esp32): bridges stdio MCP clients to the ESP32 over WebSocket + HTTP.
 Project-URL: Homepage, https://github.com/kisaragi-mochi/stackchan-mcp
 Project-URL: Repository, https://github.com/kisaragi-mochi/stackchan-mcp

{stackchan_mcp-0.13.0 → stackchan_mcp-0.14.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stackchan-mcp"
-version = "0.13.0"
+version = "0.14.0"
 description = "Two-faced MCP gateway for StackChan (xiaozhi-esp32): bridges stdio MCP clients to the ESP32 over WebSocket + HTTP."
 readme = "README.md"
 requires-python = ">=3.10"

{stackchan_mcp-0.13.0 → stackchan_mcp-0.14.0}/stackchan_mcp/capture_server.py

@@ -51,6 +51,7 @@ import json
 import logging
 import os
 import secrets
+import sys
 import time
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, AsyncIterator
@@ -142,7 +143,11 @@ async def handle_capture(request: web.Request) -> web.Response:
 
     async for part in reader:
         if part.name == "question":
-            question = (await part.read()).decode("utf-8")
+            # Decode defensively: a malformed (non-UTF-8) question field must
+            # not turn a photo upload into a 500. The question is advisory
+            # metadata, so replacing undecodable bytes is preferable to
+            # dropping the whole capture.
+            question = (await part.read()).decode("utf-8", errors="replace")
         elif part.name == "file":
             timestamp = int(time.time() * 1000)
             filename = f"capture_{timestamp}.jpg"
@@ -445,19 +450,26 @@ def create_capture_app(
     dispatches to. May be ``None`` for tests of /capture alone; /pcm
     will return 503 in that case.
     """
-    # ``client_max_size=0`` disables aiohttp's per-request body size
-    # cap (default 1 MiB). The /pcm endpoint legitimately streams
-    # arbitrarily long PCM utterances (multi-minute TTS, live audio
-    # mixes); a 1 MiB cap would silently cut a chunked-transfer
-    # producer off mid-stream once its cumulative body exceeded that
-    # limit — observed in practice with a 200-second TTS push, which
-    # aborted around 36 s in (~2 MiB of source-rate PCM through the
-    # transfer-encoding pipe). The handler itself enforces no separate
-    # cap; back-pressure comes from the device-side Opus push rate
-    # inside ``send_pcm_stream``, which is the right place for it.
-    # /capture only receives JPEG snapshots from the ESP32 (well under
-    # 1 MiB each) so removing the cap costs it nothing.
-    app = web.Application(client_max_size=0)
+    # Raise aiohttp's per-request body cap (default 1 MiB) effectively to
+    # unlimited. The /pcm endpoint legitimately streams arbitrarily long PCM
+    # utterances (multi-minute TTS, live audio mixes); a 1 MiB cap would
+    # silently cut a chunked-transfer producer off mid-stream once its
+    # cumulative body exceeded that limit — observed in practice with a
+    # 200-second TTS push, which aborted around 36 s in (~2 MiB of
+    # source-rate PCM through the transfer-encoding pipe).
+    #
+    # Use ``sys.maxsize`` rather than ``0``. Although ``0`` disables the cap
+    # for ``request.read()`` / ``request.post()`` (both guard with
+    # ``if 0 < max_size``), aiohttp's multipart reader does NOT special-case
+    # ``0``: ``BodyPartReader.read()`` compares ``len(data) > client_max_size``
+    # directly (aiohttp >= 3.14), so a client_max_size of 0 propagated into
+    # ``request.multipart()`` rejects ANY non-empty multipart field with
+    # HTTP 413. /capture reads its ``question`` form field via ``part.read()``,
+    # so with ``client_max_size=0`` every photo upload carrying a non-empty
+    # question 413s ("Failed to upload photo"). A large finite value avoids
+    # that trap while keeping /pcm effectively unbounded. /capture's real
+    # size limit is the explicit CAPTURE_MAX_BYTES check in handle_capture.
+    app = web.Application(client_max_size=sys.maxsize)
     app[CAPTURE_TOKEN_KEY] = capture_token
     app[AVATAR_SETS_KEY] = {}
     app[AVATAR_SETS_LOCK_KEY] = asyncio.Lock()

{stackchan_mcp-0.13.0 → stackchan_mcp-0.14.0}/stackchan_mcp/cli.py

@@ -438,9 +438,20 @@ def _run_ownership_check() -> int:
     """Print the current ownership lock status and exit cleanly."""
     from .ownership import is_pid_alive, read_lock
 
-    info = read_lock()
+    # Load ``.env`` first so that a WS_PORT / PORT defined only there resolves
+    # the same per-port lock the running gateway claims. Startup loads ``.env``
+    # before ``_acquire_startup_lock`` (via ``_run_stdio_gateway`` /
+    # ``_run_streamable_http_placeholder``), so ``--check`` must match it —
+    # otherwise a gateway owning ``owner-18765.lock`` would be inspected against
+    # the default ``owner-8765.lock`` and wrongly reported ready. Mirrors how
+    # ``--preflight`` loads ``.env`` inside ``_run_preflight``.
+    _load_dotenv()
+    # Inspect the per-WS_PORT lock this gateway would claim (not the legacy
+    # machine-global owner.lock), so the preflight reflects the actual port.
+    lock_path = _ws_port_lock_path()
+    info = read_lock(lock_path)
     if info is None:
-        print("no current owner")
+        print(f"no current owner (lock: {lock_path.name})")
         print("ownership preflight: ready")
         print("Result: ready. Exit 0.")
     elif is_pid_alive(info["pid"]):
@@ -750,6 +761,24 @@ def _configure_gateway_startup() -> None:
     log_user_defaults_startup()
 
 
+def _ws_port_lock_path():
+    """Per-WS_PORT ownership lock path.
+
+    複数機体対応: ownership lock を machine-global な ``owner.lock`` でなく
+    WS_PORT 単位に scope する。 lock は「同一 device を 2 つの gateway が
+    奪い合わない」 ための機構だが、 1 device = 1 gateway = 1 WS ポートで
+    複数機体を同時に動かす構成では global lock が 2 台目以降を誤って弾く。
+    ポート単位なら N gateway が共存でき、 同一ポート二重起動は従来通り弾ける。
+    WS_PORT 未解決時は従来の global パスにフォールバック。
+    """
+    from .ownership import LOCK_DIR
+
+    ws_port, _ = _resolve_ws_port()
+    return LOCK_DIR / (
+        f"owner-{ws_port}.lock" if ws_port is not None else "owner.lock"
+    )
+
+
 def _acquire_startup_lock(
     *,
     mode: "LockMode" = _STDIO_TRANSPORT,
@@ -764,13 +793,16 @@ def _acquire_startup_lock(
         release_lock_if_owner,
     )
 
+    lock_path = _ws_port_lock_path()
+
     owner_id = generate_owner_id()
     try:
         if mode == _STDIO_TRANSPORT and http_endpoint is None and started_by is None:
-            info = acquire_lock(owner_id)
+            info = acquire_lock(owner_id, path=lock_path)
         else:
             info = acquire_lock(
                 owner_id,
+                path=lock_path,
                 mode=mode,
                 http_endpoint=http_endpoint,
                 started_by=started_by,
@@ -782,12 +814,13 @@ def _acquire_startup_lock(
     try:
         print(
             "stackchan-mcp: acquired ownership lock "
-            f"(owner_id={info['owner_id']}, pid={info['pid']})",
+            f"(owner_id={info['owner_id']}, pid={info['pid']}, "
+            f"lock={lock_path.name})",
             file=sys.stderr,
         )
-        atexit.register(release_lock_if_owner, info)
+        atexit.register(release_lock_if_owner, info, lock_path)
     except BaseException:
-        release_lock_if_owner(info)
+        release_lock_if_owner(info, lock_path)
         raise
 
     return info
@@ -810,7 +843,7 @@ def _run_stdio_gateway(*, advertise_mdns: bool = True) -> None:
         except KeyboardInterrupt:
             pass
     finally:
-        release_lock_if_owner(info)
+        release_lock_if_owner(info, _ws_port_lock_path())
 
 
 def _resolve_mcp_http_endpoint() -> tuple[str, int]:
@@ -920,7 +953,7 @@ def _run_streamable_http_placeholder(*, advertise_mdns: bool = True) -> None:
             pass
     finally:
         if info is not None:
-            release_lock_if_owner(info)
+            release_lock_if_owner(info, _ws_port_lock_path())
 
 
 def main(argv: list[str] | None = None) -> None:

{stackchan_mcp-0.13.0 → stackchan_mcp-0.14.0}/stackchan_mcp/esp32_client.py

@@ -43,6 +43,8 @@ RESPONSE_TIMEOUT = 10.0
 ToolCall = tuple[str, dict[str, Any]]
 ToolCallResult = tuple[Any, dict[str, Any] | None]
 
+_SET_AVATAR_TOOL = "self.display.set_avatar"
+
 _TOOL_LANES = {
     "self.robot.": "servo",
     "self.wifi.": "wifi",
@@ -82,6 +84,8 @@ class ESP32Connection:
         self._pending: dict[int, asyncio.Future[dict[str, Any]]] = {}
         self._connected = True
         self._initialized = False
+        self._tools_discovered = False
+        self._avatar_render_sent = False
         # Phase 4.5 avatar: pending load_avatar_set calls waiting for the
         # device's `avatar_set_loaded` reply. Keyed by expected checksum
         # so that overlapping fetches (different sets) can be discriminated.
@@ -102,6 +106,14 @@ class ESP32Connection:
     def initialized(self) -> bool:
         return self._initialized
 
+    @property
+    def tools_discovered(self) -> bool:
+        return self._tools_discovered
+
+    @property
+    def avatar_render_sent(self) -> bool:
+        return self._avatar_render_sent
+
     def _next_id(self) -> int:
         self._request_id += 1
         return self._request_id
@@ -162,6 +174,8 @@ class ESP32Connection:
         """Discover tools available on ESP32."""
         all_tools: list[dict[str, Any]] = []
         cursor = ""
+        self._tools_discovered = False
+        discovered = False
 
         while True:
             params: dict[str, Any] = {"cursor": cursor}
@@ -169,6 +183,7 @@ class ESP32Connection:
 
             if error:
                 logger.error("tools/list failed: %s", error)
+                self.tools = all_tools
                 break
 
             tools = result.get("tools", [])
@@ -176,10 +191,12 @@ class ESP32Connection:
 
             next_cursor = result.get("nextCursor", "")
             if not next_cursor:
+                discovered = True
                 break
             cursor = next_cursor
 
         self.tools = all_tools
+        self._tools_discovered = discovered
         logger.info("Discovered %d tools on ESP32", len(all_tools))
         return all_tools
 
@@ -187,6 +204,8 @@ class ESP32Connection:
         self, name: str, arguments: dict[str, Any]
     ) -> tuple[Any, dict[str, Any] | None]:
         """Call a tool on ESP32."""
+        if name == _SET_AVATAR_TOOL:
+            self._avatar_render_sent = True
         return await self.send_mcp_request(
             "tools/call", {"name": name, "arguments": arguments}
         )
@@ -233,6 +252,9 @@ class ESP32Connection:
             return {"ok": False, "checksum": checksum, "error": "device_timeout"}
         except asyncio.CancelledError:
             return {"ok": False, "checksum": checksum, "error": "superseded"}
+        except ConnectionError:
+            self._avatar_set_waiters.pop(checksum, None)
+            return {"ok": False, "checksum": checksum, "error": "disconnected"}
         except Exception as exc:
             self._avatar_set_waiters.pop(checksum, None)
             return {"ok": False, "checksum": checksum, "error": f"send_failed: {exc}"}
@@ -353,6 +375,10 @@ class ESP32Connection:
             if not future.done():
                 future.set_exception(ConnectionError("ESP32 disconnected"))
         self._pending.clear()
+        for future in self._avatar_set_waiters.values():
+            if not future.done():
+                future.set_exception(ConnectionError("ESP32 disconnected"))
+        self._avatar_set_waiters.clear()
 
 
 class ESP32Manager:
@@ -732,6 +758,10 @@ class ESP32Manager:
             vision_token=self._vision_token,
         ):
             await connection.discover_tools()
+            if not connection.tools_discovered:
+                logger.error("ESP32 tools discovery failed")
+                return
+            await self._auto_render_idle_avatar(connection, device_id)
             logger.info(
                 "ESP32 ready: device=%s tools=%d",
                 device_id,
@@ -740,6 +770,37 @@ class ESP32Manager:
         else:
             logger.error("ESP32 MCP initialization failed")
 
+    async def _auto_render_idle_avatar(
+        self, connection: ESP32Connection, device_id: str
+    ) -> None:
+        """Best-effort idle avatar render after a fresh device session init."""
+        if connection.avatar_render_sent:
+            return
+
+        logger.info(
+            "auto-rendering idle avatar (no explicit set_avatar yet): device=%s",
+            device_id,
+        )
+        try:
+            _result, error = await connection.call_tool(
+                _SET_AVATAR_TOOL,
+                {"face": "idle"},
+            )
+        except Exception as exc:
+            logger.warning(
+                "auto-rendering idle avatar failed: device=%s error=%s",
+                device_id,
+                exc,
+            )
+            return
+
+        if error:
+            logger.warning(
+                "auto-rendering idle avatar failed: device=%s error=%s",
+                device_id,
+                error,
+            )
+
     async def _emit_stackchan_event(self, payload: dict[str, Any]) -> None:
         """Forward a firmware-originated stackchan event to the MCP client."""
         event_type = payload.get("event_type")

{stackchan_mcp-0.13.0 → stackchan_mcp-0.14.0}/tests/test_capture_server.py

@@ -199,3 +199,72 @@ async def test_pcm_no_auth_allows_unauthed_request_when_token_blank():
     # We don't auth-reject (would be 401); the next guard (sample-rate)
     # fires first, so 400 here means auth was skipped as intended.
     assert response.status == 400
+
+
+# ---------------------------------------------------------------------------
+# /capture endpoint — multipart body-cap regression
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_capture_accepts_nonempty_question_field(tmp_path, monkeypatch):
+    """A non-empty multipart ``question`` field must not be rejected with 413.
+
+    Regression guard. The capture app raises aiohttp's per-request body cap so
+    /pcm can stream long PCM. It must NOT do so by setting ``client_max_size=0``:
+    aiohttp's multipart reader (>= 3.14) checks ``len(data) > client_max_size``
+    directly and, unlike ``request.read()`` / ``request.post()``, does not treat
+    ``0`` as "unlimited". With ``client_max_size=0`` every /capture upload that
+    carries a non-empty ``question`` form field (read via ``part.read()``) fails
+    with HTTP 413, surfacing on the device as "Failed to upload photo". A large
+    finite cap keeps /pcm unbounded while letting normal uploads through.
+    """
+    import aiohttp
+    from aiohttp.test_utils import TestClient, TestServer
+
+    from stackchan_mcp import capture_server
+
+    monkeypatch.setattr(capture_server, "CAPTURE_DIR", str(tmp_path))
+    app = create_capture_app(capture_token="")  # blank token → auth skipped
+
+    async with TestClient(TestServer(app)) as client:
+        form = aiohttp.FormData()
+        form.add_field("question", "what is in front of you?")
+        form.add_field(
+            "file",
+            b"\xff\xd8\xff\xe0JFIF-dummy-jpeg-bytes",
+            filename="photo.jpg",
+            content_type="image/jpeg",
+        )
+        resp = await client.post("/capture", data=form)
+        assert resp.status == 200, await resp.text()
+
+
+@pytest.mark.asyncio
+async def test_capture_tolerates_non_utf8_question(tmp_path, monkeypatch):
+    """A malformed (non-UTF-8) question field must not 500 the upload.
+
+    The question is advisory metadata; a client that sends it in the wrong
+    encoding should still get its photo stored (decoded with errors=replace)
+    rather than a 500 that looks to the device like a failed capture.
+    """
+    import aiohttp
+    from aiohttp.test_utils import TestClient, TestServer
+
+    from stackchan_mcp import capture_server
+
+    monkeypatch.setattr(capture_server, "CAPTURE_DIR", str(tmp_path))
+    app = create_capture_app(capture_token="")
+
+    async with TestClient(TestServer(app)) as client:
+        with aiohttp.MultipartWriter("form-data") as mpwriter:
+            # Raw non-UTF-8 bytes (0x96 is a Shift-JIS lead byte, an invalid
+            # UTF-8 start byte) in the question part.
+            part = mpwriter.append(b"\x96\x96\x96")
+            part.set_content_disposition("form-data", name="question")
+            fpart = mpwriter.append(b"\xff\xd8\xff\xe0JFIF-dummy")
+            fpart.set_content_disposition(
+                "form-data", name="file", filename="photo.jpg"
+            )
+            resp = await client.post("/capture", data=mpwriter)
+        assert resp.status == 200, await resp.text()

{stackchan_mcp-0.13.0 → stackchan_mcp-0.14.0}/tests/test_cli.py

@@ -189,7 +189,7 @@ def test_main_default_advertises_mdns(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setattr(cli, "_load_dotenv", lambda: None)
     monkeypatch.setattr(cli, "_ensure_libopus_findable", lambda: None)
     monkeypatch.setattr(cli, "_run", fake_run)
-    monkeypatch.setattr(ownership, "release_lock_if_owner", lambda info: True)
+    monkeypatch.setattr(ownership, "release_lock_if_owner", lambda info, path=None: True)
 
     main([])
 
@@ -210,7 +210,7 @@ def test_main_no_mdns_disables_advertisement(
     monkeypatch.setattr(cli, "_load_dotenv", lambda: None)
     monkeypatch.setattr(cli, "_ensure_libopus_findable", lambda: None)
     monkeypatch.setattr(cli, "_run", fake_run)
-    monkeypatch.setattr(ownership, "release_lock_if_owner", lambda info: True)
+    monkeypatch.setattr(ownership, "release_lock_if_owner", lambda info, path=None: True)
 
     main(["--no-mdns"])
 
@@ -325,7 +325,11 @@ def test_main_check_flag_remains_side_effect_free_with_no_mdns(
     async def fail_run(*, advertise_mdns: bool = True) -> None:
         raise AssertionError("--check must not start the gateway")
 
-    monkeypatch.setattr(cli, "_run_preflight", lambda: 0)
+    # ``--check`` runs ``_run_ownership_check()``, which calls ``_load_dotenv()``.
+    # Without stubbing it, the developer's real ``gateway/.env`` is loaded into
+    # ``os.environ`` outside monkeypatch's tracking and never restored, polluting
+    # later tests (e.g. a ``STACKCHAN_TOKEN`` there breaks the WS-server suite).
+    monkeypatch.setattr(cli, "_load_dotenv", lambda: None)
     monkeypatch.setattr(cli, "_run", fail_run)
 
     with pytest.raises(SystemExit) as exc:
@@ -385,7 +389,9 @@ def test_streamable_http_releases_lock_after_daemon_exit(
     monkeypatch.setattr(cli, "_configure_gateway_startup", lambda: None)
     monkeypatch.setattr(cli, "_acquire_startup_lock", fake_acquire)
     monkeypatch.setattr(cli, "_run_streamable_http_daemon", fake_daemon)
-    monkeypatch.setattr(ownership, "release_lock_if_owner", released.append)
+    monkeypatch.setattr(
+        ownership, "release_lock_if_owner", lambda info, path=None: released.append(info)
+    )
     monkeypatch.delenv("MCP_HTTP_HOST", raising=False)
     monkeypatch.delenv("MCP_HTTP_PORT", raising=False)
     monkeypatch.delenv("STACKCHAN_TOKEN", raising=False)
@@ -752,7 +758,7 @@ def test_main_check_flag_runs_ownership_check_and_exits(
 
     _isolate_preflight_env(monkeypatch, tmp_path)
     monkeypatch.setattr(cli, "_run_preflight", lambda: 99)
-    monkeypatch.setattr(ownership, "read_lock", lambda: None)
+    monkeypatch.setattr(ownership, "read_lock", lambda path=None: None)
 
     with pytest.raises(SystemExit) as exc:
         main(["--check"])
@@ -762,6 +768,67 @@ def test_main_check_flag_runs_ownership_check_and_exits(
     assert "Result: ready" in out
 
 
+def test_main_check_flag_inspects_per_ws_port_lock(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    tmp_path: Path,
+) -> None:
+    """``--check`` inspects the lock for the configured WS_PORT.
+
+    Guards against the ``--check`` preflight reading the default
+    ``owner-8765.lock`` while a gateway configured for another port owns
+    ``owner-<port>.lock``. ``_run_ownership_check`` loads ``.env`` before
+    deriving the lock path, mirroring the startup order, so a WS_PORT set in
+    the environment (or ``.env``) is reflected here.
+    """
+    from stackchan_mcp import ownership
+
+    _isolate_preflight_env(monkeypatch, tmp_path)
+    monkeypatch.setenv("WS_PORT", "18765")
+    seen: list[Path] = []
+
+    def fake_read_lock(path: Path | None = None) -> None:
+        seen.append(path)
+        return None
+
+    monkeypatch.setattr(ownership, "read_lock", fake_read_lock)
+
+    with pytest.raises(SystemExit) as exc:
+        main(["--check"])
+    assert exc.value.code == 0
+    assert seen and seen[0] is not None and seen[0].name == "owner-18765.lock"
+    assert "owner-18765.lock" in capsys.readouterr().out
+
+
+def test_main_check_flag_scopes_lock_for_ephemeral_ws_port(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    tmp_path: Path,
+) -> None:
+    """``WS_PORT=0`` scopes the lock to ``owner-0.lock``, not the legacy path.
+
+    Preflight treats ``0`` as a valid (OS-assigned ephemeral) port, so the
+    ownership lock must stay per-port for it too. A truthiness check would send
+    ``0`` to the machine-global ``owner.lock`` and diverge from startup.
+    """
+    from stackchan_mcp import ownership
+
+    _isolate_preflight_env(monkeypatch, tmp_path)
+    monkeypatch.setenv("WS_PORT", "0")
+    seen: list[Path] = []
+
+    def fake_read_lock(path: Path | None = None) -> None:
+        seen.append(path)
+        return None
+
+    monkeypatch.setattr(ownership, "read_lock", fake_read_lock)
+
+    with pytest.raises(SystemExit) as exc:
+        main(["--check"])
+    assert exc.value.code == 0
+    assert seen and seen[0] is not None and seen[0].name == "owner-0.lock"
+
+
 def test_main_preflight_flag_runs_preflight_and_exits(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:

{stackchan_mcp-0.13.0 → stackchan_mcp-0.14.0}/tests/test_esp32_client.py

@@ -3,6 +3,7 @@
 import asyncio
 import gc
 import json
+import logging
 
 import pytest
 import pytest_asyncio
@@ -132,6 +133,13 @@ async def test_esp32_hello_handshake(manager):
         }
         await ws.send(json.dumps(tools_resp))
 
+        auto_msg = await _expect_auto_idle_avatar(ws)
+        await _send_mcp_response(
+            ws,
+            auto_msg,
+            result={"content": [{"type": "text", "text": "true"}], "isError": False},
+        )
+
         # Wait for manager to process
         await asyncio.sleep(0.2)
 
@@ -318,6 +326,265 @@ async def test_connection_removes_pending_request_when_call_is_cancelled():
     assert conn._pending == {}
 
 
+# ---------------------------------------------------------------------------
+# Auto idle avatar render after session initialization (Issue #77)
+# ---------------------------------------------------------------------------
+
+
+class _InitDeviceConnection:
+    """Fake connection for exercising ESP32Manager._init_device."""
+
+    def __init__(
+        self,
+        *,
+        avatar_render_sent: bool = False,
+        discover_ok: bool = True,
+        auto_error: dict | None = None,
+        auto_exception: Exception | None = None,
+    ) -> None:
+        self.tools: list[dict] = []
+        self.tools_discovered = False
+        self.avatar_render_sent = avatar_render_sent
+        self.discover_ok = discover_ok
+        self.auto_error = auto_error
+        self.auto_exception = auto_exception
+        self.initialize_calls = 0
+        self.discover_calls = 0
+        self.call_tool_calls: list[tuple[str, dict]] = []
+
+    async def initialize(self, *, vision_url: str = "", vision_token: str = "") -> bool:
+        self.initialize_calls += 1
+        return True
+
+    async def discover_tools(self) -> list[dict]:
+        self.discover_calls += 1
+        if not self.discover_ok:
+            self.tools = []
+            self.tools_discovered = False
+            return self.tools
+
+        self.tools = [
+            {
+                "name": "self.display.set_avatar",
+                "description": "Set avatar",
+                "inputSchema": {"type": "object"},
+            }
+        ]
+        self.tools_discovered = True
+        return self.tools
+
+    async def call_tool(self, name: str, arguments: dict):
+        self.call_tool_calls.append((name, arguments))
+        if name == "self.display.set_avatar":
+            self.avatar_render_sent = True
+        if self.auto_exception is not None:
+            raise self.auto_exception
+        return {"content": [{"type": "text", "text": "true"}]}, self.auto_error
+
+
+class _AutoMcpWebSocket:
+    """Fake WebSocket that responds to gateway MCP requests immediately."""
+
+    def __init__(self) -> None:
+        self.connection: ESP32Connection | None = None
+        self.sent: list[str] = []
+        self.tool_calls: list[tuple[str, dict]] = []
+
+    async def send(self, data: str) -> None:
+        self.sent.append(data)
+        message = json.loads(data)
+        payload = message["payload"]
+        method = payload["method"]
+
+        if method == "initialize":
+            result = {
+                "protocolVersion": "2024-11-05",
+                "capabilities": {"tools": {}},
+                "serverInfo": {"name": "test-device", "version": "1.0.0"},
+            }
+        elif method == "tools/list":
+            result = {
+                "tools": [
+                    {
+                        "name": "self.display.set_avatar",
+                        "description": "Set avatar",
+                        "inputSchema": {"type": "object"},
+                    }
+                ],
+                "nextCursor": "",
+            }
+        elif method == "tools/call":
+            params = payload["params"]
+            self.tool_calls.append((params["name"], params["arguments"]))
+            result = {"content": [{"type": "text", "text": "true"}], "isError": False}
+        else:
+            raise AssertionError(f"unexpected MCP method: {method}")
+
+        assert self.connection is not None
+        self.connection.handle_response(
+            {"jsonrpc": "2.0", "id": payload["id"], "result": result}
+        )
+
+
+@pytest.mark.asyncio
+async def test_init_auto_renders_idle_avatar_after_tools_list():
+    """A successful initialize + tools/list sends idle set_avatar once."""
+    ws = _AutoMcpWebSocket()
+    connection = ESP32Connection(ws, session_id="session-auto")  # type: ignore[arg-type]
+    ws.connection = connection
+    mgr = ESP32Manager()
+
+    await mgr._init_device(connection, "device-test")
+
+    assert ws.tool_calls == [("self.display.set_avatar", {"face": "idle"})]
+    assert connection.avatar_render_sent is True
+
+
+@pytest.mark.asyncio
+async def test_init_skips_auto_idle_avatar_when_avatar_already_sent():
+    """The connection-scoped flag suppresses the automatic idle render."""
+    mgr = ESP32Manager()
+    connection = _InitDeviceConnection(avatar_render_sent=True)
+
+    await mgr._init_device(connection, "device-test")  # type: ignore[arg-type]
+
+    assert connection.initialize_calls == 1
+    assert connection.discover_calls == 1
+    assert connection.call_tool_calls == []
+
+
+@pytest.mark.asyncio
+async def test_init_skips_auto_idle_avatar_when_tools_discovery_fails(caplog):
+    """The auto-render path only runs after successful tools/list discovery."""
+    caplog.set_level(logging.INFO, logger="stackchan_mcp.esp32_client")
+    mgr = ESP32Manager()
+    connection = _InitDeviceConnection(discover_ok=False)
+
+    await mgr._init_device(connection, "device-test")  # type: ignore[arg-type]
+
+    assert connection.initialize_calls == 1
+    assert connection.discover_calls == 1
+    assert connection.call_tool_calls == []
+    assert "ESP32 ready: device=device-test" not in caplog.text
+
+
+@pytest.mark.parametrize("failure_mode", ["error", "timeout"])
+@pytest.mark.asyncio
+async def test_init_continues_when_auto_idle_avatar_fails(failure_mode, caplog):
+    """Auto-render failures are warnings and do not block ESP32 ready."""
+    caplog.set_level(logging.INFO, logger="stackchan_mcp.esp32_client")
+    if failure_mode == "error":
+        connection = _InitDeviceConnection(
+            auto_error={"code": -32000, "message": "device rejected set_avatar"}
+        )
+    else:
+        connection = _InitDeviceConnection(
+            auto_exception=asyncio.TimeoutError("set_avatar timed out")
+        )
+    mgr = ESP32Manager()
+
+    await mgr._init_device(connection, "device-test")  # type: ignore[arg-type]
+
+    assert connection.call_tool_calls == [
+        ("self.display.set_avatar", {"face": "idle"})
+    ]
+    assert "auto-rendering idle avatar failed" in caplog.text
+    assert "ESP32 ready: device=device-test tools=1" in caplog.text
+
+
+@pytest.mark.asyncio
+async def test_reconnect_auto_renders_idle_avatar_again():
+    """A new ESP32Connection gets a fresh auto-render flag."""
+    first_ws = _AutoMcpWebSocket()
+    first = ESP32Connection(first_ws, session_id="session-first")  # type: ignore[arg-type]
+    first_ws.connection = first
+    second_ws = _AutoMcpWebSocket()
+    second = ESP32Connection(second_ws, session_id="session-second")  # type: ignore[arg-type]
+    second_ws.connection = second
+    mgr = ESP32Manager()
+
+    await mgr._init_device(first, "device-test")
+    await mgr._init_device(second, "device-test")
+
+    assert first_ws.tool_calls == [("self.display.set_avatar", {"face": "idle"})]
+    assert second_ws.tool_calls == [("self.display.set_avatar", {"face": "idle"})]
+
+
+@pytest.mark.asyncio
+async def test_send_avatar_set_fetch_resolves_when_loaded_event_arrives():
+    """avatar_set_loaded resolves the matching load_avatar_set waiter."""
+    ws = _FakeWebSocket()
+    conn = ESP32Connection(ws, session_id="session-avatar")  # type: ignore[arg-type]
+
+    task = asyncio.create_task(
+        conn.send_avatar_set_fetch(
+            url="https://example.invalid/avatar-set.bin",
+            token="test-token",
+            mode="replace",
+            checksum="sha256:avatar-set",
+            expected_size=1234,
+            timeout=30.0,
+        )
+    )
+
+    await asyncio.sleep(0)
+    assert len(ws.sent) == 1
+    assert json.loads(ws.sent[0]) == {
+        "type": "avatar_set_fetch",
+        "url": "https://example.invalid/avatar-set.bin",
+        "token": "test-token",
+        "mode": "replace",
+        "checksum": "sha256:avatar-set",
+        "expected_size": 1234,
+    }
+
+    payload = {
+        "ok": True,
+        "checksum": "sha256:avatar-set",
+        "bytes": 1234,
+    }
+    conn.handle_avatar_set_loaded(payload)
+
+    result = await asyncio.wait_for(task, timeout=1.0)
+    assert result == payload
+    assert conn._avatar_set_waiters == {}
+
+
+@pytest.mark.asyncio
+async def test_send_avatar_set_fetch_returns_disconnected_when_connection_drops():
+    """Disconnect wakes an in-flight avatar set fetch without waiting for timeout."""
+    ws = _FakeWebSocket()
+    conn = ESP32Connection(ws, session_id="session-avatar")  # type: ignore[arg-type]
+
+    task = asyncio.create_task(
+        conn.send_avatar_set_fetch(
+            url="https://example.invalid/avatar-set.bin",
+            token="test-token",
+            mode="replace",
+            checksum="sha256:avatar-set",
+            expected_size=1234,
+            timeout=30.0,
+        )
+    )
+
+    await asyncio.sleep(0)
+    assert len(ws.sent) == 1
+    assert len(conn._avatar_set_waiters) == 1
+
+    started_at = asyncio.get_running_loop().time()
+    conn.disconnect()
+    result = await asyncio.wait_for(task, timeout=1.0)
+    elapsed = asyncio.get_running_loop().time() - started_at
+
+    assert result == {
+        "ok": False,
+        "checksum": "sha256:avatar-set",
+        "error": "disconnected",
+    }
+    assert elapsed < 1.0
+    assert conn._avatar_set_waiters == {}
+
+
 class _GateableConnection:
     """Fake initialized connection with per-tool release gates."""
 
@@ -726,7 +993,7 @@ def test_connection_default_protocol_version_is_one():
 # ---------------------------------------------------------------------------
 
 
-async def _complete_handshake(ws, tools=None):
+async def _complete_handshake(ws, tools=None, *, consume_auto_avatar=True):
     """Complete the full ESP32 handshake sequence."""
     if tools is None:
         tools = []
@@ -774,6 +1041,49 @@ async def _complete_handshake(ws, tools=None):
         },
     }
     await ws.send(json.dumps(tools_resp))
+    if not consume_auto_avatar:
+        return None
+
+    auto_msg = await _expect_auto_idle_avatar(ws)
+    await _send_mcp_response(
+        ws,
+        auto_msg,
+        result={"content": [{"type": "text", "text": "true"}], "isError": False},
+    )
+    return auto_msg
+
+
+async def _expect_auto_idle_avatar(ws):
+    """Receive and assert the automatic idle avatar tools/call."""
+    auto_raw = await asyncio.wait_for(ws.recv(), timeout=5.0)
+    auto_msg = json.loads(auto_raw)
+    assert auto_msg["type"] == "mcp"
+    assert auto_msg["payload"]["method"] == "tools/call"
+    assert auto_msg["payload"]["params"]["name"] == "self.display.set_avatar"
+    assert auto_msg["payload"]["params"]["arguments"] == {"face": "idle"}
+    return auto_msg
+
+
+async def _send_mcp_response(ws, req_msg, *, result=None, error=None):
+    """Send a JSON-RPC response for a gateway-originated MCP request."""
+    payload = {
+        "jsonrpc": "2.0",
+        "id": req_msg["payload"]["id"],
+    }
+    if error is None:
+        payload["result"] = result or {}
+    else:
+        payload["error"] = error
+
+    await ws.send(
+        json.dumps(
+            {
+                "session_id": req_msg["session_id"],
+                "type": "mcp",
+                "payload": payload,
+            }
+        )
+    )
 
 
 # --- Device-driven listen capture --------------------------------------------
@@ -932,4 +1242,3 @@ async def test_device_driven_listen_cleanup_on_disconnect(manager_with_hook):
     assert not is_recording(), "recording slot was leaked across connections"
     # No push should have fired for the aborted capture.
     assert calls == []
-

{stackchan_mcp-0.13.0 → stackchan_mcp-0.14.0}/uv.lock

@@ -2068,7 +2068,7 @@ wheels = [
 
 [[package]]
 name = "stackchan-mcp"
-version = "0.13.0"
+version = "0.14.0"
 source = { editable = "." }
 dependencies = [
     { name = "aiohttp" },