CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.
Python agent-frameworkagent-harnessagent-runtimeagentic-aiai-agentsai-frameworkanthropicharnessharness-engineeringharness-frameworklanggraphlanggraph-alternativellmmcpopenaipi-agentpi-agent-corepythonpython-agent
"""The ``trace`` best-effort scope helper.
``trace(tracer, agent)`` is a context manager that attaches the tracer on
enter and detaches + flushes on exit, swallowing every tracing fault so that
tracing can never break or fail the wrapped work. ``tracer=None`` is a no-op.
These tests pin that contract: attach/detach lifecycle on the happy path, and
silent fallback on attach / flush failures.
"""
from __future__ import annotations
import asyncio
import pytest
from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
from cubeloop.agent.agent import Agent
from cubeloop.providers.base import Model
from cubeloop.providers.faux import FauxProvider
from cubeloop.tracing import Tracer, trace
MODEL = Model(id="faux-1", provider_id="faux")
class _NullExporter(SpanExporter):
def export(self, spans): # noqa: ANN001
return SpanExportResult.SUCCESS
def shutdown(self) -> None:
pass
def force_flush(self, timeout_millis: int = 30_000) -> bool:
return True
def _build() -> tuple[Agent, FauxProvider, Tracer]:
provider = FauxProvider(provider_id="faux")
agent = Agent(model=provider.model(MODEL.id), system_prompt="t")
tracer = Tracer(
service_name="t",
agent_name="t",
exporters=[_NullExporter()],
atexit_flush=False,
)
return agent, provider, tracer
async def test_trace_none_is_noop():
agent, _provider, tracer = _build()
try:
ran = False
async with trace(None, agent):
ran = True
assert ran
assert agent._listeners == [], (
"no listeners should be attached when tracer is None"
)
finally:
await tracer.shutdown()
async def test_trace_attaches_within_scope_and_detaches_after():
agent, provider, tracer = _build()
try:
assert agent._listeners == []
async with trace(tracer, agent):
assert len(agent._listeners) == 1, (
"recorder should be attached inside the scope"
)
assert len(provider._request_listeners) == 1
assert len(provider._chunk_listeners) == 1
assert len(provider._response_listeners) == 1
assert agent._listeners == [], "recorder should be detached after the scope"
assert provider._request_listeners == []
assert provider._chunk_listeners == []
assert provider._response_listeners == []
finally:
await tracer.shutdown()
async def test_trace_swallows_attach_failure(monkeypatch):
agent, _provider, tracer = _build()
try:
def _boom(_listener): # noqa: ANN202
raise RuntimeError("attach boom")
monkeypatch.setattr(agent, "subscribe", _boom)
ran = False
async with trace(tracer, agent): # must not raise
ran = True
assert ran, "body must run even when attach fails"
finally:
await tracer.shutdown()
async def test_trace_swallows_flush_failure(monkeypatch):
agent, provider, tracer = _build()
try:
async def _boom_flush(*_args, **_kwargs): # noqa: ANN202
raise RuntimeError("flush boom")
monkeypatch.setattr(tracer, "force_flush", _boom_flush)
ran = False
async with trace(tracer, agent):
ran = True
assert ran, "body must run even when flush fails on exit"
# Synchronous detach still ran before the flush failure.
assert agent._listeners == []
assert provider._request_listeners == []
finally:
# Restore the real force_flush so shutdown() can clean up.
monkeypatch.undo()
await tracer.shutdown()
async def test_trace_swallows_detach_failure(monkeypatch):
agent, _provider, tracer = _build()
try:
def _raising_detach(): # noqa: ANN202
raise RuntimeError("detach boom")
monkeypatch.setattr(tracer, "attach", lambda _agent: _raising_detach)
ran = False
async with trace(tracer, agent): # must not raise
ran = True
assert ran, "body must run even when the detach callable itself raises"
finally:
await tracer.shutdown()
async def test_trace_awaits_flush_task_on_exit(monkeypatch):
agent, _provider, tracer = _build()
flushed = {"done": False}
async def _flush() -> None:
await asyncio.sleep(0)
flushed["done"] = True
def _detach(): # noqa: ANN202
return asyncio.get_running_loop().create_task(_flush())
monkeypatch.setattr(tracer, "attach", lambda _agent: _detach)
try:
async with trace(tracer, agent):
pass
assert flushed["done"], "trace must await the flush task before the scope exits"
finally:
await tracer.shutdown()
async def test_trace_preserves_body_exception_when_cleanup_fails(monkeypatch):
agent, _provider, tracer = _build()
class _Sentinel(Exception):
pass
def _raising_detach(): # noqa: ANN202
raise RuntimeError("detach boom")
monkeypatch.setattr(tracer, "attach", lambda _agent: _raising_detach)
try:
with pytest.raises(_Sentinel):
async with trace(tracer, agent):
raise _Sentinel("body failed")
finally:
await tracer.shutdown()
async def test_trace_swallows_mcp_unregister_failure(monkeypatch):
# Real attach registers the MCP provider; make unregister blow up on detach.
# The body must still run and the failure must not propagate.
agent, _provider, tracer = _build()
import cubeloop.mcp._tracing as mcp_tracing
baseline = len(mcp_tracing._provider_stack)
try:
def _boom(_token): # noqa: ANN202
raise RuntimeError("unregister boom")
monkeypatch.setattr(mcp_tracing, "unregister_provider", _boom)
ran = False
async with trace(tracer, agent):
ran = True
assert ran, "body must run even when MCP unregister fails on detach"
finally:
# The patched unregister raised before popping, so restore the
# module-level provider stack to avoid polluting later tests.
del mcp_tracing._provider_stack[baseline:]
await tracer.shutdown()
async def test_trace_does_not_shutdown_tracer(monkeypatch):
agent, _provider, tracer = _build()
calls = {"n": 0}
async def _spy_shutdown(*_args, **_kwargs) -> None: # noqa: ANN202
calls["n"] += 1
monkeypatch.setattr(tracer, "shutdown", _spy_shutdown)
async with trace(tracer, agent):
pass
assert calls["n"] == 0, "trace must not shut the tracer down — the owner does"
# Real cleanup.
monkeypatch.undo()
await tracer.shutdown()