trodo-python 2.20.0__tar.gz → 2.22.0__tar.gz

{trodo_python-2.20.0 → trodo_python-2.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trodo-python
-Version: 2.20.0
+Version: 2.22.0
 Summary: Trodo Analytics SDK for Python — server-side event tracking
 License: ISC
 Keywords: analytics,tracking,trodo,server-side

{trodo_python-2.20.0 → trodo_python-2.22.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "trodo-python"
-version = "2.20.0"
+version = "2.22.0"
 description = "Trodo Analytics SDK for Python — server-side event tracking"
 readme = "README.md"
 license = { text = "ISC" }

{trodo_python-2.20.0 → trodo_python-2.22.0}/tests/test_error_enrichment.py

@@ -70,6 +70,31 @@ def test_errored_span_and_run_carry_rich_error_fields(processor, http):
     assert "rate limit exceeded" in run_payload["error_summary"]
 
 
+def test_raised_exception_carries_the_recorded_run_id(processor, http):
+    # The run IS recorded when an agent raises; this is the JOIN -- the
+    # exception a developer's error tracker captures must reference it.
+    with pytest.raises(RateLimitError) as e:
+        with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+            raise RateLimitError("boom")
+
+    run_payload = http.run_ingest[0]["run"]
+    assert e.value.trodo_run_id == run_payload["run_id"]
+    assert run_payload["status"] == "error"
+
+
+def test_slotted_exception_still_propagates(processor, http):
+    # An exception that can't take attributes must not crash the error path --
+    # a failure inside error handling is the one unforgivable bug here.
+    class Slotted(Exception):
+        __slots__ = ()
+
+    with pytest.raises(Slotted):
+        with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+            raise Slotted("rigid")
+
+    assert http.run_ingest[0]["run"]["status"] == "error"
+
+
 def test_set_error_records_without_raising(processor, http):
     with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat") as run:
         with span("soft-step", kind="tool") as s:

trodo_python-2.22.0/tests/test_instrumentor_resolution.py

@@ -0,0 +1,109 @@
+"""Instrumentor class resolution must survive upstream renames.
+
+Every per-framework instrumentor is loaded by name, and the loader in
+``enable_auto_instrument`` swallows failures so a missing optional package
+never breaks user code. The cost of that tolerance: a RENAMED export is
+indistinguishable from an absent package. The user installs exactly the
+package we documented, gets zero spans, and gets no error explaining why.
+
+That is not hypothetical — it happened twice. ``google-generativeai`` renamed
+its class, and ``opentelemetry-instrumentation-langchain`` ships
+``LangchainInstrumentor`` while we imported ``LangChainInstrumentor``, which
+silently disabled LangChain tracing for every Python user on a current version.
+
+So resolution tries the known spellings and then falls back to whatever single
+``*Instrumentor`` the module exports.
+"""
+import sys
+import types
+
+import pytest
+
+from trodo.otel.auto_instrument import _instrument
+
+
+def _fake_module(name, **attrs):
+    mod = types.ModuleType(name)
+    for k, v in attrs.items():
+        setattr(mod, k, v)
+    sys.modules[name] = mod
+    return mod
+
+
+class _Recorder:
+    instrumented = False
+
+    def instrument(self):
+        type(self).instrumented = True
+
+
+@pytest.fixture(autouse=True)
+def _clean():
+    made = []
+    yield made
+    for n in made:
+        sys.modules.pop(n, None)
+
+
+def test_uses_the_preferred_name_when_present(_clean):
+    name = 'fake_instr_preferred'
+    _clean.append(name)
+    cls = type('WantedInstrumentor', (_Recorder,), {'instrumented': False})
+    _fake_module(name, WantedInstrumentor=cls, OtherInstrumentor=type('OtherInstrumentor', (_Recorder,), {}))
+    _instrument(name, 'WantedInstrumentor')
+    assert cls.instrumented is True
+
+
+def test_tries_each_spelling_in_order(_clean):
+    """The real LangChain case: we ask for both casings, upstream ships one."""
+    name = 'fake_instr_langchain'
+    _clean.append(name)
+    cls = type('LangchainInstrumentor', (_Recorder,), {'instrumented': False})
+    _fake_module(name, LangchainInstrumentor=cls)
+    # 'LangChainInstrumentor' (capital C) does not exist here — must not raise.
+    _instrument(name, 'LangchainInstrumentor', 'LangChainInstrumentor')
+    assert cls.instrumented is True
+
+
+def test_falls_back_to_the_only_exported_instrumentor(_clean):
+    """An unforeseen rename still works, which is the whole point."""
+    name = 'fake_instr_renamed'
+    _clean.append(name)
+    cls = type('SomethingWeNeverHeardOfInstrumentor', (_Recorder,), {'instrumented': False})
+    _fake_module(name, SomethingWeNeverHeardOfInstrumentor=cls)
+    _instrument(name, 'ExpectedInstrumentor')
+    assert cls.instrumented is True
+
+
+def test_refuses_to_guess_between_several_candidates(_clean):
+    """Picking arbitrarily could instrument the wrong thing — say so instead."""
+    name = 'fake_instr_ambiguous'
+    _clean.append(name)
+    _fake_module(name,
+                 AInstrumentor=type('AInstrumentor', (_Recorder,), {}),
+                 BInstrumentor=type('BInstrumentor', (_Recorder,), {}))
+    with pytest.raises(ImportError, match='several Instrumentor classes'):
+        _instrument(name, 'NopeInstrumentor')
+
+
+def test_reports_when_nothing_is_exported(_clean):
+    name = 'fake_instr_empty'
+    _clean.append(name)
+    _fake_module(name)
+    with pytest.raises(ImportError, match='no Instrumentor class'):
+        _instrument(name, 'AnyInstrumentor')
+
+
+def test_base_instrumentor_is_never_the_fallback(_clean):
+    """Modules re-export BaseInstrumentor; instrumenting it would be wrong."""
+    name = 'fake_instr_baseonly'
+    _clean.append(name)
+    _fake_module(name, BaseInstrumentor=type('BaseInstrumentor', (_Recorder,), {}))
+    with pytest.raises(ImportError, match='no Instrumentor class'):
+        _instrument(name, 'AnyInstrumentor')
+
+
+def test_a_missing_module_still_raises_importerror(_clean):
+    """The caller relies on ImportError to mean "skip this framework"."""
+    with pytest.raises(ImportError):
+        _instrument('module_that_does_not_exist_xyz', 'AnyInstrumentor')

trodo_python-2.22.0/tests/test_prompt_trace.py

@@ -0,0 +1,261 @@
+"""Prompt -> span traceability (mirrors the Node promptTrace.test.ts).
+
+Compiling a managed prompt must stamp the exact version (by immutable hash)
+onto the spans that used it, and aggregate every prompt used onto the run.
+
+Two routes get it there, and both are load-bearing:
+  - the RUN SCOPE, when compile() runs inside wrap_agent/span. The only route
+    that reaches auto-instrumented spans, whose input we never see.
+  - the COMPILED VALUE, when those messages are passed to a span as ``input``.
+    The only route that survives compiling outside the run, which is an
+    ordinary shape and used to produce no link at all.
+"""
+from __future__ import annotations
+
+from trodo.managers.prompt_manager import PromptManager
+from trodo.otel.wrap_agent import span, wrap_agent
+
+PROMPT_WIRE = {
+    "name": "refund-agent",
+    "version": 3,
+    "version_hash": "a3f9c2e8d1b04756",
+    "content_hash": "ccccontent1234",
+    "parent_hash": "pppparent5678",
+    "labels": ["production"],
+    "tags": [],
+    "messages": [{"role": "system", "content": [{"type": "text", "text": "Help {{q}}"}]}],
+    "model": {"provider": "openai", "model": "gpt-4o"},
+    "tools": [],
+    "response_format": None,
+    "variables": [{"name": "q", "type": "string"}],
+    "updated_at": "2026-07-01T00:00:00Z",
+}
+
+
+class PromptHttp:
+    def __init__(self, prompt=None, fail=False):
+        self._prompt = prompt
+        self.fail = fail
+
+    def get_prompt(self, name, label=None, version=None):
+        if self.fail:
+            raise RuntimeError("unreachable")
+        return {"prompt": dict(self._prompt)}
+
+
+def test_stamps_version_hash_on_span_and_aggregates_on_run(processor, http):
+    mgr = PromptManager(PromptHttp(prompt=PROMPT_WIRE))
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        p = mgr.get("refund-agent", cache_ttl_seconds=0)
+        with span("llm", kind="llm"):
+            p.compile(q="my order")
+
+    ingest = http.run_ingest[0]
+    spans = ingest["spans"]
+    llm = next(s for s in spans if s["name"] == "llm")
+    attrs = llm["attributes"]
+    assert attrs["trodo.prompt.name"] == "refund-agent"
+    assert attrs["trodo.prompt.version_hash"] == "a3f9c2e8d1b04756"
+    assert attrs["trodo.prompt.label"] == "production"  # default selector
+    assert attrs["trodo.prompt.content_hash"] == "ccccontent1234"
+
+    used = ingest["run"]["attributes"]["trodo.prompts"]
+    assert len(used) == 1
+    assert used[0]["version_hash"] == "a3f9c2e8d1b04756"
+
+
+def test_records_label_and_omits_it_for_version_pin(processor, http):
+    mgr = PromptManager(PromptHttp(prompt=PROMPT_WIRE))
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        staged = mgr.get("refund-agent", label="staging", cache_ttl_seconds=0)
+        with span("s1"):
+            staged.compile(q="x")
+        pinned = mgr.get("refund-agent", version="a3f9c2", cache_ttl_seconds=0)
+        with span("s2"):
+            pinned.compile(q="y")
+
+    spans = http.run_ingest[0]["spans"]
+    s1 = next(s for s in spans if s["name"] == "s1")["attributes"]
+    s2 = next(s for s in spans if s["name"] == "s2")["attributes"]
+    assert s1["trodo.prompt.label"] == "staging"
+    assert "trodo.prompt.label" not in s2  # pinned by hash -> no label
+    assert s2["trodo.prompt.version_hash"] == "a3f9c2e8d1b04756"
+
+
+def test_no_op_outside_a_run(processor, http):
+    mgr = PromptManager(PromptHttp(prompt=PROMPT_WIRE))
+    p = mgr.get("refund-agent", cache_ttl_seconds=0)
+    # Must not raise despite there being no active run context.
+    p.compile(q="z")
+    assert len(http.run_ingest) == 0
+
+
+def test_fallback_prompt_is_not_traced(processor, http):
+    mgr = PromptManager(PromptHttp(fail=True))
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        p = mgr.get(
+            "refund-agent",
+            cache_ttl_seconds=0,
+            max_retries=0,
+            fallback={
+                "messages": [{"role": "user", "content": [{"type": "text", "text": "hi {{q}}"}]}],
+                "variables": [{"name": "q"}],
+            },
+        )
+        assert p.is_fallback is True
+        with span("llm"):
+            p.compile(q="x")
+
+    spans = http.run_ingest[0]["spans"]
+    attrs = next(s for s in spans if s["name"] == "llm").get("attributes") or {}
+    assert "trodo.prompt.name" not in attrs
+    # to_dict() drops None, so an untraced run has no 'attributes' key at all.
+    assert "attributes" not in http.run_ingest[0]["run"]
+
+
+# ── compiled OUTSIDE the run ────────────────────────────────────────────────
+#
+# Fetch and compile up front, open the run around just the model call. Under the
+# run-scope mechanism alone this produced no link whatsoever.
+
+
+def test_links_span_whose_input_was_compiled_outside_the_run(processor, http):
+    mgr = PromptManager(PromptHttp(prompt=PROMPT_WIRE))
+    p = mgr.get("refund-agent", cache_ttl_seconds=0)
+    compiled = p.compile(q="z")  # OUTSIDE any run
+
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        with span("llm", kind="llm", input=compiled.messages):
+            pass
+
+    attrs = next(s for s in http.run_ingest[0]["spans"] if s["name"] == "llm")["attributes"]
+    assert attrs["trodo.prompt.name"] == "refund-agent"
+    assert attrs["trodo.prompt.version_hash"] == "a3f9c2e8d1b04756"
+
+
+def test_outside_compiled_prompt_reaches_the_run_level_list(processor, http):
+    mgr = PromptManager(PromptHttp(prompt=PROMPT_WIRE))
+    p = mgr.get("refund-agent", cache_ttl_seconds=0)
+    compiled = p.compile(q="z")
+
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        with span("llm", kind="llm", input=compiled.messages):
+            pass
+
+    used = http.run_ingest[0]["run"]["attributes"]["trodo.prompts"]
+    assert [r["name"] for r in used] == ["refund-agent"]
+
+
+def test_the_compiled_wrapper_works_as_input_too(processor, http):
+    mgr = PromptManager(PromptHttp(prompt=PROMPT_WIRE))
+    p = mgr.get("refund-agent", cache_ttl_seconds=0)
+    compiled = p.compile(q="z")
+
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        with span("llm", kind="llm", input=compiled):
+            pass
+
+    attrs = next(s for s in http.run_ingest[0]["spans"] if s["name"] == "llm")["attributes"]
+    assert attrs["trodo.prompt.name"] == "refund-agent"
+
+
+def test_span_input_beats_the_runs_most_recent_prompt(processor, http):
+    """Specificity: a span holding prompt A must say A, not whatever came last."""
+    other = dict(PROMPT_WIRE, name="other-agent", version_hash="bbbb2222", content_hash="ccc2")
+
+    class TwoPrompts:
+        def get_prompt(self, name, label=None, version=None):
+            return {"prompt": dict(other if name == "other-agent" else PROMPT_WIRE)}
+
+    mgr = PromptManager(TwoPrompts())
+    a = mgr.get("refund-agent", cache_ttl_seconds=0).compile(q="first")
+
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        # Compiling B inside the run makes B the run's "current" prompt.
+        mgr.get("other-agent", cache_ttl_seconds=0).compile(q="second")
+        with span("llm", kind="llm", input=a.messages):
+            pass
+
+    attrs = next(s for s in http.run_ingest[0]["spans"] if s["name"] == "llm")["attributes"]
+    assert attrs["trodo.prompt.name"] == "refund-agent"
+    assert attrs["trodo.prompt.version_hash"] == "a3f9c2e8d1b04756"
+
+
+def test_a_span_that_never_saw_a_prompt_is_not_labelled(processor, http):
+    """False-positive guard: attribution must not leak to sibling spans."""
+    mgr = PromptManager(PromptHttp(prompt=PROMPT_WIRE))
+    p = mgr.get("refund-agent", cache_ttl_seconds=0)
+    compiled = p.compile(q="z")
+
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        with span("llm", kind="llm", input=compiled.messages):
+            pass
+        with span("unrelated", input={"some": "payload"}):
+            pass
+
+    attrs = next(s for s in http.run_ingest[0]["spans"] if s["name"] == "unrelated").get("attributes") or {}
+    assert "trodo.prompt.name" not in attrs
+
+
+def test_hand_written_messages_are_not_carriers(processor, http):
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        with span("llm", kind="llm", input=[{"role": "user", "content": "hand-written"}]):
+            pass
+
+    attrs = next(s for s in http.run_ingest[0]["spans"] if s["name"] == "llm").get("attributes") or {}
+    assert "trodo.prompt.name" not in attrs
+
+
+def test_a_fallback_is_never_tagged_via_the_input_route(processor, http):
+    mgr = PromptManager(PromptHttp(fail=True))
+    p = mgr.get(
+        "refund-agent",
+        fallback={"messages": [{"role": "user", "content": [{"type": "text", "text": "hi {{q}}"}]}],
+                  "variables": [{"name": "q"}]},
+        cache_ttl_seconds=0,
+    )
+    assert p.is_fallback
+    compiled = p.compile(q="x")
+
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        with span("llm", kind="llm", input=compiled.messages):
+            pass
+
+    attrs = next(s for s in http.run_ingest[0]["spans"] if s["name"] == "llm").get("attributes") or {}
+    assert "trodo.prompt.name" not in attrs
+
+
+def test_carrier_table_is_bounded(processor, http):
+    """It must not grow without limit in a long-lived process."""
+    from trodo.otel import prompt_trace
+
+    mgr = PromptManager(PromptHttp(prompt=PROMPT_WIRE))
+    p = mgr.get("refund-agent", cache_ttl_seconds=0)
+    for _ in range(prompt_trace._MAX_CARRIERS + 200):
+        p.compile(q="x")
+
+    assert len(prompt_trace._carrier_refs) <= prompt_trace._MAX_CARRIERS
+    assert len(prompt_trace._carrier_keepalive) <= prompt_trace._MAX_CARRIERS
+
+
+def test_run_set_input_records_the_prompt_on_the_run(processor, http):
+    """The shape that still leaves auto-instrumented spans unlabelled: compile
+    up front, hand the messages to the RUN, let a framework make the call. The
+    run can at least say which prompt it ran."""
+    mgr = PromptManager(PromptHttp(prompt=PROMPT_WIRE))
+    p = mgr.get("refund-agent", cache_ttl_seconds=0)
+    compiled = p.compile(q="z")
+
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat") as run:
+        run.set_input(compiled.messages)
+
+    used = http.run_ingest[0]["run"]["attributes"]["trodo.prompts"]
+    assert [r["name"] for r in used] == ["refund-agent"]
+
+
+def test_run_set_input_with_ordinary_input_records_nothing(processor, http):
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat") as run:
+        run.set_input({"query": "hello"})
+
+    attrs = http.run_ingest[0]["run"].get("attributes") or {}
+    assert "trodo.prompts" not in attrs

{trodo_python-2.20.0 → trodo_python-2.22.0}/tests/test_prompts.py

@@ -133,6 +133,16 @@ def test_compile_applies_a_default_when_omitted():
     assert out.messages[1]["content"][0] == {"type": "text", "text": "Hello world"}
 
 
+def test_coercion_error_text_matches_node_byte_for_byte():
+    # Node formats the offending value with JSON.stringify; repr's single
+    # quotes were the ONE divergence a full cross-SDK parity run found. The
+    # double quotes here are the point of the test.
+    numeric = {**PROMPT, "variables": [{"name": "who", "type": "number"}]}
+    with pytest.raises(CompileError) as e:
+        compile_prompt(numeric, {"who": "not-a-number"})
+    assert 'variable \'who\': expected a number, got "not-a-number"' in str(e.value)
+
+
 def test_compile_rejects_undeclared_variable():
     # Passing a variable the prompt doesn't declare is the one variable mistake
     # compile still catches (it's almost always a typo/rename).
@@ -218,6 +228,8 @@ class FakeHttp:
         self.last = {"name": name, "label": label, "version": version}
         if self.fail:
             raise RuntimeError("API down")
+        if getattr(self, "error_body", None):
+            return dict(self.error_body)
         return {"prompt": self._prompt}
 
     def list_prompts(self):
@@ -289,6 +301,58 @@ def test_stale_cache_survives_an_outage():
     assert mgr.get("greeter", cache_ttl_seconds=0.01).version == 2
 
 
+def test_missing_prompt_with_fallback_serves_fallback():
+    # Deleting a prompt mid-deploy is exactly what the fallback exists for --
+    # plain prompt_not_found stays an availability failure.
+    http = FakeHttp()
+    http.error_body = {"__error": True, "status": 404, "error": "prompt_not_found"}
+    mgr = PromptManager(http)
+    p = mgr.get("gone", cache_ttl_seconds=0, max_retries=0,
+                fallback={"messages": [{"role": "user", "content": [{"type": "text", "text": "hi"}]}]})
+    assert p.is_fallback is True
+
+
+def test_bad_version_raises_through_the_fallback():
+    # A selector naming nothing is a CONFIG error, not an outage. Being quietly
+    # handed the fallback would hide the typo for as long as it ships.
+    http = FakeHttp()
+    http.error_body = {"__error": True, "status": 404, "error": "version_not_found"}
+    mgr = PromptManager(http)
+    with pytest.raises(LookupError, match="version 999 does not exist on prompt 'greeter'") as e:
+        mgr.get("greeter", version=999, cache_ttl_seconds=0, max_retries=0,
+                fallback={"messages": [{"role": "user", "content": [{"type": "text", "text": "hi"}]}]})
+    assert e.value.code == "version_not_found"
+
+
+def test_bad_label_raises_through_the_fallback():
+    http = FakeHttp()
+    http.error_body = {"__error": True, "status": 404, "error": "label_not_found"}
+    mgr = PromptManager(http)
+    with pytest.raises(LookupError) as e:
+        mgr.get("greeter", label="prod-ue", cache_ttl_seconds=0, max_retries=0,
+                fallback={"messages": [{"role": "user", "content": [{"type": "text", "text": "hi"}]}]})
+    assert e.value.code == "label_not_found"
+
+
+def test_versionless_prompt_says_what_to_do():
+    http = FakeHttp()
+    http.error_body = {"__error": True, "status": 404, "error": "no_versions"}
+    mgr = PromptManager(http)
+    with pytest.raises(LookupError, match="has no versions yet"):
+        mgr.get("empty", cache_ttl_seconds=0, max_retries=0)
+
+
+def test_config_error_not_masked_by_stale_cache():
+    # First fetch succeeds and caches; the label is then deleted server-side.
+    http = FakeHttp(prompt=WIRE)
+    mgr = PromptManager(http)
+    assert mgr.get("greeter", label="production", cache_ttl_seconds=0).version == 2
+    http.error_body = {"__error": True, "status": 404, "error": "label_not_found"}
+    with pytest.raises(LookupError) as e:
+        mgr.get("greeter", label="production", cache_ttl_seconds=0, max_retries=0)
+    assert e.value.code == "label_not_found"
+
+
 def test_fallback_used_when_api_down_and_nothing_cached():
     mgr = PromptManager(FakeHttp(fail=True))
     p = mgr.get(

{trodo_python-2.20.0 → trodo_python-2.22.0}/trodo/__init__.py

@@ -41,7 +41,7 @@ Downstream microservice (join the caller's run instead of making a new one):
 
 from __future__ import annotations
 
-__version__ = "2.20.0"
+__version__ = "2.21.0"
 
 from typing import Any, Callable, Dict, List, Optional, Union
 

{trodo_python-2.20.0 → trodo_python-2.22.0}/trodo/managers/prompt_manager.py

@@ -38,6 +38,11 @@ __all__ = [
 DEFAULT_TTL_SECONDS = 60.0
 
 
+# 404 bodies that mean "your SELECTOR is wrong", not "the prompt is gone".
+# Mirrors backend/models/prompt.js missReason -- the wire contract's error half.
+_CONFIG_ERROR_CODES = frozenset({"version_not_found", "label_not_found", "no_versions"})
+
+
 def _cache_key(name: str, version: Optional[Union[int, str]], label: Optional[str]) -> str:
     # Resolution happens server-side on every fetch; the client only caches
     # under whatever selector was asked for. So a label flip propagates within
@@ -197,7 +202,14 @@ class PromptManager:
         Availability ladder — fresh cache -> stale cache -> ``fallback`` ->
         raise. A prompt fetch is on your hot path, so a Trodo outage degrades
         rather than takes your app down. Check ``prompt.is_fallback`` to detect
-        the last rung. Pass ``cache_ttl_seconds=0`` to disable caching (handy in
+        the last rung.
+
+        The ladder is for AVAILABILITY failures only. A selector that names
+        nothing — a ``version`` or ``label`` that doesn't exist on a prompt
+        that does — is a config error in your code and raises immediately
+        (``e.code`` is ``version_not_found`` | ``label_not_found`` |
+        ``no_versions``), because being quietly handed the fallback would hide
+        the typo for as long as it ships. Pass ``cache_ttl_seconds=0`` to disable caching (handy in
         development).
 
         :raises ValueError: if *name* is empty, or both ``label`` and ``version``
@@ -224,6 +236,22 @@ class PromptManager:
             if not res or res.get("__error") or not res.get("prompt"):
                 status = res.get("status") if isinstance(res, dict) else None
                 detail = res.get("error") if isinstance(res, dict) else None
+                # The server distinguishes a selector that names nothing from a
+                # prompt that is missing. The first is a CONFIG error -- your
+                # code asks for a version or label that does not exist -- and
+                # must throw through the availability ladder below rather than
+                # be masked by stale content or the fallback.
+                if detail in _CONFIG_ERROR_CODES:
+                    if detail == "version_not_found":
+                        what = f"version {version!r} does not exist on prompt {name!r}"
+                    elif detail == "label_not_found":
+                        what = f"label {label!r} does not exist on prompt {name!r}"
+                    else:
+                        what = f"prompt {name!r} has no versions yet -- save one in the dashboard"
+                    err = LookupError(f"trodo: {what}" + (f" (HTTP {status})" if status else ""))
+                    err.code = detail  # type: ignore[attr-defined]
+                    err.prompt_config_error = True  # type: ignore[attr-defined]
+                    raise err
                 raise LookupError(
                     f"trodo: could not fetch prompt {name!r}"
                     + (f" (HTTP {status})" if status else "")
@@ -248,7 +276,12 @@ class PromptManager:
             if ttl > 0:
                 self._cache.set(key, raw, ttl)
             return _to_prompt(raw, trace_label=trace_label)
-        except Exception:
+        except Exception as e:
+            # A config error is not an outage: a typo'd label silently serving
+            # the fallback forever would hide the mistake for as long as it
+            # ships. Config errors surface.
+            if getattr(e, "prompt_config_error", False):
+                raise
             stale = self._cache.get_stale(key)
             if stale is not None:
                 return _to_prompt(stale, trace_label=trace_label)