trodo-python 2.1.0__tar.gz → 2.3.0__tar.gz

{trodo_python-2.1.0 → trodo_python-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trodo-python
-Version: 2.1.0
+Version: 2.3.0
 Summary: Trodo Analytics SDK for Python — server-side event tracking
 License: ISC
 Keywords: analytics,tracking,trodo,server-side
@@ -263,6 +263,34 @@ with trodo.join_run(
     ...
 ```
 
+### Long-lived sessions across processes — `start_run` / `end_run`
+
+`wrap_agent` is a context manager — it opens *and* closes the run in one
+call stack. For sessions that live across many HTTP requests (an MCP
+server, a websocket-pinned chat, scheduled jobs that resume on different
+workers), use `start_run` to open the run from one process and `end_run`
+to finalise it later. Between the two, any process can use `join_run` to
+add child spans. Same `run_id` threads through everything.
+
+```python
+# Process A — open the run for an MCP session.
+run_id = trodo.start_run(
+    'external_mcp_session',
+    distinct_id=str(user_id),
+    conversation_id=mcp_session_id,
+)
+redis.set(f"mcp:run:{mcp_session_id}", run_id, ex=3600)
+
+# Process B (later, possibly a different worker) — append a tool span.
+run_id = redis.get(f"mcp:run:{mcp_session_id}").decode()
+with trodo.join_run(run_id, name='tool.run_funnel_query', kind='tool') as span:
+    span.set_input(args)
+    span.set_output(result)
+
+# When the session ends (timeout sweeper, explicit close):
+trodo.end_run(run_id, status='ok')
+```
+
 ### Conversation binding & feedback
 
 ```python

{trodo_python-2.1.0 → trodo_python-2.3.0}/README.md

@@ -236,6 +236,34 @@ with trodo.join_run(
     ...
 ```
 
+### Long-lived sessions across processes — `start_run` / `end_run`
+
+`wrap_agent` is a context manager — it opens *and* closes the run in one
+call stack. For sessions that live across many HTTP requests (an MCP
+server, a websocket-pinned chat, scheduled jobs that resume on different
+workers), use `start_run` to open the run from one process and `end_run`
+to finalise it later. Between the two, any process can use `join_run` to
+add child spans. Same `run_id` threads through everything.
+
+```python
+# Process A — open the run for an MCP session.
+run_id = trodo.start_run(
+    'external_mcp_session',
+    distinct_id=str(user_id),
+    conversation_id=mcp_session_id,
+)
+redis.set(f"mcp:run:{mcp_session_id}", run_id, ex=3600)
+
+# Process B (later, possibly a different worker) — append a tool span.
+run_id = redis.get(f"mcp:run:{mcp_session_id}").decode()
+with trodo.join_run(run_id, name='tool.run_funnel_query', kind='tool') as span:
+    span.set_input(args)
+    span.set_output(result)
+
+# When the session ends (timeout sweeper, explicit close):
+trodo.end_run(run_id, status='ok')
+```
+
 ### Conversation binding & feedback
 
 ```python

{trodo_python-2.1.0 → trodo_python-2.3.0}/pyproject.toml

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

trodo_python-2.3.0/tests/test_cross_process_session.py

@@ -0,0 +1,86 @@
+"""End-to-end test of the new MCP-style flow:
+
+  1. process A calls start_run, gets back run_id, persists it (Redis in prod)
+  2. process B receives a request, looks up run_id, uses join_run to add a span
+  3. eventually process C (or a sweeper) calls end_run
+
+This is the use case `start_run`/`end_run` were added to support, and is
+*not* expressible with `wrap_agent` alone (it's a single-context-manager block).
+"""
+from __future__ import annotations
+
+from trodo.otel.processor import TrodoSpanProcessor
+from trodo.otel.wrap_agent import start_run, end_run, join_run
+
+
+def test_caller_supplied_run_id_threads_through(http):
+    proc_a = TrodoSpanProcessor(http_client=http)
+    proc_b = TrodoSpanProcessor(http_client=http)  # different process
+
+    # Process A: open the session run.
+    rid = start_run(
+        processor=proc_a,
+        agent_name="external_mcp_session",
+        run_id="aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
+        conversation_id="mcp-sess-42",
+    )
+    assert rid == "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
+
+    # Process B: receive a tools/call request, look up rid from Redis (here
+    # we just have it), append a tool span via join_run.
+    with join_run(
+        processor=proc_b,
+        team_site_id="site-x",
+        run_id=rid,
+        name="tool.run_funnel_query",
+        kind="tool",
+    ) as span:
+        span.set_input({"team_id": "team-1"})
+        span.set_output({"status": "ok"})
+
+    # Process C (sweeper): finalise.
+    end_run(rid, processor=proc_a, output={"calls": 1}, status="ok")
+
+    # Verify wire shape:
+    assert len(http.run_start) == 1, "exactly one /runs/start"
+    assert http.run_start[0]["run"]["run_id"] == rid
+    assert http.run_start[0]["run"]["conversation_id"] == "mcp-sess-42"
+
+    assert len(http.spans_append) == 1, "join_run flushes span via /runs/{id}/spans"
+    sent_rid, spans = http.spans_append[0]
+    assert sent_rid == rid
+    assert spans[0]["name"] == "tool.run_funnel_query"
+    assert spans[0]["kind"] == "tool"
+    assert spans[0]["run_id"] == rid
+
+    assert len(http.run_end) == 1, "exactly one /runs/{id}/end"
+    end_rid, end_payload = http.run_end[0]
+    assert end_rid == rid
+    assert end_payload["status"] == "ok"
+    assert "calls" in end_payload["output"]
+
+
+def test_multiple_join_runs_share_run_id(http):
+    proc_a = TrodoSpanProcessor(http_client=http)
+    proc_b = TrodoSpanProcessor(http_client=http)
+
+    rid = start_run(processor=proc_a, agent_name="session")
+
+    # Three tool calls from three different worker processes.
+    for i, tool in enumerate(["tool.a", "tool.b", "tool.c"]):
+        with join_run(
+            processor=proc_b,
+            team_site_id="site-x",
+            run_id=rid,
+            name=tool,
+            kind="tool",
+        ) as span:
+            span.set_attribute("call_idx", i)
+
+    end_run(rid, processor=proc_a)
+
+    # All three spans hit /runs/{id}/spans with the same run_id.
+    assert len(http.spans_append) == 3
+    for sent_rid, spans in http.spans_append:
+        assert sent_rid == rid
+        assert spans[0]["run_id"] == rid

trodo_python-2.3.0/tests/test_end_run.py

@@ -0,0 +1,90 @@
+"""Tests for trodo.otel.wrap_agent.end_run module function."""
+from __future__ import annotations
+
+from trodo.otel.processor import TrodoSpan
+from trodo.otel.wrap_agent import start_run, end_run
+
+
+def _make_span(run_id: str, *, kind: str = "tool", status: str = "ok",
+               input_tokens: int = 10, output_tokens: int = 20, cost: float = 0.001):
+    return TrodoSpan(
+        span_id="span-1",
+        run_id=run_id,
+        parent_span_id=None,
+        kind=kind,
+        name="step",
+        status=status,
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        cost=cost,
+    )
+
+
+def test_posts_to_runs_end_endpoint(processor, http):
+    rid = start_run(processor=processor, agent_name="session")
+    end_run(rid, processor=processor, output={"done": True}, status="ok")
+
+    assert len(http.run_end) == 1
+    sent_run_id, payload = http.run_end[0]
+    assert sent_run_id == rid
+    assert payload["status"] == "ok"
+    assert "ended_at" in payload
+    assert "done" in payload["output"]
+
+
+def test_aggregates_pending_spans(processor, http):
+    rid = start_run(processor=processor, agent_name="session")
+    # Inject two completed spans into the local buffer (bypass joined-flush
+    # by directly populating; the real path goes through enqueue_span which
+    # already flushes for joined runs).
+    processor._pending[rid] = [
+        _make_span(rid, kind="tool", input_tokens=5, output_tokens=10, cost=0.001),
+        _make_span(rid, kind="llm", input_tokens=15, output_tokens=30, cost=0.002),
+    ]
+    end_run(rid, processor=processor)
+
+    _, payload = http.run_end[0]
+    assert payload["total_tokens_in"] == 20
+    assert payload["total_tokens_out"] == 40
+    assert round(payload["total_cost"], 6) == 0.003
+    assert payload["span_count"] == 2
+    assert payload["tool_count"] == 1
+    assert payload["error_count"] == 0
+
+
+def test_records_error_status(processor, http):
+    rid = start_run(processor=processor, agent_name="session")
+    end_run(rid, processor=processor, status="error", error_summary="boom")
+    _, payload = http.run_end[0]
+    assert payload["status"] == "error"
+    assert payload["error_summary"] == "boom"
+
+
+def test_unmarks_joined(processor, http):
+    rid = start_run(processor=processor, agent_name="session")
+    assert rid in processor._joined_runs
+    end_run(rid, processor=processor)
+    assert rid not in processor._joined_runs
+
+
+def test_clears_pending_after_end(processor, http):
+    rid = start_run(processor=processor, agent_name="session")
+    processor._pending[rid] = [_make_span(rid)]
+    end_run(rid, processor=processor)
+    # unmark_joined() drops the bucket.
+    assert processor._pending.get(rid, []) == []
+
+
+def test_tolerates_http_failure(processor, http):
+    rid = start_run(processor=processor, agent_name="session")
+    http.fail_next = True
+    end_run(rid, processor=processor)
+    # No exception; but the POST didn't record.
+    assert len(http.run_end) == 0
+
+
+def test_metadata_in_end_payload(processor, http):
+    rid = start_run(processor=processor, agent_name="session")
+    end_run(rid, processor=processor, metadata={"closed_via": "session_timeout"})
+    _, payload = http.run_end[0]
+    assert payload["metadata"] == {"closed_via": "session_timeout"}

trodo_python-2.3.0/tests/test_processor_methods.py

@@ -0,0 +1,34 @@
+"""Direct unit tests of TrodoSpanProcessor.start_run / .end_run."""
+from __future__ import annotations
+
+from trodo.otel.processor import TrodoRun
+
+
+def test_start_run_posts_to_runs_start(processor, http):
+    run = TrodoRun(run_id="r1", agent_name="x", status="running")
+    processor.start_run(run)
+    assert len(http.run_start) == 1
+    assert http.run_start[0]["run"]["run_id"] == "r1"
+    assert http.run_start[0]["run"]["status"] == "running"
+
+
+def test_end_run_posts_to_runs_end(processor, http):
+    processor.end_run("r1", {"status": "ok", "ended_at": "2026-04-30T00:00:00Z"})
+    assert len(http.run_end) == 1
+    rid, payload = http.run_end[0]
+    assert rid == "r1"
+    assert payload["status"] == "ok"
+
+
+def test_start_run_swallows_http_errors(processor, http):
+    http.fail_next = True
+    run = TrodoRun(run_id="r1", agent_name="x")
+    # Must not raise.
+    processor.start_run(run)
+    assert len(http.run_start) == 0
+
+
+def test_end_run_swallows_http_errors(processor, http):
+    http.fail_next = True
+    processor.end_run("r1", {"status": "ok"})
+    assert len(http.run_end) == 0

trodo_python-2.3.0/tests/test_start_run.py

@@ -0,0 +1,65 @@
+"""Tests for trodo.otel.wrap_agent.start_run module function."""
+from __future__ import annotations
+
+import re
+import uuid
+
+from trodo.otel.wrap_agent import start_run, end_run
+
+
+UUID_RE = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$")
+
+
+def test_mints_run_id_when_not_supplied(processor, http):
+    rid = start_run(processor=processor, agent_name="session")
+    assert UUID_RE.match(rid)
+    assert len(http.run_start) == 1
+    assert http.run_start[0]["run"]["run_id"] == rid
+
+
+def test_accepts_caller_supplied_run_id(processor, http):
+    given = "11111111-2222-3333-4444-555555555555"
+    rid = start_run(processor=processor, agent_name="session", run_id=given)
+    assert rid == given
+    assert http.run_start[0]["run"]["run_id"] == given
+
+
+def test_posts_to_runs_start_with_full_payload(processor, http):
+    rid = start_run(
+        processor=processor,
+        agent_name="external_mcp_session",
+        distinct_id="user-7",
+        conversation_id="conv-abc",
+        parent_run_id="parent-1",
+        metadata={"mcp_client": "claude-desktop"},
+        input={"hello": "world"},
+    )
+    assert len(http.run_start) == 1
+    run = http.run_start[0]["run"]
+    assert run["run_id"] == rid
+    assert run["agent_name"] == "external_mcp_session"
+    assert run["distinct_id"] == "user-7"
+    assert run["conversation_id"] == "conv-abc"
+    assert run["parent_run_id"] == "parent-1"
+    assert run["status"] == "running"
+    assert run["metadata"] == {"mcp_client": "claude-desktop"}
+    assert "started_at" in run
+    # input is JSON-stringified inside _truncate
+    assert "hello" in run["input"]
+
+
+def test_marks_joined_locally(processor, http):
+    rid = start_run(processor=processor, agent_name="session")
+    # Internal state — verify processor flips into joined mode.
+    assert rid in processor._joined_runs
+
+
+def test_tolerates_http_failure(processor, http):
+    """start_run must not raise on backend failure — telemetry is fire-and-forget."""
+    http.fail_next = True
+    rid = start_run(processor=processor, agent_name="session")
+    assert UUID_RE.match(rid)
+    # Failed POST means nothing recorded, but no exception bubbled up.
+    assert len(http.run_start) == 0
+    # Local state still flipped (caller can still emit spans optimistically).
+    assert rid in processor._joined_runs

trodo_python-2.3.0/tests/test_wrap_agent_unchanged.py

@@ -0,0 +1,49 @@
+"""Regression tests: wrap_agent's existing behaviour must not change.
+
+The new start_run/end_run are additive — wrap_agent should still POST
+/runs/ingest in one shot for the simple in-process case, NOT decompose
+into start+end (which would double the HTTP traffic).
+"""
+from __future__ import annotations
+
+import pytest
+
+from trodo.otel.wrap_agent import wrap_agent
+
+
+def test_wrap_agent_uses_single_ingest_call(processor, http):
+    with wrap_agent(
+        processor=processor,
+        team_site_id="site-x",
+        agent_name="chat",
+        distinct_id="user-1",
+        conversation_id="conv-1",
+    ) as run:
+        run.set_input({"q": "hello"})
+        run.set_output({"a": "world"})
+
+    assert len(http.run_ingest) == 1, "wrap_agent must POST /runs/ingest exactly once"
+    assert len(http.run_start) == 0, "wrap_agent must NOT call /runs/start"
+    assert len(http.run_end) == 0, "wrap_agent must NOT call /runs/end"
+
+    run_payload = http.run_ingest[0]["run"]
+    assert run_payload["agent_name"] == "chat"
+    assert run_payload["distinct_id"] == "user-1"
+    assert run_payload["conversation_id"] == "conv-1"
+    assert run_payload["status"] == "ok"
+
+
+def test_wrap_agent_records_error_on_exception(processor, http):
+    with pytest.raises(ValueError):
+        with wrap_agent(
+            processor=processor,
+            team_site_id="site-x",
+            agent_name="chat",
+        ) as run:
+            run.set_input("query")
+            raise ValueError("kaboom")
+
+    assert len(http.run_ingest) == 1
+    run_payload = http.run_ingest[0]["run"]
+    assert run_payload["status"] == "error"
+    assert "kaboom" in run_payload["error_summary"]

{trodo_python-2.1.0 → trodo_python-2.3.0}/trodo/__init__.py

@@ -40,7 +40,7 @@ Downstream microservice (join the caller's run instead of making a new one):
 
 from __future__ import annotations
 
-__version__ = "2.1.0"
+__version__ = "2.3.0"
 
 from typing import Any, Callable, Dict, List, Optional, Union
 
@@ -85,7 +85,10 @@ __all__ = [
     "llm",
     "retrieval",
     "join_run",
+    "start_run",
+    "end_run",
     "track_llm_call",
+    "track_mcp",
     "feedback",
     "get_tracer",
     # Cross-service propagation
@@ -264,6 +267,52 @@ def join_run(
     )
 
 
+def start_run(
+    agent_name: str,
+    *,
+    run_id: Optional[str] = None,
+    distinct_id: Optional[str] = None,
+    conversation_id: Optional[str] = None,
+    parent_run_id: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    input: Any = None,
+) -> str:
+    """Open a Run record without a context manager.
+
+    Pairs with :func:`end_run` for sessions that span multiple processes or
+    HTTP requests. Returns the run_id (caller-supplied or freshly minted).
+    Between start_run and end_run any process can use ``join_run(run_id, ...)``
+    to add spans.
+    """
+    return _get_client().start_run(
+        agent_name,
+        run_id=run_id,
+        distinct_id=distinct_id,
+        conversation_id=conversation_id,
+        parent_run_id=parent_run_id,
+        metadata=metadata,
+        input=input,
+    )
+
+
+def end_run(
+    run_id: str,
+    *,
+    output: Any = None,
+    status: str = "ok",
+    error_summary: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+) -> None:
+    """Finalise a Run opened by :func:`start_run`."""
+    _get_client().end_run(
+        run_id,
+        output=output,
+        status=status,
+        error_summary=error_summary,
+        metadata=metadata,
+    )
+
+
 def tool(
     name: Any = None,
     fn: Optional[Callable[..., Any]] = None,
@@ -377,6 +426,65 @@ def track_llm_call(
     )
 
 
+def track_mcp(
+    *,
+    tool: str,
+    distinct_id: str,
+    input: Any = None,
+    output: Any = None,
+    error: Optional[str] = None,
+    duration_ms: Optional[int] = None,
+    session_id: Optional[str] = None,
+    client_label: Optional[str] = None,
+    attributes: Optional[Dict[str, Any]] = None,
+    agent_name: str = "MCP",
+    started_at: Optional[str] = None,
+    ended_at: Optional[str] = None,
+) -> str:
+    """Record one MCP tool call as a runless span (no parent run).
+
+    Use this from inside an MCP server's ``tools/call`` handler. The MCP
+    server proxies tool calls but never sees the user's prompt or the
+    LLM's final answer, so a parent run carries no analytical value.
+    Each call to ``track_mcp`` writes one self-contained span row tagged
+    with ``agent_name='MCP'`` (overridable), ``distinct_id`` (the user),
+    and ``conversation_id`` (the MCP-Session-Id, auto-uuid'd if omitted).
+
+    Required:
+      tool: the tool name. Becomes ``name='tool.<tool>'``.
+      distinct_id: end-user attribution (email or stable user id).
+
+    Optional:
+      input, output: full args + result. Truncated at 64KB by the SDK.
+      error: if set, marks ``status='error'``.
+      duration_ms: tool wall time. Defaults to 0 if omitted.
+      session_id: the ``Mcp-Session-Id`` from the client; auto-uuid'd
+                  if omitted (each call becomes its own grouping bucket).
+      client_label: 'anthropic' / 'cursor' / 'chatgpt' / etc.; merged
+                    into attributes as ``mcp_client_label``.
+      attributes: free-form extras.
+      agent_name: defaults to 'MCP'; override only for custom tags.
+      started_at / ended_at: ISO 8601; defaults derived from now() and
+                             ``duration_ms`` so callers usually skip them.
+
+    Returns the span_id (str) for caller-side correlation/logging.
+    """
+    return _get_client().track_mcp(
+        tool=tool,
+        distinct_id=distinct_id,
+        input=input,
+        output=output,
+        error=error,
+        duration_ms=duration_ms,
+        session_id=session_id,
+        client_label=client_label,
+        attributes=attributes,
+        agent_name=agent_name,
+        started_at=started_at,
+        ended_at=ended_at,
+    )
+
+
 def feedback(
     run_id: str,
     *,

{trodo_python-2.1.0 → trodo_python-2.3.0}/trodo/api/http_client.py

@@ -107,6 +107,11 @@ class HttpClient:
             {"spans": spans},
         )
 
+    def post_runless_spans(self, spans: list) -> ApiResult:
+        """Ingest spans with no parent run (e.g. MCP tool calls). Each span
+        MUST carry distinct_id and agent_name; the server gates on that."""
+        return self._request("/api/sdk/spans/append", {"spans": spans})
+
     def post_run_feedback(self, run_id: str, payload: Dict[str, Any]) -> ApiResult:
         from urllib.parse import quote
         return self._request(

{trodo_python-2.1.0 → trodo_python-2.3.0}/trodo/client.py

@@ -17,6 +17,8 @@ from .otel.wrap_agent import (
     wrap_agent as wrap_agent_ctx,
     span as span_ctx,
     join_run as join_run_ctx,
+    start_run as start_run_fn,
+    end_run as end_run_fn,
     current_run_id as _current_run_id,
     current_span_id as _current_span_id,
 )
@@ -24,6 +26,7 @@ from .otel.auto_instrument import enable_auto_instrument
 from .otel.helpers import (
     tool as tool_decorator,
     track_llm_call as track_llm_call_fn,
+    track_mcp as track_mcp_fn,
     fastapi_middleware as fastapi_middleware_fn,
     propagation_headers as propagation_headers_fn,
 )
@@ -284,6 +287,51 @@ class TrodoClient:
         """Create a nested span inside the current run."""
         return span_ctx(name=name, kind=kind, input=input, attributes=attributes)
 
+    def start_run(
+        self,
+        agent_name: str,
+        *,
+        run_id: Optional[str] = None,
+        distinct_id: Optional[str] = None,
+        conversation_id: Optional[str] = None,
+        parent_run_id: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        input: Any = None,
+    ) -> str:
+        """Open a Run record outside a context manager. Returns the run_id.
+
+        Use ``end_run`` to finalise, ``join_run`` from any process to add spans.
+        """
+        return start_run_fn(
+            processor=self._span_processor,
+            agent_name=agent_name,
+            run_id=run_id,
+            distinct_id=distinct_id,
+            conversation_id=conversation_id,
+            parent_run_id=parent_run_id,
+            metadata=metadata,
+            input=input,
+        )
+
+    def end_run(
+        self,
+        run_id: str,
+        *,
+        output: Any = None,
+        status: str = "ok",
+        error_summary: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Finalise a Run previously opened by :meth:`start_run`."""
+        end_run_fn(
+            run_id,
+            processor=self._span_processor,
+            output=output,
+            status=status,
+            error_summary=error_summary,
+            metadata=metadata,
+        )
+
     def join_run(
         self,
         run_id: str,
@@ -348,6 +396,65 @@ class TrodoClient:
             metadata=metadata,
         )
 
+    def track_mcp(
+        self,
+        *,
+        tool: str,
+        distinct_id: str,
+        input: Any = None,
+        output: Any = None,
+        error: Optional[str] = None,
+        duration_ms: Optional[int] = None,
+        session_id: Optional[str] = None,
+        client_label: Optional[str] = None,
+        attributes: Optional[Dict[str, Any]] = None,
+        agent_name: str = "MCP",
+        started_at: Optional[str] = None,
+        ended_at: Optional[str] = None,
+    ) -> str:
+        """Record a single MCP tool call as a runless span.
+
+        Use this from inside an MCP server's ``tools/call`` handler — one
+        call to ``track_mcp`` = one row in ``agent_spans`` with ``run_id``
+        NULL. The MCP server proxies tool calls but never sees the user's
+        prompt or the LLM's final answer, so a parent run carries no
+        analytical value; the span is the unit of analytics.
+
+        Required:
+          tool: the tool name (becomes ``name = "tool.<tool>"``).
+          distinct_id: end-user attribution (email or stable user id).
+
+        Optional but recommended:
+          input / output: the tool's args + full result. Truncated at 64KB.
+          error: if set, marks ``status="error"`` and stored as
+                 ``error_message``.
+          duration_ms: tool wall time. If omitted, falls back to 0.
+          session_id: the ``Mcp-Session-Id`` from the client; stored as
+                      ``conversation_id`` for grouping. Auto-uuid'd if
+                      omitted (each call becomes its own bucket).
+          client_label: which MCP client (anthropic / cursor / chatgpt /
+                        etc.); merged into attributes.
+          attributes: any extra free-form key/values.
+          agent_name: defaults to "MCP"; override only for custom tags.
+
+        Returns the span_id (str) so the caller can correlate.
+        """
+        return track_mcp_fn(
+            http=self._http,
+            tool=tool,
+            distinct_id=distinct_id,
+            input=input,
+            output=output,
+            error=error,
+            duration_ms=duration_ms,
+            session_id=session_id,
+            client_label=client_label,
+            attributes=attributes,
+            agent_name=agent_name,
+            started_at=started_at,
+            ended_at=ended_at,
+        )
+
     def fastapi_middleware(self) -> Callable:
         """Return a FastAPI/Starlette middleware that auto-joins runs."""
         return fastapi_middleware_fn(self)

{trodo_python-2.1.0 → trodo_python-2.3.0}/trodo/otel/helpers.py

@@ -286,6 +286,96 @@ def llm(
     )
 
 
+def track_mcp(
+    *,
+    http: Any,
+    tool: str,
+    distinct_id: str,
+    input: Any = None,
+    output: Any = None,
+    error: Optional[str] = None,
+    duration_ms: Optional[int] = None,
+    session_id: Optional[str] = None,
+    client_label: Optional[str] = None,
+    attributes: Optional[Dict[str, Any]] = None,
+    agent_name: str = "MCP",
+    started_at: Optional[str] = None,
+    ended_at: Optional[str] = None,
+) -> str:
+    """Record one MCP tool call as a runless span. See ``Client.track_mcp``
+    for the customer-facing docstring; this is the implementation that
+    builds the span payload and posts it via the HttpClient.
+
+    Returns the span_id.
+    """
+    import json as _json
+    import uuid as _uuid
+    from datetime import datetime, timedelta, timezone
+
+    if not tool:
+        raise ValueError("track_mcp: 'tool' is required")
+    if not distinct_id:
+        raise ValueError("track_mcp: 'distinct_id' is required (runless spans must attribute)")
+
+    span_id = str(_uuid.uuid4())
+    conv_id = session_id or str(_uuid.uuid4())
+
+    now = datetime.now(timezone.utc)
+    if ended_at is None:
+        ended_at = now.isoformat()
+    if started_at is None:
+        offset_ms = duration_ms if isinstance(duration_ms, int) and duration_ms > 0 else 0
+        started_at = (now - timedelta(milliseconds=offset_ms)).isoformat()
+    if duration_ms is None:
+        duration_ms = 0
+
+    status = "error" if error else "ok"
+    if error:
+        error_payload: Any = {"error": error}
+        output_to_record = output if output is not None else error_payload
+    else:
+        output_to_record = output
+
+    def _stringify(value: Any) -> Any:
+        if value is None or isinstance(value, str):
+            return value
+        try:
+            return _json.dumps(value, default=str)
+        except Exception:
+            return str(value)
+
+    merged_attributes: Dict[str, Any] = dict(attributes or {})
+    if client_label:
+        merged_attributes.setdefault("mcp_client_label", client_label)
+
+    span_payload: Dict[str, Any] = {
+        "span_id": span_id,
+        "kind": "tool",
+        "name": f"tool.{tool}",
+        "status": status,
+        "input": _stringify({"tool": tool, "params": input}) if input is not None else None,
+        "output": _stringify(output_to_record),
+        "tool_name": tool,
+        "started_at": started_at,
+        "ended_at": ended_at,
+        "duration_ms": duration_ms,
+        "distinct_id": distinct_id,
+        "conversation_id": conv_id,
+        "agent_name": agent_name,
+        "error_message": error,
+        "attributes": merged_attributes,
+    }
+
+    try:
+        http.post_runless_spans([span_payload])
+    except Exception:
+        # Span loss must never break the caller's request flow. The
+        # underlying HttpClient already retries; failures here mean the
+        # backend rejected (rare) or the network is permanently down.
+        pass
+    return span_id
+
+
 def track_llm_call(
     *,
     model: Optional[str] = None,

{trodo_python-2.1.0 → trodo_python-2.3.0}/trodo/otel/processor.py

@@ -136,6 +136,25 @@ class TrodoSpanProcessor:
         except Exception:
             pass
 
+    def start_run(self, run: TrodoRun) -> None:
+        """Open a Run row server-side without holding a context manager.
+
+        Pairs with ``end_run`` for sessions that span multiple processes or
+        HTTP requests. Spans emitted between start_run and end_run flush
+        incrementally via append_spans (callers are expected to mark_joined).
+        """
+        try:
+            self._http.post_run_start({"run": run.to_dict()})
+        except Exception:
+            pass
+
+    def end_run(self, run_id: str, payload: Dict[str, Any]) -> None:
+        """Finalise a Run opened by start_run."""
+        try:
+            self._http.post_run_end(run_id, payload)
+        except Exception:
+            pass
+
     def append_spans(self, run_id: str, spans: List[TrodoSpan]) -> None:
         """Stream spans for a long-running or joined run without finalising."""
         if not spans:

{trodo_python-2.1.0 → trodo_python-2.3.0}/trodo/otel/wrap_agent.py

@@ -163,6 +163,76 @@ class SpanHandle:
         self.tool_name = tool_name
 
 
+def start_run(
+    *,
+    processor: TrodoSpanProcessor,
+    agent_name: str,
+    run_id: Optional[str] = None,
+    distinct_id: Optional[str] = None,
+    conversation_id: Optional[str] = None,
+    parent_run_id: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    input: Any = None,
+) -> str:
+    """Open a Run record without holding a context manager.
+
+    Pairs with :func:`end_run` for sessions that span multiple processes or
+    HTTP requests (e.g. an MCP server where ``initialize`` opens a run and
+    later ``tools/call`` requests append spans before a final close).
+
+    Returns the ``run_id`` (caller-supplied or freshly minted UUID). Between
+    ``start_run`` and ``end_run`` any process can use ``join_run(run_id, ...)``
+    to add spans — they flush incrementally via ``append_spans``.
+    """
+    rid = run_id or str(uuid.uuid4())
+    run = TrodoRun(
+        run_id=rid,
+        agent_name=agent_name,
+        distinct_id=distinct_id,
+        conversation_id=conversation_id,
+        parent_run_id=parent_run_id,
+        status="running",
+        input=_truncate(input),
+        started_at=_now_iso(),
+        metadata=metadata,
+    )
+    processor.mark_joined(rid)
+    processor.start_run(run)
+    return rid
+
+
+def end_run(
+    run_id: str,
+    *,
+    processor: TrodoSpanProcessor,
+    output: Any = None,
+    status: str = "ok",
+    error_summary: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+) -> None:
+    """Finalise a Run opened by :func:`start_run`.
+
+    Aggregates any locally-buffered spans for ``run_id``, POSTs to the
+    ``/runs/{id}/end`` endpoint, and unmarks the run as joined. Idempotent
+    on the local-state side; the backend treats a second call as a row update.
+    """
+    pending = processor.get_pending(run_id)
+    agg = _aggregate(pending)
+    payload: Dict[str, Any] = {
+        "ended_at": _now_iso(),
+        "status": status,
+        **agg,
+    }
+    if output is not None:
+        payload["output"] = _truncate(output)
+    if error_summary is not None:
+        payload["error_summary"] = _truncate(error_summary, 4_000)
+    if metadata is not None:
+        payload["metadata"] = metadata
+    processor.end_run(run_id, payload)
+    processor.unmark_joined(run_id)
+
+
 class wrap_agent:
     """Context manager wrapping an agent run.
 

{trodo_python-2.1.0 → trodo_python-2.3.0}/trodo_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trodo-python
-Version: 2.1.0
+Version: 2.3.0
 Summary: Trodo Analytics SDK for Python — server-side event tracking
 License: ISC
 Keywords: analytics,tracking,trodo,server-side
@@ -263,6 +263,34 @@ with trodo.join_run(
     ...
 ```
 
+### Long-lived sessions across processes — `start_run` / `end_run`
+
+`wrap_agent` is a context manager — it opens *and* closes the run in one
+call stack. For sessions that live across many HTTP requests (an MCP
+server, a websocket-pinned chat, scheduled jobs that resume on different
+workers), use `start_run` to open the run from one process and `end_run`
+to finalise it later. Between the two, any process can use `join_run` to
+add child spans. Same `run_id` threads through everything.
+
+```python
+# Process A — open the run for an MCP session.
+run_id = trodo.start_run(
+    'external_mcp_session',
+    distinct_id=str(user_id),
+    conversation_id=mcp_session_id,
+)
+redis.set(f"mcp:run:{mcp_session_id}", run_id, ex=3600)
+
+# Process B (later, possibly a different worker) — append a tool span.
+run_id = redis.get(f"mcp:run:{mcp_session_id}").decode()
+with trodo.join_run(run_id, name='tool.run_funnel_query', kind='tool') as span:
+    span.set_input(args)
+    span.set_output(result)
+
+# When the session ends (timeout sweeper, explicit close):
+trodo.end_run(run_id, status='ok')
+```
+
 ### Conversation binding & feedback
 
 ```python

{trodo_python-2.1.0 → trodo_python-2.3.0}/trodo_python.egg-info/SOURCES.txt

@@ -1,5 +1,10 @@
 README.md
 pyproject.toml
+tests/test_cross_process_session.py
+tests/test_end_run.py
+tests/test_processor_methods.py
+tests/test_start_run.py
+tests/test_wrap_agent_unchanged.py
 trodo/__init__.py
 trodo/client.py
 trodo/types.py