perf(server): lazy-load Pydantic schema generation to fix storyboard readiness flake (#435)

* perf(server): lazy-load Pydantic outputSchema generation to fix storyboard readiness flake

_generate_pydantic_schemas(), _generate_pydantic_output_schemas(), and
_apply_pydantic_schemas() previously ran at module import time, causing
heavy Pydantic type imports to race with the storyboard readiness probe
and producing "Agent unreachable" failures across PRs #391, #405, #406, #407.

Generation is now deferred to the first get_tools_for_handler() call (which
fires during create_mcp_tools() at server construction, not at import time).
_PYDANTIC_SCHEMAS and _PYDANTIC_OUTPUT_SCHEMAS start as empty dicts and are
populated via .update() so external references stay valid. The _schemas_applied
sentinel makes subsequent calls no-ops (~0ms overhead on the hot path).

Import-time delta: ~4.5s of schema generation is moved from `import adcp.server`
to the first `create_mcp_tools()` call.

Tests updated: conftest.py gains a session-scoped autouse fixture that triggers
lazy init before any test reads ADCP_TOOL_DEFINITIONS schema fields; stale
"at import time" references in docstrings and error messages are updated.

Closes #412

https://claude.ai/code/session_01NnoQN3c6Wi5LY5DEUBp8W2

* fixup: update stale 'at import time' docstrings and error messages

Addresses pre-PR review findings: test_spec_coverage.py assertion message
still referenced 'at import time', and _ensure_pydantic_schemas_applied
docstring understated the in-place mutation and misdirected to
get_tools_for_handler instead of create_mcp_tools.

https://claude.ai/code/session_01NnoQN3c6Wi5LY5DEUBp8W2

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: bokelley

src/adcp/server/mcp_tools.py

@@ -1224,8 +1224,8 @@ def _generate_pydantic_schemas() -> dict[str, dict[str, Any]]:
     spec-accurate schemas with proper field types, descriptions,
     required fields, and nested ``$defs``.
 
-    The result is applied to ``ADCP_TOOL_DEFINITIONS`` at import time
-    by :func:`_apply_pydantic_schemas`. Any tool whose generation
+    The result is applied to ``ADCP_TOOL_DEFINITIONS`` lazily on first
+    ``tools/list`` call by :func:`_ensure_pydantic_schemas_applied`. Any tool whose generation
     fails (or whose request model has no mapping here) silently keeps
     its hand-crafted stub; ``tests/test_mcp_schema_drift.py`` guards
     against that regression by asserting every tool has an entry here.
@@ -1558,9 +1558,12 @@ def _generate_pydantic_output_schemas() -> dict[str, dict[str, Any]]:
     return schemas
 
 
-# Generate schemas once at import time
-_PYDANTIC_SCHEMAS = _generate_pydantic_schemas()
-_PYDANTIC_OUTPUT_SCHEMAS = _generate_pydantic_output_schemas()
+# Schemas are populated lazily on the first tools/list call to avoid
+# heavy Pydantic type imports at module import time. Use .update() so
+# external references bound before init (e.g. in tests) stay valid.
+_PYDANTIC_SCHEMAS: dict[str, dict[str, Any]] = {}
+_PYDANTIC_OUTPUT_SCHEMAS: dict[str, dict[str, Any]] = {}
+_schemas_applied = False
 
 
 def _apply_pydantic_schemas() -> None:
@@ -1580,7 +1583,23 @@ def _apply_pydantic_schemas() -> None:
             tool_def["outputSchema"] = _PYDANTIC_OUTPUT_SCHEMAS[name]
 
 
-_apply_pydantic_schemas()
+def _ensure_pydantic_schemas_applied() -> None:
+    """Lazily populate Pydantic schemas and apply them to tool definitions.
+
+    Mutates :data:`ADCP_TOOL_DEFINITIONS` in-place, replacing each tool's
+    ``inputSchema`` with the Pydantic-generated schema and adding
+    ``outputSchema``. Safe to call multiple times — subsequent calls are
+    no-ops. Called automatically by :func:`create_mcp_tools` /
+    :func:`get_tools_for_handler`; callers outside those paths (e.g. tests
+    or doc generators) must invoke this before reading schema fields.
+    """
+    global _schemas_applied
+    if _schemas_applied:
+        return
+    _PYDANTIC_SCHEMAS.update(_generate_pydantic_schemas())
+    _PYDANTIC_OUTPUT_SCHEMAS.update(_generate_pydantic_output_schemas())
+    _apply_pydantic_schemas()
+    _schemas_applied = True
 
 
 def _is_sdk_base_class(cls_name: str) -> bool:
@@ -1718,6 +1737,7 @@ def get_tools_for_handler(
     Returns:
         Filtered list of tool definitions.
     """
+    _ensure_pydantic_schemas_applied()
     cls = handler if isinstance(handler, type) else type(handler)
     instance = handler if not isinstance(handler, type) else None
 

tests/conftest.py

@@ -27,6 +27,15 @@
 _INTEGRATION_DIR = (Path(__file__).parent / "integration").resolve()
 
 
+@pytest.fixture(autouse=True, scope="session")
+def _ensure_pydantic_schemas() -> None:
+    """Trigger lazy Pydantic schema init so ADCP_TOOL_DEFINITIONS has
+    inputSchema/outputSchema populated for any test that reads them directly."""
+    from adcp.server.mcp_tools import _ensure_pydantic_schemas_applied
+
+    _ensure_pydantic_schemas_applied()
+
+
 def _is_integration_test(request: pytest.FixtureRequest) -> bool:
     """Is this test under ``tests/integration/``?
 

tests/test_mcp_schema_drift.py

@@ -2,8 +2,8 @@
 
 The MCP tool registry exposes ``inputSchema`` for every ADCP tool via
 ``tools/list``. These schemas are auto-generated from the corresponding
-Pydantic request models in ``adcp.types`` at import time
-(:func:`adcp.server.mcp_tools._generate_pydantic_schemas`).
+Pydantic request models in ``adcp.types`` on first ``tools/list`` call
+(:func:`adcp.server.mcp_tools._ensure_pydantic_schemas_applied`).
 
 This module protects the generation path from regressions:
 
@@ -59,7 +59,7 @@ def test_input_schemas_match_pydantic_generation() -> None:
 
     assert not mismatches, (
         "ADCP_TOOL_DEFINITIONS has stale inputSchemas — "
-        "`_apply_pydantic_schemas()` must run at import time:\n"
+        "call `_ensure_pydantic_schemas_applied()` (or `create_mcp_tools()`) first:\n"
         + "\n".join(f"  - {name}" for name in mismatches)
     )
 

tests/test_spec_coverage.py

@@ -173,8 +173,8 @@ class MyGovernanceAgent(GovernanceHandler):
 def test_mcp_tool_input_schema_matches_pydantic_models():
     """MCP tool inputSchemas are generated from Pydantic request models.
 
-    The ``ADCP_TOOL_DEFINITIONS[*].inputSchema`` is overwritten at import
-    time by ``_apply_pydantic_schemas()`` with the output of
+    The ``ADCP_TOOL_DEFINITIONS[*].inputSchema`` is overwritten on first
+    ``tools/list`` call by ``_ensure_pydantic_schemas_applied()`` with the output of
     ``model_json_schema()`` on the corresponding ``<ToolName>Request``
     model. This test is a coarse guard that every tool with a mapped
     request model carries a schema advertising every field of that
@@ -213,8 +213,9 @@ def test_mcp_tool_input_schema_matches_pydantic_models():
 
     assert drift == [], (
         "MCP tool inputSchema fields have drifted from Pydantic models.\n"
-        "The inputSchema is auto-generated from the request model at\n"
-        "import time; this drift shouldn't be possible unless schema\n"
-        "generation is broken. See tests/test_mcp_schema_drift.py.\n"
+        "The inputSchema is auto-generated from the request model on first\n"
+        "tools/list call (_ensure_pydantic_schemas_applied()); this drift\n"
+        "shouldn't be possible unless schema generation is broken.\n"
+        "See tests/test_mcp_schema_drift.py.\n"
         + "\n".join(f"  - {d}" for d in drift)
     )