agent-engine-runner-shared 0.11.13__tar.gz → 0.11.14__tar.gz

{agent_engine_runner_shared-0.11.13 → agent_engine_runner_shared-0.11.14}/CHANGELOG.md

@@ -8,6 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Changed
+- Spans go to the platform trace endpoint (`POST /internal/traces`) by default
+  whenever `OE_URL` is set, so the OE can redact PII in them. `AGENTIC_TRACE_EXPORTER`
+  no longer needs to be `1`; set it to `0` or `false` to keep the direct MongoDB
+  path, which stores spans without redaction. `0.11.14` is the Python floor
+  for span redaction. Earlier releases write spans straight to MongoDB unless
+  `AGENTIC_TRACE_EXPORTER=1`, and the platform cannot detect this.
 - **Breaking:** the connector `tool.yaml` `auth` block no longer takes `type`.
   It names exactly one credential: `bearer: <secret>`, `basic: {username,
   password}`, `api_keys: [{env, location, name, prefix}]`, or

{agent_engine_runner_shared-0.11.13 → agent_engine_runner_shared-0.11.14}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.5
 Name: agent-engine-runner-shared
-Version: 0.11.13
+Version: 0.11.14
 Summary: Runner SDK - Framework-agnostic agent runtime
 License: Apache-2.0
 License-File: LICENSE
 Requires-Python: >=3.11
-Requires-Dist: agent-engine-sdk-memory==0.11.13
-Requires-Dist: agent-engine-sdk==0.11.13
+Requires-Dist: agent-engine-sdk-memory==0.11.14
+Requires-Dist: agent-engine-sdk==0.11.14
 Requires-Dist: fastapi>=0.141.1
 Requires-Dist: filelock>=3.0.0
 Requires-Dist: httpx-sse>=0.4.0

{agent_engine_runner_shared-0.11.13 → agent_engine_runner_shared-0.11.14}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-engine-runner-shared"
-version = "0.11.13"
+version = "0.11.14"
 description = "Runner SDK - Framework-agnostic agent runtime"
 readme = "README.md"
 license = {text = "Apache-2.0"}
@@ -27,9 +27,9 @@ dependencies = [
     "jsonschema>=4.26.0",
     "sentry-sdk>=2.27.0",
     # BaseAgent protocol and AgentInput/AgentEvent models
-    "agent-engine-sdk==0.11.13",
+    "agent-engine-sdk==0.11.14",
     # Memory models and the MemoryClient HTTP client
-    "agent-engine-sdk-memory==0.11.13",
+    "agent-engine-sdk-memory==0.11.14",
     # Required for checkpoint message decoding (query/sessions endpoints)
     "msgpack>=1.0.0",
     # Required by guardrails_evaluator/regex.py for advanced regex matching

{agent_engine_runner_shared-0.11.13 → agent_engine_runner_shared-0.11.14}/src/agent_engine_runner_shared/tracing/setup.py

@@ -63,16 +63,17 @@ _retry_thread: Optional[threading.Thread] = None
 # clients.
 _tracing_mongo_client: Optional["MongoClient"] = None
 
-# Platform trace-exporter state. The exporter is off by default and enabled
-# per workspace with the flag named by `_PLATFORM_TRACE_EXPORTER_ENV`; when on
-# (and OE_URL is set) the guest sends spans to the OE instead of writing
-# MongoDB directly. `_platform_exporter` is retained so /health can report its
-# recent export results and shutdown can reset it.
+# Platform trace-exporter state. The exporter is on whenever OE_URL is set; the
+# flag named by `_PLATFORM_TRACE_EXPORTER_ENV` only turns it off. When on, the
+# guest sends spans to the OE instead of writing MongoDB directly.
+# `_platform_exporter` is retained so /health can report its recent export
+# results and shutdown can reset it.
 _platform_exporter: Optional[PlatformSpanExporter] = None
 _platform_exporter_attached: bool = False
 
-# Feature flag: route runner spans to the OE platform trace endpoint. Off by
-# default, so an unset value keeps the MongoDB trace-store path. Deliberately
+# Opt-out for routing runner spans to the OE platform trace endpoint. Unset
+# means on. Setting it to "0" or "false" keeps the MongoDB trace-store path: the
+# OE never sees those spans, so PII redaction cannot apply to them. Deliberately
 # avoids the reserved tenant-secret prefix, which a workspace secret cannot use
 # (pkg/tenantsecrets), so a workspace can set this one directly.
 _PLATFORM_TRACE_EXPORTER_ENV = "AGENTIC_TRACE_EXPORTER"
@@ -146,13 +147,12 @@ def _otlp_endpoint_configured() -> bool:
 def platform_trace_exporter_enabled() -> bool:
     """Whether the OE platform trace exporter is enabled.
 
-    Off by default: the flag gates the rollout, so an unset (or unrecognized)
-    value keeps the MongoDB trace-store path. A workspace enables it by setting
-    the env var named by ``_PLATFORM_TRACE_EXPORTER_ENV`` to ``1`` or ``true``.
-    It is only half the condition — the exporter also needs ``OE_URL`` to know
-    where to send spans.
+    On unless the env var named by ``_PLATFORM_TRACE_EXPORTER_ENV`` is ``0`` or
+    ``false``. Any other value, including an unrecognized one, keeps it on so a
+    typo cannot silently route spans past the OE. It is only half the
+    condition — the exporter also needs ``OE_URL`` to know where to send spans.
     """
-    return os.getenv(_PLATFORM_TRACE_EXPORTER_ENV, "").strip().lower() in ("1", "true")
+    return os.getenv(_PLATFORM_TRACE_EXPORTER_ENV, "").strip().lower() not in ("0", "false")
 
 
 class ExecutionContextSpanProcessor(SpanProcessor):
@@ -237,13 +237,20 @@ def setup_tracing(
 
     provider.add_span_processor(ExecutionContextSpanProcessor())
 
-    # Destination: the OE platform trace endpoint when the feature flag is on
-    # and OE_URL is set, otherwise the caller-supplied MongoDB collection. With
-    # the flag on the OE is the platform trace path and takes precedence — a
-    # guest with both must not keep writing MongoDB directly.
+    # Destination: the OE platform trace endpoint whenever OE_URL is set,
+    # otherwise the caller-supplied MongoDB collection. The OE is the platform
+    # trace path and takes precedence — a guest with both must not keep writing
+    # MongoDB directly.
     oe_url = os.getenv("OE_URL", "").strip()
     otlp_configured = _otlp_endpoint_configured()
-    if oe_url and platform_trace_exporter_enabled():
+    use_platform = bool(oe_url) and platform_trace_exporter_enabled()
+    if oe_url and not use_platform:
+        logger.warning(
+            "Tracing: %s disables the platform trace exporter; spans go to the "
+            "trace store without PII redaction",
+            _PLATFORM_TRACE_EXPORTER_ENV,
+        )
+    if use_platform:
         _attach_platform_exporter(provider, oe_url)
     elif mongodb_collection is not None:
         provider.add_span_processor(BatchSpanProcessor(MongoDBSpanExporter(mongodb_collection)))
@@ -399,7 +406,7 @@ def tracing_status() -> dict[str, str]:
 
     ``platform_exporter`` is ``attached`` (spans are sent to the OE),
     ``degraded`` (the most recent export did not fully succeed), or
-    ``disabled`` (the feature flag is off or OE_URL unset; OTLP may still be
+    ``disabled`` (the opt-out is set or OE_URL unset; OTLP may still be
     configured).
     """
     if _platform_exporter_attached:

agent_engine_runner_shared-0.11.14/tests/unit/test_platform_trace_payload_parity.py

@@ -0,0 +1,124 @@
+"""The Python platform exporter sends the payload the TypeScript one sends.
+
+Both runner test suites decode their own request and compare it with the shared
+fixture, so a field one runner drops or renames fails here instead of in the OE.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from opentelemetry.proto.collector.trace.v1.trace_service_pb2 import ExportTraceServiceRequest
+from opentelemetry.proto.trace.v1.trace_pb2 import Span as ProtoSpan
+from opentelemetry.proto.trace.v1.trace_pb2 import Status as ProtoStatus
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import ReadableSpan
+from opentelemetry.sdk.trace.export import SpanExportResult
+from opentelemetry.trace import SpanContext, SpanKind, Status, StatusCode, TraceFlags
+
+from agent_engine_runner_shared.tracing.exporters import PlatformSpanExporter
+
+_FIXTURE = (
+    Path(__file__).resolve().parents[5] / "shared-test-fixtures" / "runner_trace_payload.json"
+)
+
+
+_PROJECT_KEY = "agentic_platform.project_id"  # open-source-refs:ignore — data contract
+
+
+class _Response:
+    status_code = 200
+    headers: dict = {}
+    content = b""
+
+
+class _Client:
+    def __init__(self) -> None:
+        self.bodies: list[bytes] = []
+
+    async def post(self, url, *, content, headers, timeout):
+        self.bodies.append(content)
+        return _Response()
+
+
+def _fixed_span() -> ReadableSpan:
+    return ReadableSpan(
+        name="agent.run",
+        context=SpanContext(
+            trace_id=0x0AF7651916CD43DD8448EB211C80319C,
+            span_id=0xB7AD6B7169203331,
+            is_remote=False,
+            trace_flags=TraceFlags(1),
+        ),
+        parent=SpanContext(
+            trace_id=0x0AF7651916CD43DD8448EB211C80319C,
+            span_id=0x00F067AA0BA902B7,
+            is_remote=False,
+        ),
+        resource=Resource({"service.name": "runner-sdk", _PROJECT_KEY: "proj-1"}),
+        attributes={
+            "session.id": "sess-1",
+            "execution.id": "exec-1",
+            "thread.id": "sess-1",
+            "workspace.id": "ws-1",
+            "llm.token_count.total": 42,
+            "custom.flag": True,
+            "ratio": 0.5,
+            "user.note": "contact jane@x.com",
+        },
+        kind=SpanKind.INTERNAL,
+        status=Status(StatusCode.OK),
+        start_time=1700000000000000001,
+        end_time=1700000001500000002,
+    )
+
+
+def _any_value(value):
+    return getattr(value, value.WhichOneof("value"))
+
+
+def _attributes(pairs) -> dict:
+    return {pair.key: _any_value(pair.value) for pair in pairs}
+
+
+def _normalize(body: bytes) -> dict:
+    request = ExportTraceServiceRequest()
+    request.ParseFromString(body)
+    spans = []
+    for resource_spans in request.resource_spans:
+        resource = _attributes(resource_spans.resource.attributes)
+        for scope_spans in resource_spans.scope_spans:
+            for span in scope_spans.spans:
+                spans.append(
+                    {
+                        "trace_id": span.trace_id.hex(),
+                        "span_id": span.span_id.hex(),
+                        "parent_span_id": span.parent_span_id.hex(),
+                        "name": span.name,
+                        "kind": ProtoSpan.SpanKind.Name(span.kind),
+                        "start_time_unix_nano": str(span.start_time_unix_nano),
+                        "end_time_unix_nano": str(span.end_time_unix_nano),
+                        "status_code": ProtoStatus.StatusCode.Name(span.status.code),
+                        "attributes": _attributes(span.attributes),
+                        "resource": resource,
+                    }
+                )
+    return {"spans": spans}
+
+
+def test_platform_payload_matches_the_shared_fixture():
+    client = _Client()
+
+    async def factory(_base: str):
+        return client
+
+    exporter = PlatformSpanExporter(
+        "http://oe:8000", client_factory=factory, cert_mtimes=lambda: None
+    )
+
+    assert exporter.export([_fixed_span()]) == SpanExportResult.SUCCESS
+
+    expected = json.loads(_FIXTURE.read_text())
+    assert len(client.bodies) == 1
+    assert _normalize(client.bodies[0]) == {"spans": expected["spans"]}

{agent_engine_runner_shared-0.11.13 → agent_engine_runner_shared-0.11.14}/tests/unit/test_platform_tracing_exporter.py

@@ -622,23 +622,22 @@ def isolated_tracing(monkeypatch):
     tracing_setup.shutdown_tracing()
 
 
-@pytest.mark.parametrize("value", ["1", "true", "TRUE", " true "])
-def test_platform_trace_exporter_enabled_accepts_truthy_values(monkeypatch, value):
+@pytest.mark.parametrize("value", ["", "1", "true", "TRUE", "yes", "off", "garbage"])
+def test_platform_trace_exporter_enabled_by_default_and_on_other_values(monkeypatch, value):
+    monkeypatch.delenv(_PLATFORM_FLAG, raising=False)
+    assert tracing_setup.platform_trace_exporter_enabled() is True
     monkeypatch.setenv(_PLATFORM_FLAG, value)
     assert tracing_setup.platform_trace_exporter_enabled() is True
 
 
-@pytest.mark.parametrize("value", ["", "0", "false", "no", "on"])
-def test_platform_trace_exporter_disabled_by_default_and_on_other_values(monkeypatch, value):
-    monkeypatch.delenv(_PLATFORM_FLAG, raising=False)
-    assert tracing_setup.platform_trace_exporter_enabled() is False
+@pytest.mark.parametrize("value", ["0", "false", "FALSE", " false "])
+def test_platform_trace_exporter_opt_out_values(monkeypatch, value):
     monkeypatch.setenv(_PLATFORM_FLAG, value)
     assert tracing_setup.platform_trace_exporter_enabled() is False
 
 
-def test_setup_tracing_installs_platform_exporter_when_flagged(monkeypatch, isolated_tracing):
+def test_setup_tracing_installs_platform_exporter_by_default(monkeypatch, isolated_tracing):
     monkeypatch.setenv("OE_URL", "http://oe:8000")
-    monkeypatch.setenv(_PLATFORM_FLAG, "1")
 
     isolated_tracing.setup_tracing(service_name="svc-platform")
 
@@ -650,9 +649,8 @@ def test_setup_tracing_installs_platform_exporter_when_flagged(monkeypatch, isol
     }
 
 
-def test_setup_tracing_flag_prefers_oe_url_over_a_mongodb_collection(monkeypatch, isolated_tracing):
+def test_setup_tracing_prefers_oe_url_over_a_mongodb_collection(monkeypatch, isolated_tracing):
     monkeypatch.setenv("OE_URL", "http://oe:8000")
-    monkeypatch.setenv(_PLATFORM_FLAG, "1")
     collection = MagicMock()
 
     isolated_tracing.setup_tracing(service_name="svc-both", mongodb_collection=collection)
@@ -661,13 +659,15 @@ def test_setup_tracing_flag_prefers_oe_url_over_a_mongodb_collection(monkeypatch
     assert isolated_tracing._mongodb_exporter_attached is False
 
 
-def test_setup_tracing_oe_url_without_flag_keeps_mongodb(monkeypatch, isolated_tracing):
-    # The flag is off by default: a live runner with OE_URL set must keep
-    # writing MongoDB directly, not silently switch to the platform exporter.
+def test_setup_tracing_opt_out_keeps_mongodb_and_warns(monkeypatch, isolated_tracing, caplog):
+    # AGENTIC_TRACE_EXPORTER=0 keeps the direct MongoDB path. Those spans skip
+    # the OE, so the opt-out must say so in the log.
     monkeypatch.setenv("OE_URL", "http://oe:8000")
+    monkeypatch.setenv(_PLATFORM_FLAG, "0")
     collection = MagicMock()
 
-    isolated_tracing.setup_tracing(service_name="svc-default", mongodb_collection=collection)
+    with caplog.at_level("WARNING"):
+        isolated_tracing.setup_tracing(service_name="svc-optout", mongodb_collection=collection)
 
     assert isolated_tracing._platform_exporter_attached is False
     assert isolated_tracing._mongodb_exporter_attached is True
@@ -675,6 +675,7 @@ def test_setup_tracing_oe_url_without_flag_keeps_mongodb(monkeypatch, isolated_t
         "database_exporter": "attached",
         "platform_exporter": "disabled",
     }
+    assert "without PII redaction" in caplog.text
 
 
 def test_setup_tracing_without_oe_url_uses_mongodb(isolated_tracing):
@@ -729,6 +730,53 @@ def test_platform_exporter_status_degrades_on_partial_success_and_recovers(isola
     assert isolated_tracing.tracing_status()["platform_exporter"] == "attached"
 
 
+def test_platform_exporter_unreachable_oe_loses_spans_and_reports_degraded(isolated_tracing):
+    # No Mongo fallback: while the OE is unreachable the batch is lost, and
+    # /health must say so rather than report attached.
+    import httpx
+
+    clock = _Clock()
+
+    def handler(_body):
+        return httpx.ConnectError("oe unreachable")
+
+    exporter, client = _exporter(handler, clock=clock, sleep=clock.advance)
+    isolated_tracing._platform_exporter = exporter
+    isolated_tracing._platform_exporter_attached = True
+
+    assert exporter.export(_make_spans(2)) == SpanExportResult.FAILURE
+
+    assert len(client.requests) > 1
+    assert exporter.last_error is not None
+    assert isolated_tracing.tracing_status()["platform_exporter"] == "degraded"
+    assert isolated_tracing._mongodb_exporter_attached is False
+
+
+def test_platform_exporter_sustained_503_backpressure_degrades_then_recovers(isolated_tracing):
+    # The OE answers 503 + Retry-After when its 16-slot admission semaphore is
+    # full. The exporter retries within its deadline, drops the batch when the
+    # OE stays saturated, and recovers on the next clean export.
+    clock = _Clock()
+    saturated = {"on": True}
+
+    def handler(_body):
+        if saturated["on"]:
+            return _Response(503, headers={"Retry-After": "1"})
+        return _Response(200)
+
+    exporter, client = _exporter(handler, clock=clock, sleep=clock.advance)
+    isolated_tracing._platform_exporter = exporter
+    isolated_tracing._platform_exporter_attached = True
+
+    assert exporter.export(_make_spans(1)) == SpanExportResult.FAILURE
+    assert len(client.requests) > 1
+    assert isolated_tracing.tracing_status()["platform_exporter"] == "degraded"
+
+    saturated["on"] = False
+    assert exporter.export(_make_spans(1)) == SpanExportResult.SUCCESS
+    assert isolated_tracing.tracing_status()["platform_exporter"] == "attached"
+
+
 def test_force_flush_tracing_is_true_when_uninitialized(isolated_tracing):
     assert isolated_tracing.force_flush_tracing() is True
 
@@ -748,8 +796,8 @@ def _capture_runtime_setup_calls(monkeypatch) -> list[dict]:
     return calls
 
 
-def test_runtime_setup_tracing_skips_the_mongo_store_when_flagged(monkeypatch):
-    """With the platform exporter flagged on and OE_URL set, the guest routes
+def test_runtime_setup_tracing_skips_the_mongo_store_by_default(monkeypatch):
+    """With OE_URL set and the opt-out unset, the guest routes
     spans to the OE and must not open the trace-store Mongo connection — the
     double-write this change exists to prevent."""
     import pymongo
@@ -757,7 +805,6 @@ def test_runtime_setup_tracing_skips_the_mongo_store_when_flagged(monkeypatch):
     import agent_engine_runner_shared.tracing as tracing_pkg
 
     monkeypatch.setenv("OE_URL", "http://oe:8000")
-    monkeypatch.setenv(_PLATFORM_FLAG, "1")
 
     setup_calls: list[dict] = []
     monkeypatch.setattr(tracing_pkg, "setup_tracing", lambda **kwargs: setup_calls.append(kwargs))
@@ -782,13 +829,13 @@ def test_runtime_setup_tracing_skips_the_mongo_store_when_flagged(monkeypatch):
     assert setup_calls == [{"service_name": "svc"}]
 
 
-def test_runtime_keeps_mongodb_path_when_flag_off(monkeypatch):
-    """A live runner (OE_URL set) without the flag must not take the OE path."""
+def test_runtime_keeps_mongodb_path_when_opted_out(monkeypatch):
+    """AGENTIC_TRACE_EXPORTER=0 must not take the OE path."""
     calls = _capture_runtime_setup_calls(monkeypatch)
     monkeypatch.setenv("OE_URL", "http://oe:8000")
-    monkeypatch.delenv(_PLATFORM_FLAG, raising=False)
+    monkeypatch.setenv(_PLATFORM_FLAG, "0")
 
-    TenantRuntime(app_name="svc-default")
+    TenantRuntime(app_name="svc-optout")
 
     # The MongoDB path passes the collection kwarg; the OE path does not.
     assert len(calls) == 1