Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(telemetry): report the degrade reason, the keyless case, and every crash leaf (#2056)

Raghav Chamadiya37e2e0927e89
diff --git a/packages/cli/src/repowise/cli/_instrumented_group.py b/packages/cli/src/repowise/cli/_instrumented_group.py
index 3977ca080..84275517f 100644
--- a/packages/cli/src/repowise/cli/_instrumented_group.py
+++ b/packages/cli/src/repowise/cli/_instrumented_group.py
@@ -183,6 +183,21 @@ class InstrumentedGroup(click.Group):
except Exception as exc:
status = "error"
error_type = type(exc).__name__
+ # A task-group crash raises one leaf and stamps the class names of
+ # its siblings on it. `error_type` can only name the one, which
+ # cannot say whether a crash-looping server has a single fault or
+ # several. Read here rather than in the command, so every host of a
+ # task group is covered and an interrupt - handled above, and not a
+ # failure - never lands in the failure dimension.
+ from repowise.core.platform.telemetry import GROUP_LEAF_TYPES_ATTR
+
+ leaves = getattr(exc, GROUP_LEAF_TYPES_ATTR, None)
+ if isinstance(leaves, tuple) and leaves:
+ from repowise.cli.platform import telemetry
+
+ telemetry.add_command_outcome(
+ error_leaves=",".join(leaves), error_leaf_count=len(leaves)
+ )
raise
finally:
# ``invoked_subcommand`` is only populated once ``super().invoke``
diff --git a/packages/core/src/repowise/core/platform/telemetry.py b/packages/core/src/repowise/core/platform/telemetry.py
index 45934f9cd..57bc59566 100644
--- a/packages/core/src/repowise/core/platform/telemetry.py
+++ b/packages/core/src/repowise/core/platform/telemetry.py
@@ -38,6 +38,13 @@ _INGEST_URL = "https://api.repowise.dev/telemetry/events"
#: Best-effort: telemetry must never stall or break a tool call.
_TIMEOUT = 2.0
+#: Attribute an exception carries to report the other failures it was raised
+#: alongside. anyio reports a task group's death as one wrapper holding several
+#: leaves; whoever unwraps it stamps the leaf class names here, and whoever
+#: classifies the invocation reads them off. Named once, in the package both
+#: sides already import, so a rename cannot silently unhook the two.
+GROUP_LEAF_TYPES_ATTR = "repowise_group_leaf_types"
+
_TRUTHY = {"1", "true", "yes", "on"}
#: Common CI signals (kept in sync with the CLI's environment module).
diff --git a/packages/server/src/repowise/server/mcp_server/_meta.py b/packages/server/src/repowise/server/mcp_server/_meta.py
index 7ec20e79b..31e8ffab6 100644
--- a/packages/server/src/repowise/server/mcp_server/_meta.py
+++ b/packages/server/src/repowise/server/mcp_server/_meta.py
@@ -412,6 +412,29 @@ def finalize_trust_envelope(result: Any, *, evidence_kind: str | None = None) ->
return result
+def semantic_search_state() -> bool | None:
+ """Whether retrieval has a real vector leg. ``None`` when never evaluated.
+
+ Three-valued on purpose, and the third value is the point: a signal that only
+ ever reports ``False`` cannot be told apart, by anything aggregating it, from
+ one this version does not report at all. That is exactly the trap
+ ``embedder_degraded`` was written to avoid, and it bites harder here, because
+ the population this measures - keyless installs, where nothing is broken and
+ retrieval is simply full-text-only - is the larger one.
+
+ Kept beside :func:`_embedder_meta` and read by it, so the response and the
+ telemetry can never disagree about the same install.
+ """
+ from repowise.server.mcp_server import _state
+
+ status = getattr(_state, "_embedder_status", None)
+ if not status:
+ return None
+ if status.get("degraded"):
+ return False
+ return status.get("active") != "mock"
+
+
def _embedder_meta() -> dict[str, Any]:
"""Surface embedder degradation (issue #306) in the `_meta` envelope.
@@ -430,7 +453,12 @@ def _embedder_meta() -> dict[str, Any]:
is broken and nothing was misconfigured, so it is not flagged as degraded;
but retrieval really is full-text-only, and a caller that assumes semantic
matching is running will misread a lexical miss as "not in the codebase".
- ``semantic_search: false`` says so once per response without crying wolf.
+ ``semantic_search: false`` says so once per response without crying wolf. The
+ healthy case stays silent on the wire, because ``embedder_degraded: False``
+ with no ``embedder`` key already says it and a second key on every response of
+ every tool would be paid for in the caller's token budget to tell it something
+ it can already see. Telemetry needs the third state named rather than
+ inferred, so it reads :func:`semantic_search_state` directly instead.
"""
# Lazy import: `_state` is a sibling module; importing it at call-time keeps
# `_meta` free of any package import-ordering coupling.
diff --git a/packages/server/src/repowise/server/mcp_server/_savings/wrapper.py b/packages/server/src/repowise/server/mcp_server/_savings/wrapper.py
index c2eeb3524..42ca52279 100644
--- a/packages/server/src/repowise/server/mcp_server/_savings/wrapper.py
+++ b/packages/server/src/repowise/server/mcp_server/_savings/wrapper.py
@@ -44,8 +44,19 @@ logger = logging.getLogger(__name__)
#: Coarse, non-identifying result fields worth reporting per tool call. All are
#: enums or booleans (confidence tier, retrieval quality, staleness) — never
#: query text, paths, or repo/symbol names. See the telemetry privacy contract.
+#:
+#: ``degraded`` names WHY a get_answer reply carries no synthesised prose (no
+#: provider, versus a provider that failed), which is the difference between an
+#: install working as designed and one that broke.
_META_FLAGS = ("index_behind", "embedder_degraded")
-_RESULT_ENUMS = ("confidence", "retrieval_quality", "grounding")
+_RESULT_ENUMS = ("confidence", "retrieval_quality", "grounding", "degraded")
+
+
+def _semantic_search_state() -> bool | None:
+ """The install's vector-leg state, or ``None`` when it was never evaluated."""
+ from repowise.server.mcp_server._meta import semantic_search_state
+
+ return semantic_search_state()
def _results_count_bucket(result: Any) -> str | None:
@@ -89,6 +100,15 @@ def _telemetry_properties(tool: str, result: Any, duration_ms: int) -> dict[str,
bucket = _results_count_bucket(result)
if bucket is not None:
props["results_bucket"] = bucket
+ # Read from server state rather than from the response. `embedder_degraded`
+ # is False on a keyless install by design, so it only ever catches
+ # misconfiguration and the larger keyless population - retrieval genuinely
+ # full-text-only - was invisible. Taking it here keeps the caller's response
+ # exactly as it was: this is a fact about the install, and the agent already
+ # has everything it needs to see it.
+ semantic_search = _semantic_search_state()
+ if semantic_search is not None:
+ props["semantic_search"] = semantic_search
return props
diff --git a/packages/server/src/repowise/server/mcp_server/_server.py b/packages/server/src/repowise/server/mcp_server/_server.py
index ac8e83983..9531cef86 100644
--- a/packages/server/src/repowise/server/mcp_server/_server.py
+++ b/packages/server/src/repowise/server/mcp_server/_server.py
@@ -21,6 +21,7 @@ from repowise.core.persistence.database import (
)
from repowise.core.persistence.search import FullTextSearch
from repowise.core.persistence.vector_store import InMemoryVectorStore
+from repowise.core.platform.telemetry import GROUP_LEAF_TYPES_ATTR
from repowise.core.providers.embedding.base import KeylessEmbedder
from repowise.server.mcp_server import _state
@@ -648,30 +649,28 @@ def _configure_transport_security(host: str) -> None:
)
-def _run_transport(transport: str) -> None:
- """Run the server, raising the cause of a task-group failure rather than the group.
+def group_leaves(exc: BaseException, *, _depth: int = 0) -> list[BaseException]:
+ """Every non-group exception inside *exc*, outermost group flattened.
``mcp.run`` drives an anyio event loop, and anyio reports a child task's
failure as an ``ExceptionGroup`` wrapping the real exception. Anything that
- reads the outermost class then learns only that *a* task failed: the CLI
- records the wrapper's name as the error type, so a missing dependency, a
- permission problem and a closed pipe are indistinguishable after the fact.
- Unwrap to the first leaf and raise that, so the layers above name the real
- error. A group holding several distinct failures loses the siblings, which
- is worth it to stop losing the cause entirely.
+ reads the outermost class learns only that *a* task failed: a missing
+ dependency, a permission problem and a closed pipe are indistinguishable
+ after the fact.
+
+ Returns the whole leaf set rather than the first one. The caller still
+ *raises* the first, because an exception can only be one thing, but the
+ siblings are what say whether a crash is one fault or several — a question
+ the single-leaf unwrap could not be asked, since it discarded them before
+ anything could look. A group that is empty, or nested past
+ :data:`_MAX_GROUP_DEPTH`, yields itself: no leaf is a worse answer than an
+ honest wrapper.
"""
- try:
- mcp.run(transport=transport)
- except BaseExceptionGroup as group:
- leaf: BaseException = group
- for _ in range(_MAX_GROUP_DEPTH):
- if not isinstance(leaf, BaseExceptionGroup) or not leaf.exceptions:
- break
- leaf = leaf.exceptions[0]
- # A cancelled run is how a client-initiated shutdown looks, not a fault.
- if isinstance(leaf, Exception):
- _log.error("MCP server (%s) stopped: %r", transport, leaf, exc_info=leaf)
- raise leaf from group
+ if not isinstance(exc, BaseExceptionGroup) or _depth >= _MAX_GROUP_DEPTH:
+ return [exc]
+ if not exc.exceptions:
+ return [exc]
+ return [leaf for child in exc.exceptions for leaf in group_leaves(child, _depth=_depth + 1)]
def run_mcp(
@@ -686,50 +685,76 @@ def run_mcp(
``tools`` overrides which tools are advertised (see
:func:`repowise.server.mcp_server._tool_selection.apply_tool_selection`);
when omitted, the ``mcp.tools`` config block is honoured.
- """
- _state._repo_path = repo_path
- from repowise.server.mcp_server import ensure_full_surface
- from repowise.server.mcp_server._tool_selection import apply_tool_selection
-
- ensure_full_surface()
- apply_tool_selection(mcp, repo_path=repo_path, override=tools)
- if transport == "sse":
- mcp.settings.host = host
- mcp.settings.port = port
- _configure_transport_security(host)
- if host in ("0.0.0.0", "::") and not os.environ.get("REPOWISE_API_KEY"):
- _log.warning(
- "SECURITY WARNING: MCP server (sse) is binding to %s without "
- "REPOWISE_API_KEY. All tools are unauthenticated and "
- "network-accessible. Set REPOWISE_API_KEY or bind to 127.0.0.1.",
- host,
- )
- _run_transport("sse")
- elif transport == "streamable-http":
- mcp.settings.host = host
- mcp.settings.port = port
- _configure_transport_security(host)
- if host in ("0.0.0.0", "::") and not os.environ.get("REPOWISE_API_KEY"):
- _log.warning(
- "SECURITY WARNING: MCP server (streamable-http) is binding to %s without "
- "REPOWISE_API_KEY. All tools are unauthenticated and "
- "network-accessible. Set REPOWISE_API_KEY or bind to 127.0.0.1.",
- host,
+ A task-group failure is unwrapped over the whole body, not around ``mcp.run``
+ alone: surface construction and transport security run outside that call, and
+ a group raised by either escaped with its wrapper class intact. Every leaf is
+ logged, and the first is re-raised carrying the class names of all of them in
+ :data:`GROUP_LEAF_TYPES_ATTR`. That is what lets the layer recording the
+ outcome say whether one fault or several killed the server, without reaching
+ back in here to re-derive it.
+ """
+ try:
+ _state._repo_path = repo_path
+ from repowise.server.mcp_server import ensure_full_surface
+ from repowise.server.mcp_server._tool_selection import apply_tool_selection
+
+ ensure_full_surface()
+ apply_tool_selection(mcp, repo_path=repo_path, override=tools)
+
+ if transport == "sse":
+ mcp.settings.host = host
+ mcp.settings.port = port
+ _configure_transport_security(host)
+ if host in ("0.0.0.0", "::") and not os.environ.get("REPOWISE_API_KEY"):
+ _log.warning(
+ "SECURITY WARNING: MCP server (sse) is binding to %s without "
+ "REPOWISE_API_KEY. All tools are unauthenticated and "
+ "network-accessible. Set REPOWISE_API_KEY or bind to 127.0.0.1.",
+ host,
+ )
+ mcp.run(transport="sse")
+ elif transport == "streamable-http":
+ mcp.settings.host = host
+ mcp.settings.port = port
+ _configure_transport_security(host)
+ if host in ("0.0.0.0", "::") and not os.environ.get("REPOWISE_API_KEY"):
+ _log.warning(
+ "SECURITY WARNING: MCP server (streamable-http) is binding to %s without "
+ "REPOWISE_API_KEY. All tools are unauthenticated and "
+ "network-accessible. Set REPOWISE_API_KEY or bind to 127.0.0.1.",
+ host,
+ )
+ mcp.run(transport="streamable-http")
+ else:
+ # stdout is the JSON-RPC channel on stdio, so every log line written
+ # there arrives at the client as a malformed protocol frame. Move the
+ # log sinks to stderr before anything can log.
+ from repowise.server.mcp_server._stdio_logging import route_logging_to_stderr
+
+ route_logging_to_stderr()
+ # stdio servers are spawned per-session by the MCP client; when the
+ # client dies abnormally the stdio loop doesn't exit (and Windows
+ # never kills children), leaking servers that hold wiki.db handles.
+ # The watchdog exits this process once the client is gone.
+ from repowise.server.mcp_server._watchdog import start_parent_watchdog
+
+ start_parent_watchdog()
+ mcp.run(transport="stdio")
+ except BaseExceptionGroup as group:
+ leaves = group_leaves(group)
+ for leaf in leaves:
+ # A cancelled run is how a client-initiated shutdown looks, not a fault.
+ if isinstance(leaf, Exception):
+ _log.error("MCP server (%s) stopped: %r", transport, leaf, exc_info=leaf)
+ first = leaves[0]
+ # Best effort: a leaf class with __slots__ refuses the attribute, and the
+ # sibling names are not worth losing the exception over.
+ with contextlib.suppress(AttributeError, TypeError):
+ setattr(
+ first,
+ GROUP_LEAF_TYPES_ATTR,
+ tuple(sorted({type(leaf).__name__ for leaf in leaves})),
)
- _run_transport("streamable-http")
- else:
- # stdout is the JSON-RPC channel on stdio, so every log line written
- # there arrives at the client as a malformed protocol frame. Move the
- # log sinks to stderr before anything can log.
- from repowise.server.mcp_server._stdio_logging import route_logging_to_stderr
-
- route_logging_to_stderr()
- # stdio servers are spawned per-session by the MCP client; when the
- # client dies abnormally the stdio loop doesn't exit (and Windows
- # never kills children), leaking servers that hold wiki.db handles.
- # The watchdog exits this process once the client is gone.
- from repowise.server.mcp_server._watchdog import start_parent_watchdog
-
- start_parent_watchdog()
- _run_transport("stdio")
+ raise first from group
+
diff --git a/tests/unit/cli/test_mcp_transport.py b/tests/unit/cli/test_mcp_transport.py
index 71664d141..ed5e13e50 100644
--- a/tests/unit/cli/test_mcp_transport.py
+++ b/tests/unit/cli/test_mcp_transport.py
@@ -337,3 +337,102 @@ def test_a_plain_error_is_left_alone(monkeypatch) -> None:
with pytest.raises(OSError):
_server.run_mcp(transport="stdio")
+
+
+def test_a_group_from_startup_is_unwrapped_too(monkeypatch) -> None:
+ """The reason the unwrap moved: it used to cover only `mcp.run`.
+
+ Surface construction and transport security run before the transport starts,
+ and a group raised by either escaped with its wrapper class intact - which is
+ the likeliest reason installs still report a bare group class.
+ """
+ import pytest
+
+ from repowise.server.mcp_server import _server
+
+ def boom():
+ raise ExceptionGroup("startup", [PermissionError("wiki.db is not writable")])
+
+ monkeypatch.setattr("repowise.server.mcp_server.ensure_full_surface", boom)
+
+ with pytest.raises(PermissionError):
+ _server.run_mcp(transport="stdio")
+
+
+def test_a_crash_carries_the_names_of_every_leaf(monkeypatch) -> None:
+ """One exception travels; the siblings ride along as class names.
+
+ `error_type` can only ever name the one that was raised, which cannot say
+ whether a crash-looping server has a single fault or several. The names are
+ stamped on the exception so the layer that classifies the invocation can
+ report them without reaching back into the server to re-derive them.
+ """
+ import pytest
+
+ from repowise.core.platform.telemetry import GROUP_LEAF_TYPES_ATTR
+ from repowise.server.mcp_server import _server
+
+ def boom(**_kw):
+ raise ExceptionGroup(
+ "outer",
+ [
+ ModuleNotFoundError("no mcp"),
+ ExceptionGroup("inner", [PermissionError("locked"), OSError("pipe")]),
+ ],
+ )
+
+ monkeypatch.setattr(_server.mcp, "run", boom)
+
+ with pytest.raises(ModuleNotFoundError) as excinfo:
+ _server.run_mcp(transport="stdio")
+
+ assert getattr(excinfo.value, GROUP_LEAF_TYPES_ATTR) == (
+ "ModuleNotFoundError",
+ "OSError",
+ "PermissionError",
+ )
+
+
+def test_the_root_group_reports_those_names(monkeypatch, tmp_path: Path) -> None:
+ """End to end through the CLI: the names reach the invocation's outcome."""
+
+ from repowise.cli.platform import telemetry
+ from repowise.server.mcp_server import _server
+
+ (tmp_path / ".repowise").mkdir()
+ recorded: dict[str, object] = {}
+ monkeypatch.setattr(telemetry, "add_command_outcome", recorded.update)
+
+ def boom(**_kw):
+ raise ExceptionGroup("outer", [ModuleNotFoundError("no mcp"), OSError("pipe")])
+
+ monkeypatch.setattr(_server.mcp, "run", boom)
+
+ result = CliRunner().invoke(cli, ["mcp", str(tmp_path)])
+
+ assert result.exit_code != 0
+ assert recorded["error_leaves"] == "ModuleNotFoundError,OSError"
+ assert recorded["error_leaf_count"] == 2
+
+
+def test_an_interrupt_is_not_reported_as_a_crash(monkeypatch, tmp_path: Path) -> None:
+ """Ctrl-C is how a long-running server normally exits.
+
+ The root group classifies it as `interrupted` rather than an error on
+ purpose; putting crash dimensions on that event would make the failure
+ numbers this exists to measure unreadable in exactly the same way.
+ """
+ from repowise.cli.platform import telemetry
+
+ (tmp_path / ".repowise").mkdir()
+ recorded: dict[str, object] = {}
+ monkeypatch.setattr(telemetry, "add_command_outcome", recorded.update)
+ monkeypatch.setattr(
+ "repowise.server.mcp_server.run_mcp",
+ lambda **_kw: (_ for _ in ()).throw(KeyboardInterrupt()),
+ )
+
+ CliRunner().invoke(cli, ["mcp", str(tmp_path)])
+
+ assert "error_leaves" not in recorded
+
diff --git a/tests/unit/server/mcp/test_embedder_resolution.py b/tests/unit/server/mcp/test_embedder_resolution.py
index 6732b9d34..5173a825a 100644
--- a/tests/unit/server/mcp/test_embedder_resolution.py
+++ b/tests/unit/server/mcp/test_embedder_resolution.py
@@ -283,11 +283,50 @@ def test_build_meta_clean_when_healthy(monkeypatch):
)
meta = build_meta(timing_ms=1.0)
assert meta["embedder_degraded"] is False
+ assert "semantic_search" not in meta
assert "embedder" not in meta
assert "embedder_warning" not in meta
+ ("status", "expected"),
+ [
+ ({"active": "openai", "requested": "openai", "degraded": False}, True),
+ ({"active": "mock", "requested": "mock", "degraded": False}, False),
+ ({"active": "mock", "requested": "openai", "degraded": True}, False),
+ (None, None),
+ ],
+)
+def test_semantic_search_state_is_three_valued(monkeypatch, status, expected):
+ """Telemetry needs the third state named, not inferred.
+
+ A signal that only ever reports ``False`` cannot be told apart, by anything
+ aggregating it, from one this version does not report at all — which is what
+ hid the keyless population, the larger one, behind ``embedder_degraded``.
+ Absent means "never evaluated" and stays distinct from an explicit ``False``.
+ """
+ from repowise.server.mcp_server._meta import semantic_search_state
+
+ monkeypatch.setattr(_state, "_embedder_status", status)
+ assert semantic_search_state() is expected
+
+
+def test_build_meta_marks_a_keyless_index_full_text_only(monkeypatch):
+ """The keyless install: nothing broken, but retrieval really is FTS-only."""
+ monkeypatch.setattr(
+ _state,
+ "_embedder_status",
+ {"active": "mock", "requested": "mock", "degraded": False},
+ )
+ meta = build_meta(timing_ms=1.0)
+ assert meta["embedder_degraded"] is False
+ assert meta["semantic_search"] is False
+ assert meta["embedder"] == "mock"
+
+
def test_build_meta_omits_degraded_when_embedder_unresolved(monkeypatch):
"""Nothing resolved → the check never ran, so neither value is honest."""
monkeypatch.setattr(_state, "_embedder_status", None)
- assert "embedder_degraded" not in build_meta(timing_ms=1.0)
+ meta = build_meta(timing_ms=1.0)
+ assert "embedder_degraded" not in meta
+ assert "semantic_search" not in meta
diff --git a/tests/unit/server/mcp/test_exception_group_leaves.py b/tests/unit/server/mcp/test_exception_group_leaves.py
new file mode 100644
index 000000000..fc1ca40de
--- /dev/null
+++ b/tests/unit/server/mcp/test_exception_group_leaves.py
@@ -0,0 +1,65 @@
+"""A task-group crash names every fault in it, not just the first one.
+
+anyio reports a child task's failure as an ``ExceptionGroup``, so the class the
+layers above record was ``ExceptionGroup`` and nothing more: a missing
+dependency, a permission problem and a closed pipe read identically. The unwrap
+that fixed that kept ``exceptions[0]`` and dropped the siblings, which trades
+one blind spot for a smaller one — 73 installs a month still report a bare group
+class, and on a crash-looping server one fault masking another costs weeks.
+
+These pin the flatten itself. The raise still carries exactly one exception,
+because an exception can only be one thing; the leaf set travels beside it.
+"""
+
+from __future__ import annotations
+
+from repowise.server.mcp_server._server import group_leaves
+
+
+def test_a_plain_exception_is_its_own_leaf():
+ exc = ValueError("boom")
+ assert group_leaves(exc) == [exc]
+
+
+def test_every_sibling_survives():
+ """The whole point: `exceptions[0]` alone said one fault where there were two."""
+ a, b = ModuleNotFoundError("no mcp"), PermissionError("locked")
+ assert group_leaves(ExceptionGroup("g", [a, b])) == [a, b]
+
+
+def test_a_nested_group_flattens_to_its_leaves():
+ """anyio nests groups when a task group fails inside another one."""
+ inner = ExceptionGroup("inner", [OSError("a"), OSError("b")])
+ outer = ExceptionGroup("outer", [ValueError("v"), inner])
+ assert [type(leaf).__name__ for leaf in group_leaves(outer)] == [
+ "ValueError",
+ "OSError",
+ "OSError",
+ ]
+
+
+def test_an_empty_group_yields_itself():
+ """A group is a worse answer than a leaf, and a better one than nothing.
+
+ ``ExceptionGroup`` refuses an empty sequence, so this is reachable only
+ through a subclass that overrides it — but the flatten must not return an
+ empty list either way, since the caller raises ``leaves[0]``.
+ """
+
+ class _Empty(ExceptionGroup):
+ @property
+ def exceptions(self):
+ return ()
+
+ empty = _Empty("nothing", [ValueError("placeholder")])
+ assert group_leaves(empty) == [empty]
+
+
+def test_pathological_nesting_stops_at_the_depth_cap():
+ """The cap exists to stop a cycle hanging, not because deep groups are real."""
+ exc: BaseException = ValueError("core")
+ for i in range(40):
+ exc = ExceptionGroup(f"g{i}", [exc])
+ leaves = group_leaves(exc)
+ assert len(leaves) == 1
+ assert isinstance(leaves[0], BaseExceptionGroup)
diff --git a/tests/unit/server/mcp/test_tool_telemetry.py b/tests/unit/server/mcp/test_tool_telemetry.py
index e42159f77..38921ba8c 100644
--- a/tests/unit/server/mcp/test_tool_telemetry.py
+++ b/tests/unit/server/mcp/test_tool_telemetry.py
@@ -13,6 +13,16 @@ from repowise.server.mcp_server._savings import wrapper
class TestTelemetryProperties:
+ @pytest.fixture(autouse=True)
+ def _no_ambient_embedder(self, monkeypatch: pytest.MonkeyPatch):
+ """Pin the install-level state so the exact-shape cases stay exact.
+
+ `semantic_search` is read from server state rather than the response, so
+ without this an unrelated test leaving an embedder resolved would add a
+ key here and the equality assertions would fail for the wrong reason.
+ """
+ monkeypatch.setattr(wrapper, "_semantic_search_state", lambda: None)
+
def test_answer_shape_extracts_enums_and_flags(self):
result = {
"answer": "…prose the agent reads…", # must NOT be reported
@@ -33,6 +43,49 @@ class TestTelemetryProperties:
"embedder_degraded": False,
}
+ def test_degraded_answer_reports_why_synthesis_was_missing(self):
+ """"No provider" and "the provider failed" are different products.
+
+ Both return the same payload shape, so without this dimension a keyless
+ install working exactly as designed is indistinguishable from a broken
+ one, and neither can be sized.
+ """
+ result = {
+ "answer": "…assembled boilerplate…",
+ "confidence": "medium",
+ "retrieval_quality": "high",
+ "degraded": "no-llm-provider",
+ "_meta": {"embedder_degraded": False},
+ }
+ props = wrapper._telemetry_properties("get_answer", result, 7)
+ assert props["degraded"] == "no-llm-provider"
+ assert props["embedder_degraded"] is False
+ # The reason is an enum; the prose it explains never travels.
+ assert "answer" not in props
+
+ def test_semantic_search_is_read_from_the_install_not_the_response(
+ self, monkeypatch: pytest.MonkeyPatch
+ ):
+ """The response shape is untouched; the dimension still gets all three states.
+
+ Putting this on the wire would have cost every caller tokens on every
+ call to say something `embedder_degraded` already implies. It is a fact
+ about the install, so it is read from the install.
+ """
+ monkeypatch.setattr(wrapper, "_semantic_search_state", lambda: False)
+ props = wrapper._telemetry_properties("get_answer", {"confidence": "low"}, 1)
+ assert props["semantic_search"] is False
+
+ monkeypatch.setattr(wrapper, "_semantic_search_state", lambda: True)
+ assert wrapper._telemetry_properties("get_answer", {}, 1)["semantic_search"] is True
+
+ def test_an_unevaluated_embedder_reports_no_semantic_search(
+ self, monkeypatch: pytest.MonkeyPatch
+ ):
+ """Absent stays distinct from False: "never checked" is not "off"."""
+ monkeypatch.setattr(wrapper, "_semantic_search_state", lambda: None)
+ assert "semantic_search" not in wrapper._telemetry_properties("get_answer", {}, 1)
+
def test_error_result_is_status_error(self):
props = wrapper._telemetry_properties("get_symbol", {"error": "boom"}, 3)
assert props["status"] == "error"