trace-agent-server 0.3.0__tar.gz → 0.5.0__tar.gz

{trace_agent_server-0.3.0 → trace_agent_server-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trace-agent-server
-Version: 0.3.0
+Version: 0.5.0
 Summary: TraceAgent FastAPI backend server.
 Author-email: Enrique Javier Villar Cea <villarcea.enriquejavier@gmail.com>, Javier Rodriguez Castellano <javirodriguezcastellano@gmail.com>
 License: MIT

{trace_agent_server-0.3.0 → trace_agent_server-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "trace-agent-server"
-version = "0.3.0"
+version = "0.5.0"
 description = "TraceAgent FastAPI backend server."
 readme = "README.md"
 authors = [

{trace_agent_server-0.3.0 → trace_agent_server-0.5.0}/src/trace_agent_server/api/runs.py

@@ -12,7 +12,7 @@ from sqlalchemy.orm import Session
 
 from trace_agent_server.db import get_session
 from trace_agent_server.models import Artifact, Decision, Event, Run, Turn
-from trace_agent_sdk.redaction import stable_hash, summarize_value
+from trace_agent_sdk.redaction import redact_keys, stable_hash, summarize_value
 from trace_agent_server.schemas import (
     ArtifactOut,
     DashboardResponse,
@@ -36,6 +36,7 @@ from trace_agent_server.schemas import (
     TurnCreateResponse,
     TurnOut,
 )
+from trace_agent_server.services.stored_redaction import redact_messages, redact_tool_calls
 from trace_agent_server.services.analytics import build_similar_runs, build_tool_graph, build_tool_metrics
 from trace_agent_server.services.compare import compare_runs
 from trace_agent_server.services.events import create_artifact, record_event
@@ -295,6 +296,8 @@ def create_turn(
             raise HTTPException(status_code=400, detail="Input blocked by guardrails.")
 
     tool_redaction = {tool.name: tool.redact_fields for tool in payload.tools}
+    # What is stored is a masked copy; the provider and the agent keep the real data.
+    stored_messages = redact_messages(sanitized_messages, tool_redaction)
     if payload.tools:
         run.run_metadata = {
             **run.run_metadata,
@@ -315,7 +318,7 @@ def create_turn(
         provider=payload.provider,
         model=payload.model,
         payload_hash=stable_hash(sanitized_messages),
-        payload_full={"messages": sanitized_messages} if capture_full else None,
+        payload_full={"messages": stored_messages} if capture_full else None,
         metadata={
             "registered_tool_count": len(payload.tools),
             "tool_names": [tool.name for tool in payload.tools],
@@ -355,6 +358,10 @@ def create_turn(
     run.provider = payload.provider
     run.model = payload.model
 
+    stored_assistant_message = (
+        redact_messages([response.assistant_message], tool_redaction)[0] if response.assistant_message else None
+    )
+
     # Create Turn record with full messages and token usage
     usage = response.metadata.get("usage", {}) if response.metadata else {}
     turn = Turn(
@@ -362,9 +369,12 @@ def create_turn(
         seq=run.last_event_seq + 1,
         provider=payload.provider,
         model=payload.model,
-        messages=sanitized_messages,
-        assistant_message=response.assistant_message,
-        tool_calls=[{"id": c.id, "name": c.name, "arguments": c.arguments, "step_id": c.step_id} for c in response.tool_calls],
+        messages=stored_messages,
+        assistant_message=stored_assistant_message,
+        tool_calls=redact_tool_calls(
+            [{"id": c.id, "name": c.name, "arguments": c.arguments, "step_id": c.step_id} for c in response.tool_calls],
+            tool_redaction,
+        ),
         prompt_tokens=usage.get("prompt_tokens"),
         completion_tokens=usage.get("completion_tokens"),
         total_tokens=usage.get("total_tokens"),
@@ -409,7 +419,7 @@ def create_turn(
         provider=payload.provider,
         model=payload.model,
         payload_hash=stable_hash(response.assistant_message or [tool_call.__dict__ for tool_call in response.tool_calls]),
-        payload_full={"assistant_message": response.assistant_message, "tool_calls": turn.tool_calls} if capture_full else None,
+        payload_full={"assistant_message": stored_assistant_message, "tool_calls": turn.tool_calls} if capture_full else None,
         turn_id=turn.id,
         metadata=response_metadata,
     )
@@ -430,7 +440,7 @@ def create_turn(
             model=payload.model,
             tool_name=call.name,
             payload_hash=stable_hash(call.arguments),
-            payload_full={"arguments": call.arguments} if capture_full else None,
+            payload_full={"arguments": redact_keys(call.arguments, tool_redaction.get(call.name, []))} if capture_full else None,
             turn_id=turn.id,
             metadata={"call_id": call.id},
         )
@@ -962,7 +972,7 @@ def get_artifacts(run_id: str, session: Session = Depends(get_session)) -> list[
 
 
 @router.get("/runs/{run_id}/audit")
-def get_run_audit(run_id: str, session: Session = Depends(get_session)) -> dict[str, Any]:
+def get_run_audit(run_id: str, request: Request, session: Session = Depends(get_session)) -> dict[str, Any]:
     """Return a structured audit report for a run based on guardrail events."""
     run = _get_run_or_404(session, run_id)
     events = list(session.scalars(select(Event).where(Event.run_id == run_id).order_by(Event.seq)))
@@ -1020,6 +1030,8 @@ def get_run_audit(run_id: str, session: Session = Depends(get_session)) -> dict[
 
     return {
         "run_id": run_id,
+        # Without guardrails nothing is checked, so the score would only be a meaningless 100.
+        "guardrails_enabled": bool(getattr(request.app.state.settings, "audit_enable_guardrails", False)),
         "security_score": security_score,
         "pii_hit_count": pii_hit_count,
         "injection_hit_count": injection_hit_count,

{trace_agent_server-0.3.0 → trace_agent_server-0.5.0}/src/trace_agent_server/config.py

@@ -45,6 +45,8 @@ class Settings(BaseSettings):
     capture_full_payloads: bool = True
     otlp_enabled: bool = True
     otlp_max_body_bytes: int = 10_000_000
+    # A run with no event for this long is closed as failed (0 turns it off).
+    run_inactivity_timeout_seconds: int = 3600
 
     model_config = SettingsConfigDict(
         env_prefix="TRACE_AGENT_",

{trace_agent_server-0.3.0 → trace_agent_server-0.5.0}/src/trace_agent_server/main.py

@@ -1,5 +1,10 @@
 from __future__ import annotations
 
+import asyncio
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from datetime import timedelta
+
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 
@@ -9,6 +14,7 @@ from trace_agent_server.config import Settings, get_settings
 from trace_agent_server.db import Base, create_session_factory
 from trace_agent_server.services.audit_guardrails import AuditGuardrails
 from trace_agent_server.services.observability import AppObservability, configure_opentelemetry
+from trace_agent_server.services.run_lifecycle import expire_inactive_runs
 from trace_agent_server.services.provider import (
     AnthropicProviderAdapter,
     BaseProviderAdapter,
@@ -41,9 +47,38 @@ def build_provider_registry(settings: Settings) -> dict[str, BaseProviderAdapter
     return registry
 
 
+def _close_inactive_runs(app: FastAPI, timeout: timedelta) -> None:
+    with app.state.session_factory() as session:
+        expire_inactive_runs(session, timeout=timeout)
+
+
+@asynccontextmanager
+async def _lifespan(app: FastAPI) -> AsyncIterator[None]:
+    """While the server is up, close the runs whose agent disappeared without finishing them."""
+    seconds = app.state.settings.run_inactivity_timeout_seconds
+    task: asyncio.Task[None] | None = None
+    if seconds > 0:
+        timeout = timedelta(seconds=seconds)
+
+        async def sweep() -> None:
+            while True:
+                await asyncio.sleep(min(60.0, max(1.0, seconds / 4)))
+                try:
+                    await asyncio.to_thread(_close_inactive_runs, app, timeout)
+                except Exception:  # a failed sweep must never take the server down; try again next time
+                    pass
+
+        task = asyncio.create_task(sweep())
+    try:
+        yield
+    finally:
+        if task is not None:
+            task.cancel()
+
+
 def create_app(settings: Settings | None = None) -> FastAPI:
     current_settings = settings or get_settings()
-    app = FastAPI(title=current_settings.app_name)
+    app = FastAPI(title=current_settings.app_name, lifespan=_lifespan)
     app.add_middleware(
         CORSMiddleware,
         allow_origins=current_settings.cors_origins,

{trace_agent_server-0.3.0 → trace_agent_server-0.5.0}/src/trace_agent_server/services/otlp.py

@@ -89,6 +89,18 @@ def _parse_json(value: Any) -> Any:
         return value
 
 
+def _readable(text: Any) -> Any:
+    """Decode the \\uXXXX escapes of a JSON text, so accents show as typed.
+
+    Some producers serialize results with json.dumps defaults, which escapes every non-ASCII character.
+    """
+    if isinstance(text, str) and "\\u" in text:
+        parsed = _parse_json(text)
+        if parsed is not text:
+            return parsed
+    return text
+
+
 def _error_of(span: SpanRecord) -> tuple[str, str]:
     """Error code (the exception class name) and message of a failed span."""
     for event in span.events:
@@ -347,7 +359,7 @@ def _tool_steps(session: Session, run: Run, span: SpanRecord, capture_full: bool
         parent_step_id=span.parent_span_id,
         status="failed" if failed else "succeeded",
         args=redact_payload(arguments if isinstance(arguments, dict) else {"input": arguments} if arguments is not None else {}),
-        output_summary=summarize_value(result_text) if result_text is not None else None,
+        output_summary=summarize_value(_readable(result_text)) if result_text is not None else None,
         output_hash=stable_hash(result_text if not failed else {"error": message}),
         error_code=code,
         error_summary=message,

{trace_agent_server-0.3.0 → trace_agent_server-0.5.0}/src/trace_agent_server/services/run_lifecycle.py

@@ -3,9 +3,10 @@
 from __future__ import annotations
 
 from collections.abc import Sequence
-from datetime import datetime
+from datetime import datetime, timedelta
 from typing import Any
 
+from sqlalchemy import select
 from sqlalchemy.orm import Session
 
 from trace_agent_sdk.redaction import stable_hash, summarize_value
@@ -213,3 +214,23 @@ def fail_run_with(
         timestamp=ended_at,
     )
     derive_explanation(session, run)
+
+
+def expire_inactive_runs(session: Session, *, timeout: timedelta, now: datetime | None = None) -> int:
+    """Fail the runs that are still running but have had no event for ``timeout``.
+
+    An agent that dies without calling finish or fail would otherwise stay "running" forever and keep
+    counting as active. Returns how many runs were closed.
+    """
+    now = now or utcnow()
+    stale = list(session.scalars(select(Run).where(Run.status == "running", Run.updated_at < now - timeout)))
+    minutes = max(1, int(timeout.total_seconds() // 60))
+    for run in stale:
+        fail_run_with(
+            session,
+            run,
+            "RunAbandoned",
+            f"No activity for {minutes} minutes: the agent stopped without finishing the run.",
+        )
+    session.commit()
+    return len(stale)

trace_agent_server-0.5.0/src/trace_agent_server/services/stored_redaction.py

@@ -0,0 +1,57 @@
+"""Copies of a model turn with the sensitive keys of each tool masked, for what the server stores.
+
+The provider and the agent still get the real data; only what is saved (events, turns) is masked.
+A tool names its sensitive keys with ``redact_fields``; they apply to that tool's arguments and result.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from trace_agent_sdk.redaction import redact_keys
+
+
+def _redact_json_text(text: Any, fields: list[str]) -> Any:
+    if not fields or not isinstance(text, str):
+        return text
+    try:
+        parsed = json.loads(text)
+    except ValueError:
+        return text
+    return json.dumps(redact_keys(parsed, fields), ensure_ascii=False)
+
+
+def redact_messages(messages: list[dict[str, Any]], tool_redaction: dict[str, list[str]]) -> list[dict[str, Any]]:
+    """The conversation with the arguments and results of each tool masked."""
+    if not any(tool_redaction.values()):
+        return messages
+
+    tool_names: dict[str, str] = {}
+    for message in messages:
+        for call in message.get("tool_calls") or []:
+            tool_names[str(call.get("id"))] = str((call.get("function") or {}).get("name"))
+
+    redacted: list[dict[str, Any]] = []
+    for message in messages:
+        message = dict(message)
+        if message.get("role") == "tool":
+            fields = tool_redaction.get(tool_names.get(str(message.get("tool_call_id")), ""), [])
+            message["content"] = _redact_json_text(message.get("content"), fields)
+        if message.get("tool_calls"):
+            calls = []
+            for call in message["tool_calls"]:
+                function = dict(call.get("function") or {})
+                function["arguments"] = _redact_json_text(function.get("arguments"), tool_redaction.get(str(function.get("name")), []))
+                calls.append({**call, "function": function})
+            message["tool_calls"] = calls
+        redacted.append(message)
+    return redacted
+
+
+def redact_tool_calls(tool_calls: list[dict[str, Any]], tool_redaction: dict[str, list[str]]) -> list[dict[str, Any]]:
+    """Tool calls ({"name", "arguments", ...}) with the arguments of each tool masked."""
+    return [
+        {**call, "arguments": redact_keys(call.get("arguments"), tool_redaction.get(str(call.get("name")), []))}
+        for call in tool_calls
+    ]

{trace_agent_server-0.3.0 → trace_agent_server-0.5.0}/src/trace_agent_server.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trace-agent-server
-Version: 0.3.0
+Version: 0.5.0
 Summary: TraceAgent FastAPI backend server.
 Author-email: Enrique Javier Villar Cea <villarcea.enriquejavier@gmail.com>, Javier Rodriguez Castellano <javirodriguezcastellano@gmail.com>
 License: MIT

{trace_agent_server-0.3.0 → trace_agent_server-0.5.0}/src/trace_agent_server.egg-info/SOURCES.txt

@@ -30,10 +30,12 @@ src/trace_agent_server/services/otlp_decode.py
 src/trace_agent_server/services/provider.py
 src/trace_agent_server/services/run_lifecycle.py
 src/trace_agent_server/services/run_summary.py
+src/trace_agent_server/services/stored_redaction.py
 tests/test_audit_guardrails_api.py
 tests/test_dashboard.py
 tests/test_events.py
 tests/test_framework_observations.py
+tests/test_inactivity_sweep.py
 tests/test_otlp_decode.py
 tests/test_otlp_ingest.py
 tests/test_providers.py
@@ -41,4 +43,5 @@ tests/test_run_lifecycle.py
 tests/test_runs_api.py
 tests/test_sdk_wrappers.py
 tests/test_sse.py
+tests/test_stored_redaction.py
 tests/test_turns.py

{trace_agent_server-0.3.0 → trace_agent_server-0.5.0}/tests/test_audit_guardrails_api.py

@@ -137,3 +137,19 @@ def test_metrics_endpoint_is_available_when_enabled(tmp_path) -> None:
     body = metrics.text
     assert "TRACE_AGENT_http_requests_total" in body
     assert "TRACE_AGENT_http_request_duration_seconds" in body
+
+
+def test_audit_says_guardrails_are_off_by_default(tmp_path) -> None:
+    client = build_client(tmp_path, CountingProvider())
+
+    report = client.get(f"/api/runs/{_create_run(client)}/audit").json()
+
+    assert report["guardrails_enabled"] is False
+
+
+def test_audit_says_guardrails_are_on_when_enabled(tmp_path) -> None:
+    client = build_client(tmp_path, CountingProvider(), audit_enable_guardrails=True)
+
+    report = client.get(f"/api/runs/{_create_run(client)}/audit").json()
+
+    assert report["guardrails_enabled"] is True

trace_agent_server-0.5.0/tests/test_inactivity_sweep.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import time
+
+from fastapi.testclient import TestClient
+
+from trace_agent_server.config import Settings
+from trace_agent_server.main import create_app
+
+
+def build_app(tmp_path, timeout_seconds: int):
+    return create_app(
+        Settings(
+            database_url=f"sqlite:///{tmp_path / 'sweep.db'}",
+            cors_origins=["http://localhost:5173"],
+            run_inactivity_timeout_seconds=timeout_seconds,
+        )
+    )
+
+
+def wait_for_status(client: TestClient, run_id: str, status: str, seconds: float) -> str:
+    deadline = time.time() + seconds
+    current = ""
+    while time.time() < deadline:
+        current = client.get(f"/api/runs/{run_id}").json()["status"]
+        if current == status:
+            break
+        time.sleep(0.25)
+    return current
+
+
+class TestInactivitySweep:
+    def test_a_running_server_closes_a_run_whose_agent_disappeared(self, tmp_path) -> None:
+        with TestClient(build_app(tmp_path, timeout_seconds=1)) as client:
+            run_id = client.post("/api/runs", json={"agent_name": "a", "goal": "g"}).json()["run_id"]
+
+            assert wait_for_status(client, run_id, "failed", seconds=8) == "failed"
+
+            events = client.get(f"/api/runs/{run_id}/events").json()
+            events = events if isinstance(events, list) else events["events"]
+            assert events[-1]["type"] == "run.failed"
+            assert events[-1]["error_code"] == "RunAbandoned"
+
+    def test_a_timeout_of_zero_turns_the_sweep_off(self, tmp_path) -> None:
+        with TestClient(build_app(tmp_path, timeout_seconds=0)) as client:
+            run_id = client.post("/api/runs", json={"agent_name": "a", "goal": "g"}).json()["run_id"]
+
+            time.sleep(2.5)
+
+            assert client.get(f"/api/runs/{run_id}").json()["status"] == "running"

{trace_agent_server-0.3.0 → trace_agent_server-0.5.0}/tests/test_otlp_ingest.py

@@ -433,6 +433,40 @@ class TestPrivacy:
         assert len(next(e for e in events if e.type == "tool.succeeded").summary) <= 220
 
 
+class TestNonAsciiText:
+    def test_accents_in_a_tool_result_are_shown_as_typed(self, client) -> None:
+        spans = agent_spans()
+        spans[2].attributes["gen_ai__tool__call__result"] = json.dumps({"mensaje": "El OEE bajó"}, ensure_ascii=False)
+
+        post(client, export(*spans))
+
+        _, events = load(client)
+        summary = next(e for e in events if e.type == "tool.succeeded").summary
+        assert "El OEE bajó" in summary
+        assert "\\u" not in summary
+
+    def test_a_result_escaped_by_the_producer_is_decoded(self, client) -> None:
+        spans = agent_spans()
+        spans[2].attributes["gen_ai__tool__call__result"] = json.dumps({"mensaje": "El OEE bajó"})
+        assert "\\u00f3" in spans[2].attributes["gen_ai__tool__call__result"]
+
+        post(client, export(*spans))
+
+        _, events = load(client)
+        summary = next(e for e in events if e.type == "tool.succeeded").summary
+        assert "El OEE bajó" in summary
+        assert "\\u" not in summary
+
+    def test_a_plain_text_result_with_a_backslash_is_left_alone(self, client) -> None:
+        spans = agent_spans()
+        spans[2].attributes["gen_ai__tool__call__result"] = r"path C:\users\ana"
+
+        post(client, export(*spans))
+
+        _, events = load(client)
+        assert next(e for e in events if e.type == "tool.succeeded").summary == r"path C:\users\ana"
+
+
 class TestEndpoint:
     def test_the_response_is_a_valid_protobuf_export_response(self, client) -> None:
         response = post(client, export(*agent_spans()))

{trace_agent_server-0.3.0 → trace_agent_server-0.5.0}/tests/test_run_lifecycle.py

@@ -13,6 +13,7 @@ from trace_agent_server.services.events import record_event
 from trace_agent_server.services.run_lifecycle import (
     apply_llm_usage,
     complete_run,
+    expire_inactive_runs,
     fail_run_with,
     record_tool_result,
     token_count,
@@ -115,3 +116,44 @@ class TestRunEnd:
         assert (run.status, run.error_count, run.final_output_summary) == ("failed", 1, "boom")
         last = events_of(session, run)[-1]
         assert (last.type, last.error_code) == ("run.failed", "ValueError")
+
+
+class TestExpireInactiveRuns:
+    def stale_run(self, session, *, minutes_ago: int, status: str = "running") -> Run:
+        run = Run(agent_name="agent", goal="goal", status=status)
+        session.add(run)
+        session.flush()
+        run.updated_at = START - timedelta(minutes=minutes_ago)
+        session.flush()
+        return run
+
+    def test_a_run_with_no_activity_is_failed_with_a_clear_reason(self, session) -> None:
+        run = self.stale_run(session, minutes_ago=90)
+
+        closed = expire_inactive_runs(session, timeout=timedelta(minutes=60), now=START)
+
+        assert closed == 1
+        assert run.status == "failed"
+        assert "No activity for 60 minutes" in run.final_output_summary
+        last = events_of(session, run)[-1]
+        assert (last.type, last.error_code) == ("run.failed", "RunAbandoned")
+
+    def test_a_recent_run_is_left_running(self, session) -> None:
+        run = self.stale_run(session, minutes_ago=5)
+
+        assert expire_inactive_runs(session, timeout=timedelta(minutes=60), now=START) == 0
+        assert run.status == "running"
+
+    def test_finished_runs_are_not_touched(self, session) -> None:
+        run = self.stale_run(session, minutes_ago=500, status="completed")
+
+        assert expire_inactive_runs(session, timeout=timedelta(minutes=60), now=START) == 0
+        assert run.status == "completed"
+
+    def test_an_active_run_keeps_going_as_events_arrive(self, session) -> None:
+        run = self.stale_run(session, minutes_ago=90)
+        record_event(session, run, actor="sdk", event_type="tool.started", summary="still working", timestamp=START)
+        run.updated_at = START
+
+        assert expire_inactive_runs(session, timeout=timedelta(minutes=60), now=START) == 0
+        assert run.status == "running"

trace_agent_server-0.5.0/tests/test_stored_redaction.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import json
+
+import pytest
+from fastapi.testclient import TestClient
+
+from trace_agent_sdk import TraceAgentClient
+from trace_agent_server.config import Settings
+from trace_agent_server.main import create_app
+from trace_agent_server.models import Event, Turn
+from trace_agent_server.services.provider import ProviderToolCall, ProviderTurnRequest, ProviderTurnResponse
+from trace_agent_server.services.stored_redaction import redact_messages, redact_tool_calls
+
+SECRET = "SECRET-KEY-123"
+CARD = "4111111111111111"
+
+
+class ChargingProvider:
+    """Asks for the `charge` tool once, then answers. Keeps what it was sent."""
+
+    provider_name = "openai"
+
+    def __init__(self) -> None:
+        self.seen: list[list[dict]] = []
+
+    def generate_turn(self, request: ProviderTurnRequest) -> ProviderTurnResponse:
+        self.seen.append(request.messages)
+        if not any(m.get("role") == "tool" for m in request.messages):
+            return ProviderTurnResponse(
+                assistant_message={
+                    "role": "assistant",
+                    "content": None,
+                    "tool_calls": [
+                        {"id": "call_1", "type": "function", "function": {"name": "charge", "arguments": json.dumps({"customer": "ana", "api_key": SECRET})}}
+                    ],
+                },
+                tool_calls=[ProviderToolCall(id="call_1", name="charge", arguments={"customer": "ana", "api_key": SECRET}, step_id="step-1")],
+                summary="calls charge",
+            )
+        return ProviderTurnResponse(assistant_message={"role": "assistant", "content": "Charged."}, summary="Charged.")
+
+
+@pytest.fixture
+def provider() -> ChargingProvider:
+    return ChargingProvider()
+
+
+@pytest.fixture
+def client(tmp_path, provider) -> TestClient:
+    app = create_app(Settings(database_url=f"sqlite:///{tmp_path / 'test.db'}", cors_origins=["http://localhost:5173"]))
+    app.state.provider_registry = {"openai": provider}
+    return TestClient(app)
+
+
+def everything_stored(client: TestClient) -> str:
+    with client.app.state.session_factory() as session:
+        events = [(e.summary, e.payload_full, e.event_metadata) for e in session.query(Event).all()]
+        turns = [(t.messages, t.assistant_message, t.tool_calls) for t in session.query(Turn).all()]
+    return json.dumps([events, turns], default=str)
+
+
+class TestToolRedactionOnStoredData:
+    def run_agent(self, client: TestClient, redact_fields: list[str]):
+        run = TraceAgentClient("http://testserver", http_client=client).start_run("billing", "Charge ana")
+        received: dict = {}
+
+        @run.tool(name="charge", description="Charge a customer.", redact_fields=redact_fields)
+        def charge(customer: str, api_key: str) -> dict:
+            received["args"] = {"customer": customer, "api_key": api_key}
+            return {"ok": True, "customer": customer, "card": CARD}
+
+        result = run.create_model_turn([{"role": "user", "content": "Charge ana"}], model="m")
+        run.finish(result.assistant_message["content"])
+        return received, result
+
+    def test_nothing_sensitive_is_stored_anywhere(self, client, provider) -> None:
+        self.run_agent(client, ["api_key", "card"])
+
+        stored = everything_stored(client)
+        assert SECRET not in stored
+        assert CARD not in stored
+        assert "[redacted]" in stored
+
+    def test_the_tool_and_the_model_still_get_the_real_data(self, client, provider) -> None:
+        received, _ = self.run_agent(client, ["api_key", "card"])
+
+        assert received["args"] == {"customer": "ana", "api_key": SECRET}
+        tool_message = next(m for m in provider.seen[-1] if m.get("role") == "tool")
+        assert CARD in tool_message["content"]
+
+    def test_the_agent_is_handed_the_real_tool_call_arguments(self, client, provider) -> None:
+        _, result = self.run_agent(client, ["api_key", "card"])
+
+        assert result.executed_tools[0]["status"] == "succeeded"
+
+    def test_without_redact_fields_the_data_is_stored_as_before(self, client, provider) -> None:
+        self.run_agent(client, [])
+
+        assert SECRET in everything_stored(client)
+
+    def test_other_values_are_kept_in_full(self, client, provider) -> None:
+        self.run_agent(client, ["api_key"])
+
+        stored = everything_stored(client)
+        assert "ana" in stored
+        assert CARD in stored  # `card` was not listed, so it is not masked
+
+
+class TestRedactMessages:
+    def test_masks_the_arguments_of_a_call_and_the_result_of_its_tool(self) -> None:
+        messages = [
+            {"role": "user", "content": "hi"},
+            {"role": "assistant", "content": None, "tool_calls": [{"id": "c1", "type": "function", "function": {"name": "charge", "arguments": json.dumps({"api_key": "k", "n": 1})}}]},
+            {"role": "tool", "tool_call_id": "c1", "content": json.dumps({"card": "4111", "ok": True})},
+        ]
+
+        masked = redact_messages(messages, {"charge": ["api_key", "card"]})
+
+        assert json.loads(masked[1]["tool_calls"][0]["function"]["arguments"]) == {"api_key": "[redacted]", "n": 1}
+        assert json.loads(masked[2]["content"]) == {"card": "[redacted]", "ok": True}
+        assert messages[2]["content"] == json.dumps({"card": "4111", "ok": True})  # the original is untouched
+
+    def test_a_tool_without_redact_fields_and_plain_text_are_left_alone(self) -> None:
+        messages = [
+            {"role": "assistant", "tool_calls": [{"id": "c1", "function": {"name": "other", "arguments": '{"a": 1}'}}]},
+            {"role": "tool", "tool_call_id": "c1", "content": "plain text"},
+        ]
+
+        assert redact_messages(messages, {"charge": ["api_key"]}) == messages
+        assert redact_messages(messages, {}) is messages
+
+    def test_accents_survive_the_masking(self) -> None:
+        messages = [
+            {"role": "assistant", "tool_calls": [{"id": "c1", "function": {"name": "t", "arguments": json.dumps({"pw": "x", "msg": "bajó"}, ensure_ascii=False)}}]},
+        ]
+
+        masked = redact_messages(messages, {"t": ["pw"]})
+
+        assert "bajó" in masked[0]["tool_calls"][0]["function"]["arguments"]
+
+
+class TestRedactToolCalls:
+    def test_masks_the_arguments_of_the_listed_tools(self) -> None:
+        calls = [{"id": "c1", "name": "charge", "arguments": {"api_key": "k", "n": 1}, "step_id": "s"}]
+
+        assert redact_tool_calls(calls, {"charge": ["api_key"]})[0]["arguments"] == {"api_key": "[redacted]", "n": 1}
+        assert calls[0]["arguments"]["api_key"] == "k"