astropods-adapter-core 0.1.0__tar.gz

astropods_adapter_core-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.egg-info/
+.venv/
+dist/

astropods_adapter_core-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: astropods-adapter-core
+Version: 0.1.0
+Summary: Framework-agnostic bridge between agent adapters and the Astropods messaging service
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: astropods-messaging>=0.0.4
+Requires-Dist: grpcio>=1.62
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# astropods-adapter-core
+
+Framework-agnostic bridge between Python agents and the Astropods messaging service.
+
+## Installation
+
+```bash
+pip install astropods-adapter-core
+```
+
+Requires Python 3.10+.
+
+## Usage
+
+If you're using a supported framework, use the pre-built adapter package instead (e.g. `astropods-adapter-langchain`). Use this package directly to connect a custom or unsupported framework.
+
+Create a class with `name`, `stream`, and `get_config`, then call `serve()`:
+
+```python
+from astropods_adapter_core import StreamHooks, StreamOptions, serve
+
+class MyAdapter:
+    name = "My Agent"
+
+    async def stream(self, prompt: str, hooks: StreamHooks, options: StreamOptions) -> None:
+        try:
+            hooks.on_chunk("Hello!")
+            hooks.on_finish()
+        except Exception as e:
+            hooks.on_error(e)
+
+    def get_config(self) -> dict:
+        return {"system_prompt": "You are a helpful assistant.", "tools": []}
+
+serve(MyAdapter())
+```
+
+`serve()` blocks until `SIGINT` or `SIGTERM`. Under `ast dev`, `GRPC_SERVER_ADDR` is injected automatically.
+
+## API
+
+### `AgentAdapter` protocol
+
+| Member | Description |
+|--------|-------------|
+| `name: str` | Display name used in logs and registration |
+| `async stream(prompt, hooks, options)` | Stream a response, invoking hooks as the agent progresses |
+| `get_config() -> dict` | Return `{"system_prompt": str, "tools": [...]}` for playground display |
+
+### `StreamHooks`
+
+Call these inside `stream()` as the agent produces output:
+
+| Method | When to call |
+|--------|-------------|
+| `on_chunk(text)` | Each text token or fragment from the LLM |
+| `on_status_update({"status": "..."})` | Agent state change — valid values: `THINKING`, `SEARCHING`, `GENERATING`, `PROCESSING`, `ANALYZING`, `CUSTOM` |
+| `on_finish()` | Response complete — call exactly once per request |
+| `on_error(exception)` | Error occurred — call instead of `on_finish` |
+
+For `CUSTOM` status, include `"custom_message"` in the dict:
+
+```python
+hooks.on_status_update({"status": "CUSTOM", "custom_message": "Fetching data..."})
+```
+
+### `StreamOptions`
+
+Per-request context passed to `stream()`:
+
+| Field | Description |
+|-------|-------------|
+| `conversation_id` | Stable ID for the conversation thread |
+| `user_id` | ID of the user who sent the message |
+
+### `serve(adapter, options?)`
+
+Connects the adapter to the messaging service and blocks until shutdown.
+
+```python
+from astropods_adapter_core import ServeOptions, serve
+
+# Override the gRPC address (default: GRPC_SERVER_ADDR env var or localhost:9090)
+serve(adapter, ServeOptions(server_address="astro-messaging:9090"))
+```
+
+### `MessagingBridge`
+
+`serve()` is a thin wrapper around `MessagingBridge`. Use it directly if you need lifecycle control:
+
+```python
+import asyncio
+from astropods_adapter_core import MessagingBridge
+
+bridge = MessagingBridge(adapter)
+asyncio.run(bridge.start())
+```

astropods_adapter_core-0.1.0/README.md

@@ -0,0 +1,97 @@
+# astropods-adapter-core
+
+Framework-agnostic bridge between Python agents and the Astropods messaging service.
+
+## Installation
+
+```bash
+pip install astropods-adapter-core
+```
+
+Requires Python 3.10+.
+
+## Usage
+
+If you're using a supported framework, use the pre-built adapter package instead (e.g. `astropods-adapter-langchain`). Use this package directly to connect a custom or unsupported framework.
+
+Create a class with `name`, `stream`, and `get_config`, then call `serve()`:
+
+```python
+from astropods_adapter_core import StreamHooks, StreamOptions, serve
+
+class MyAdapter:
+    name = "My Agent"
+
+    async def stream(self, prompt: str, hooks: StreamHooks, options: StreamOptions) -> None:
+        try:
+            hooks.on_chunk("Hello!")
+            hooks.on_finish()
+        except Exception as e:
+            hooks.on_error(e)
+
+    def get_config(self) -> dict:
+        return {"system_prompt": "You are a helpful assistant.", "tools": []}
+
+serve(MyAdapter())
+```
+
+`serve()` blocks until `SIGINT` or `SIGTERM`. Under `ast dev`, `GRPC_SERVER_ADDR` is injected automatically.
+
+## API
+
+### `AgentAdapter` protocol
+
+| Member | Description |
+|--------|-------------|
+| `name: str` | Display name used in logs and registration |
+| `async stream(prompt, hooks, options)` | Stream a response, invoking hooks as the agent progresses |
+| `get_config() -> dict` | Return `{"system_prompt": str, "tools": [...]}` for playground display |
+
+### `StreamHooks`
+
+Call these inside `stream()` as the agent produces output:
+
+| Method | When to call |
+|--------|-------------|
+| `on_chunk(text)` | Each text token or fragment from the LLM |
+| `on_status_update({"status": "..."})` | Agent state change — valid values: `THINKING`, `SEARCHING`, `GENERATING`, `PROCESSING`, `ANALYZING`, `CUSTOM` |
+| `on_finish()` | Response complete — call exactly once per request |
+| `on_error(exception)` | Error occurred — call instead of `on_finish` |
+
+For `CUSTOM` status, include `"custom_message"` in the dict:
+
+```python
+hooks.on_status_update({"status": "CUSTOM", "custom_message": "Fetching data..."})
+```
+
+### `StreamOptions`
+
+Per-request context passed to `stream()`:
+
+| Field | Description |
+|-------|-------------|
+| `conversation_id` | Stable ID for the conversation thread |
+| `user_id` | ID of the user who sent the message |
+
+### `serve(adapter, options?)`
+
+Connects the adapter to the messaging service and blocks until shutdown.
+
+```python
+from astropods_adapter_core import ServeOptions, serve
+
+# Override the gRPC address (default: GRPC_SERVER_ADDR env var or localhost:9090)
+serve(adapter, ServeOptions(server_address="astro-messaging:9090"))
+```
+
+### `MessagingBridge`
+
+`serve()` is a thin wrapper around `MessagingBridge`. Use it directly if you need lifecycle control:
+
+```python
+import asyncio
+from astropods_adapter_core import MessagingBridge
+
+bridge = MessagingBridge(adapter)
+asyncio.run(bridge.start())
+```

astropods_adapter_core-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "astropods-adapter-core"
+version = "0.1.0"
+description = "Framework-agnostic bridge between agent adapters and the Astropods messaging service"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+dependencies = [
+  "astropods-messaging>=0.0.4",
+  "grpcio>=1.62",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/astropods_adapter_core"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

astropods_adapter_core-0.1.0/src/astropods_adapter_core/__init__.py

@@ -0,0 +1,12 @@
+from .types import AgentAdapter, StreamHooks, StreamOptions, ServeOptions
+from .bridge import MessagingBridge
+from .serve import serve
+
+__all__ = [
+    "AgentAdapter",
+    "StreamHooks",
+    "StreamOptions",
+    "ServeOptions",
+    "MessagingBridge",
+    "serve",
+]

astropods_adapter_core-0.1.0/src/astropods_adapter_core/bridge.py

@@ -0,0 +1,304 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import signal
+from typing import Optional
+
+import grpc
+import grpc.aio
+
+from astropods_messaging import (
+    AgentMessagingStub,
+    AgentConfig,
+    AgentToolConfig,
+    AgentResponse,
+    ContentChunk,
+    ConversationRequest,
+    ErrorResponse,
+    HealthCheckRequest,
+    Message,
+    StatusUpdate,
+    User,
+)
+
+from .types import AgentAdapter, ServeOptions, StreamHooks, StreamOptions
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_SERVER_ADDR = "localhost:9090"
+MAX_RETRIES = 10
+INITIAL_DELAY_MS = 500
+MAX_DELAY_MS = 15000
+
+
+def _debug(*args: object) -> None:
+    if os.environ.get("DEBUG"):
+        logger.debug(*args)
+
+
+class _StreamHooksImpl:
+    """Concrete StreamHooks that enqueues gRPC messages for the writer task."""
+
+    def __init__(self, conversation_id: str, write_queue: asyncio.Queue) -> None:
+        self._conversation_id = conversation_id
+        self._write_queue = write_queue
+        self._finished = False
+
+    def _enqueue(self, request: ConversationRequest) -> None:
+        self._write_queue.put_nowait(request)
+
+    def on_chunk(self, text: str) -> None:
+        if self._finished:
+            return
+        chunk = ContentChunk(
+            type=ContentChunk.ChunkType.Value("DELTA"),
+            content=text,
+        )
+        response = AgentResponse(
+            conversation_id=self._conversation_id,
+            content=chunk,
+        )
+        self._enqueue(ConversationRequest(agent_response=response))
+
+    def on_status_update(self, status: dict) -> None:
+        if self._finished:
+            return
+        status_str = status.get("status", "THINKING")
+        custom_message = status.get("custom_message", "")
+        try:
+            status_value = StatusUpdate.Status.Value(status_str)
+        except ValueError:
+            status_value = StatusUpdate.Status.Value("THINKING")
+        update = StatusUpdate(status=status_value, custom_message=custom_message)
+        response = AgentResponse(
+            conversation_id=self._conversation_id,
+            status=update,
+        )
+        self._enqueue(ConversationRequest(agent_response=response))
+
+    def on_error(self, error: Exception) -> None:
+        if self._finished:
+            return
+        self._finished = True
+        err = ErrorResponse(
+            code=ErrorResponse.ErrorCode.Value("AGENT_ERROR"),
+            message=str(error),
+        )
+        response = AgentResponse(
+            conversation_id=self._conversation_id,
+            error=err,
+        )
+        self._enqueue(ConversationRequest(agent_response=response))
+        logger.error("Agent error: %s", error)
+
+    def on_finish(self) -> None:
+        if self._finished:
+            return
+        self._finished = True
+        chunk = ContentChunk(
+            type=ContentChunk.ChunkType.Value("END"),
+            content="",
+        )
+        response = AgentResponse(
+            conversation_id=self._conversation_id,
+            content=chunk,
+        )
+        self._enqueue(ConversationRequest(agent_response=response))
+        _debug("[bridge] Response complete: conversation=%s", self._conversation_id)
+
+    def on_transcript(self, text: str) -> None:
+        pass  # Audio not supported in Phase 1
+
+    def on_audio_chunk(self, data: bytes) -> None:
+        pass  # Audio not supported in Phase 1
+
+    def on_audio_end(self) -> None:
+        pass  # Audio not supported in Phase 1
+
+
+class MessagingBridge:
+    """Connects an agent adapter to the Astro messaging service via gRPC."""
+
+    def __init__(
+        self, adapter: AgentAdapter, options: Optional[ServeOptions] = None
+    ) -> None:
+        self._adapter = adapter
+        self._server_address: str = (
+            (options.server_address if options else None)
+            or os.environ.get("GRPC_SERVER_ADDR")
+            or DEFAULT_SERVER_ADDR
+        )
+        self._channel: Optional[grpc.aio.Channel] = None
+        self._stub: Optional[AgentMessagingStub] = None
+        self._write_queue: asyncio.Queue = asyncio.Queue()
+        self._stop_event: asyncio.Event = asyncio.Event()
+
+    async def _connect_with_retry(self) -> None:
+        for attempt in range(1, MAX_RETRIES + 1):
+            try:
+                self._channel = grpc.aio.insecure_channel(self._server_address)
+                self._stub = AgentMessagingStub(self._channel)
+                response = await self._stub.HealthCheck(HealthCheckRequest())
+                status_name = response.Status.Name(response.status)
+                logger.info("Connected to messaging service (health: %s)", status_name)
+                return
+            except Exception as error:
+                if self._channel:
+                    await self._channel.close()
+                    self._channel = None
+                    self._stub = None
+                if attempt == MAX_RETRIES:
+                    raise
+                delay_ms = min(INITIAL_DELAY_MS * (2 ** (attempt - 1)), MAX_DELAY_MS)
+                logger.info(
+                    "Waiting for messaging service (attempt %d/%d, retry in %dms)...",
+                    attempt,
+                    MAX_RETRIES,
+                    delay_ms,
+                )
+                await asyncio.sleep(delay_ms / 1000)
+
+    async def _writer_task(self, stream: grpc.aio.StreamStreamCall) -> None:
+        """Consumes the write queue and sends messages to the gRPC stream sequentially."""
+        while True:
+            item = await self._write_queue.get()
+            if item is None:
+                break
+            try:
+                await stream.write(item)
+            except Exception as e:
+                logger.error("Stream write error: %s", e)
+
+    async def start(self) -> None:
+        agent_name = self._adapter.name
+        agent_id = agent_name.lower().replace(" ", "-")
+
+        logger.info("Starting %s...", agent_name)
+        logger.info("  gRPC Server: %s", self._server_address)
+
+        await self._connect_with_retry()
+
+        stream = self._stub.ProcessConversation()
+
+        # Start the sequential writer task
+        writer = asyncio.create_task(self._writer_task(stream))
+
+        # Send agent config for playground display
+        config_dict = self._adapter.get_config()
+        tool_configs = [
+            AgentToolConfig(
+                name=t.get("name", ""),
+                title=t.get("name", ""),
+                description=t.get("description", ""),
+                type=t.get("type", "other"),
+            )
+            for t in config_dict.get("tools", [])
+        ]
+        agent_config = AgentConfig(
+            system_prompt=config_dict.get("system_prompt", ""),
+            tools=tool_configs,
+        )
+        await self._write_queue.put(ConversationRequest(agent_config=agent_config))
+        logger.info("Agent config sent")
+
+        # Register the agent
+        registration = Message(
+            conversation_id="agent-registration",
+            platform="grpc",
+            content="Agent ready",
+            user=User(id=agent_id, username=agent_name),
+        )
+        await self._write_queue.put(ConversationRequest(message=registration))
+        logger.info("%s is ready and listening for messages", agent_name)
+
+        # Register signal handlers for graceful shutdown
+        loop = asyncio.get_event_loop()
+        for sig in (signal.SIGINT, signal.SIGTERM):
+            loop.add_signal_handler(sig, self.stop)
+
+        # Read incoming messages from the server
+        try:
+            async for response in stream:
+                payload = response.WhichOneof("payload")
+                if payload != "incoming_message":
+                    continue
+
+                message = response.incoming_message
+                is_audio = (
+                    message.content == "[audio]"
+                    or any(
+                        a.type == a.Type.Value("AUDIO")
+                        for a in message.attachments
+                    )
+                )
+                if is_audio:
+                    # Audio not supported in Phase 1 — reply with error message
+                    hooks = _StreamHooksImpl(message.conversation_id, self._write_queue)
+                    start_chunk = ContentChunk(
+                        type=ContentChunk.ChunkType.Value("START"), content=""
+                    )
+                    await self._write_queue.put(
+                        ConversationRequest(
+                            agent_response=AgentResponse(
+                                conversation_id=message.conversation_id,
+                                content=start_chunk,
+                            )
+                        )
+                    )
+                    hooks.on_chunk(
+                        "Sorry, I don't support audio input. Please send a text message."
+                    )
+                    hooks.on_finish()
+                    continue
+
+                asyncio.create_task(self._handle_message(message))
+        except grpc.aio.AioRpcError as e:
+            if not self._stop_event.is_set():
+                logger.error("Stream error: %s", e)
+        finally:
+            # Drain the writer
+            await self._write_queue.put(None)
+            await writer
+
+        await self._stop_event.wait()
+
+    async def _handle_message(self, message: Message) -> None:
+        conversation_id = message.conversation_id
+
+        # Send START chunk before dispatching to adapter
+        start_chunk = ContentChunk(
+            type=ContentChunk.ChunkType.Value("START"), content=""
+        )
+        await self._write_queue.put(
+            ConversationRequest(
+                agent_response=AgentResponse(
+                    conversation_id=conversation_id,
+                    content=start_chunk,
+                )
+            )
+        )
+
+        hooks = _StreamHooksImpl(conversation_id, self._write_queue)
+        options = StreamOptions(
+            conversation_id=conversation_id,
+            user_id=message.user.id if message.user else "anonymous",
+        )
+
+        try:
+            await self._adapter.stream(message.content, hooks, options)
+        except Exception as error:
+            hooks.on_error(
+                error if isinstance(error, Exception) else Exception(str(error))
+            )
+
+    def stop(self) -> None:
+        logger.info("Shutting down...")
+        self._stop_event.set()
+        loop = asyncio.get_event_loop()
+        for sig in (signal.SIGINT, signal.SIGTERM):
+            try:
+                loop.remove_signal_handler(sig)
+            except Exception:
+                pass

astropods_adapter_core-0.1.0/src/astropods_adapter_core/serve.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import asyncio
+import sys
+from typing import Optional
+
+from .bridge import MessagingBridge
+from .types import AgentAdapter, ServeOptions
+
+
+def serve(adapter: AgentAdapter, options: Optional[ServeOptions] = None) -> None:
+    """Connect an agent adapter to the Astro messaging service and start listening.
+
+    Blocks until the process receives SIGINT or SIGTERM.
+    """
+    bridge = MessagingBridge(adapter, options)
+    try:
+        asyncio.run(bridge.start())
+    except Exception as e:
+        print(f"Fatal error: {e}", file=sys.stderr)
+        sys.exit(1)

astropods_adapter_core-0.1.0/src/astropods_adapter_core/types.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Optional, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class StreamHooks(Protocol):
+    """Lifecycle callbacks called by an adapter as the agent streams a response."""
+
+    def on_chunk(self, text: str) -> None:
+        """Send a text token or fragment from the LLM."""
+        ...
+
+    def on_status_update(self, status: dict) -> None:
+        """Send an agent state change. status must contain a 'status' key with one of:
+        THINKING, SEARCHING, GENERATING, PROCESSING, ANALYZING, CUSTOM.
+        Optionally include 'custom_message' for CUSTOM status.
+        """
+        ...
+
+    def on_error(self, error: Exception) -> None:
+        """Signal that an error occurred during generation."""
+        ...
+
+    def on_finish(self) -> None:
+        """Signal that the response is complete. Must be called exactly once per request.
+        Must not be called if on_error has already been called for the same request.
+        """
+        ...
+
+    def on_transcript(self, text: str) -> None:
+        """Send the transcribed text of the user's audio input."""
+        ...
+
+    def on_audio_chunk(self, data: bytes) -> None:
+        """Send a chunk of TTS audio back to the client."""
+        ...
+
+    def on_audio_end(self) -> None:
+        """Signal the end of the current audio response segment."""
+        ...
+
+
+@dataclass
+class StreamOptions:
+    """Per-request context passed to the adapter's stream method."""
+
+    conversation_id: str
+    user_id: str
+
+
+@dataclass
+class ServeOptions:
+    """Options for the serve() entry point and MessagingBridge."""
+
+    server_address: Optional[str] = None
+
+
+@runtime_checkable
+class AgentAdapter(Protocol):
+    """Framework-agnostic interface that any agent adapter must implement."""
+
+    name: str
+
+    async def stream(
+        self, prompt: str, hooks: StreamHooks, options: StreamOptions
+    ) -> None:
+        """Stream a response for the given prompt, invoking hooks as the agent progresses."""
+        ...
+
+    def get_config(self) -> dict:
+        """Return agent metadata for playground display (system prompt, tool list)."""
+        ...

astropods_adapter_core-0.1.0/tests/conftest.py

@@ -0,0 +1,17 @@
+import pytest
+from unittest.mock import AsyncMock, MagicMock
+from astropods_adapter_core.types import StreamOptions
+
+
+@pytest.fixture
+def mock_adapter():
+    adapter = MagicMock()
+    adapter.name = "Test Agent"
+    adapter.stream = AsyncMock()
+    adapter.get_config.return_value = {"system_prompt": "You are a test agent.", "tools": []}
+    return adapter
+
+
+@pytest.fixture
+def stream_options():
+    return StreamOptions(conversation_id="conv-123", user_id="user-456")

astropods_adapter_core-0.1.0/tests/test_bridge.py

@@ -0,0 +1,171 @@
+import asyncio
+import os
+import pytest
+from unittest.mock import AsyncMock, MagicMock, patch, call
+
+from astropods_adapter_core.bridge import (
+    MessagingBridge,
+    _StreamHooksImpl,
+    DEFAULT_SERVER_ADDR,
+)
+from astropods_adapter_core.types import ServeOptions, StreamOptions
+from astropods_messaging import ContentChunk, StatusUpdate, ErrorResponse
+
+
+# --- _StreamHooksImpl tests ---
+
+class TestStreamHooksImpl:
+    def setup_method(self):
+        self.queue = asyncio.Queue()
+        self.hooks = _StreamHooksImpl("conv-123", self.queue)
+
+    def _dequeue_all(self):
+        items = []
+        while not self.queue.empty():
+            items.append(self.queue.get_nowait())
+        return items
+
+    def test_on_chunk_enqueues_delta(self):
+        self.hooks.on_chunk("hello")
+        items = self._dequeue_all()
+        assert len(items) == 1
+        response = items[0].agent_response
+        assert response.content.type == ContentChunk.ChunkType.Value("DELTA")
+        assert response.content.content == "hello"
+        assert response.conversation_id == "conv-123"
+
+    def test_on_finish_enqueues_end(self):
+        self.hooks.on_finish()
+        items = self._dequeue_all()
+        assert len(items) == 1
+        response = items[0].agent_response
+        assert response.content.type == ContentChunk.ChunkType.Value("END")
+
+    def test_on_finish_sets_finished_flag(self):
+        self.hooks.on_finish()
+        self.hooks.on_chunk("should be ignored")
+        items = self._dequeue_all()
+        assert len(items) == 1  # only the END chunk, not the subsequent chunk
+
+    def test_on_error_enqueues_error_response(self):
+        self.hooks.on_error(ValueError("something went wrong"))
+        items = self._dequeue_all()
+        assert len(items) == 1
+        response = items[0].agent_response
+        assert response.error.code == ErrorResponse.ErrorCode.Value("AGENT_ERROR")
+        assert "something went wrong" in response.error.message
+
+    def test_on_error_sets_finished_flag(self):
+        self.hooks.on_error(Exception("err"))
+        self.hooks.on_finish()  # should be ignored
+        items = self._dequeue_all()
+        assert len(items) == 1  # only the error
+
+    def test_on_status_update_enqueues_status(self):
+        self.hooks.on_status_update({"status": "THINKING"})
+        items = self._dequeue_all()
+        assert len(items) == 1
+        response = items[0].agent_response
+        assert response.status.status == StatusUpdate.Status.Value("THINKING")
+
+    def test_on_status_update_with_custom_message(self):
+        self.hooks.on_status_update({"status": "PROCESSING", "custom_message": "Running tool"})
+        items = self._dequeue_all()
+        response = items[0].agent_response
+        assert response.status.status == StatusUpdate.Status.Value("PROCESSING")
+        assert response.status.custom_message == "Running tool"
+
+    def test_on_status_update_unknown_status_defaults_to_thinking(self):
+        self.hooks.on_status_update({"status": "UNKNOWN_STATUS"})
+        items = self._dequeue_all()
+        response = items[0].agent_response
+        assert response.status.status == StatusUpdate.Status.Value("THINKING")
+
+    def test_on_chunk_ignored_after_finish(self):
+        self.hooks.on_finish()
+        self.hooks.on_chunk("late chunk")
+        self.hooks.on_status_update({"status": "THINKING"})
+        items = self._dequeue_all()
+        assert len(items) == 1  # only the END
+
+    def test_audio_hooks_are_noop(self):
+        self.hooks.on_transcript("text")
+        self.hooks.on_audio_chunk(b"data")
+        self.hooks.on_audio_end()
+        assert self.queue.empty()
+
+
+# --- MessagingBridge constructor tests ---
+
+class TestMessagingBridgeConstructor:
+    def test_uses_options_server_address(self, mock_adapter):
+        bridge = MessagingBridge(mock_adapter, ServeOptions(server_address="custom:1234"))
+        assert bridge._server_address == "custom:1234"
+
+    def test_uses_env_var(self, mock_adapter, monkeypatch):
+        monkeypatch.setenv("GRPC_SERVER_ADDR", "env-host:5678")
+        bridge = MessagingBridge(mock_adapter)
+        assert bridge._server_address == "env-host:5678"
+
+    def test_uses_default_when_no_config(self, mock_adapter, monkeypatch):
+        monkeypatch.delenv("GRPC_SERVER_ADDR", raising=False)
+        bridge = MessagingBridge(mock_adapter)
+        assert bridge._server_address == DEFAULT_SERVER_ADDR
+
+    def test_options_takes_precedence_over_env(self, mock_adapter, monkeypatch):
+        monkeypatch.setenv("GRPC_SERVER_ADDR", "env-host:5678")
+        bridge = MessagingBridge(mock_adapter, ServeOptions(server_address="options-host:9999"))
+        assert bridge._server_address == "options-host:9999"
+
+
+# --- MessagingBridge agent ID derivation ---
+
+class TestAgentIdDerivation:
+    def _get_registration_message(self, sent_messages):
+        """Find the registration ConversationRequest among sent messages."""
+        for msg in sent_messages:
+            if hasattr(msg, "message") and msg.WhichOneof("request") == "message":
+                m = msg.message
+                if m.conversation_id == "agent-registration":
+                    return m
+        return None
+
+    @pytest.mark.asyncio
+    async def test_agent_id_is_lowercased_and_hyphenated(self, monkeypatch):
+        adapter = MagicMock()
+        adapter.name = "My Test Agent"
+        adapter.stream = AsyncMock()
+        adapter.get_config.return_value = {"system_prompt": "", "tools": []}
+
+        sent = []
+
+        mock_stream = MagicMock()
+        mock_stream.write = AsyncMock(side_effect=lambda msg: sent.append(msg))
+
+        async def fake_aiter(self):
+            return
+            yield  # make it an async generator
+
+        mock_stream.__aiter__ = fake_aiter
+
+        mock_stub = MagicMock()
+        mock_stub.HealthCheck = AsyncMock(return_value=MagicMock(status=1))
+        mock_stub.ProcessConversation = MagicMock(return_value=mock_stream)
+
+        bridge = MessagingBridge(adapter, ServeOptions(server_address="localhost:9090"))
+        bridge._stub = mock_stub
+
+        with patch.object(bridge, "_connect_with_retry", new=AsyncMock()):
+            bridge._stub = mock_stub
+            # Run just enough to send registration
+            task = asyncio.create_task(bridge.start())
+            await asyncio.sleep(0.05)
+            bridge.stop()
+            try:
+                await asyncio.wait_for(task, timeout=1.0)
+            except (asyncio.TimeoutError, SystemExit):
+                pass
+
+        registration = self._get_registration_message(sent)
+        if registration:
+            assert registration.user.id == "my-test-agent"