trodo-python 1.2.0__tar.gz → 2.2.0__tar.gz

{trodo_python-1.2.0 → trodo_python-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trodo-python
-Version: 1.2.0
+Version: 2.2.0
 Summary: Trodo Analytics SDK for Python — server-side event tracking
 License: ISC
 Keywords: analytics,tracking,trodo,server-side
@@ -136,9 +136,188 @@ trodo.set_group('user-123', 'company', 'acme')
 
 ---
 
-## Agent Analytics
+## AI Agent Tracing (recommended)
 
-Track every step of your LLM agents. Each call counts as one event toward your plan limit.
+One wrap around your agent captures every LLM call, tool call, and
+nested step as a tree of spans — token counts, costs, inputs, outputs,
+errors. Works with any stack: OpenAI, Anthropic, LangChain, LlamaIndex,
+Gemini, raw HTTP, custom tools. Cost is derived server-side from
+`(provider, model)` — the SDK only sends tokens.
+
+### 30-second quickstart
+
+```python
+import trodo
+trodo.init(site_id='your-site-id')   # auto-instrument on by default
+
+with trodo.wrap_agent('customer-support',
+                       distinct_id=user_id,
+                       conversation_id=session_id) as run:
+    run.set_input({'query': 'where did sales drop'})
+    answer = agent.run(query)        # OpenAI/Anthropic/LangChain auto-captured
+    run.set_output(answer)
+```
+
+Open the Agent Runs dashboard — the row shows tokens in/out, cost,
+span count, tool count, error count, plus the full trace tree.
+
+### Auto-instrumentation
+
+`trodo.init()` calls `enable_auto_instrument()` which registers every
+installed OpenTelemetry instrumentor. No extra code required.
+
+| Framework | Install |
+|-----------|---------|
+| OpenAI | `pip install opentelemetry-instrumentation-openai` |
+| Anthropic | `pip install opentelemetry-instrumentation-anthropic` |
+| LangChain | `pip install opentelemetry-instrumentation-langchain` |
+| LlamaIndex | `pip install opentelemetry-instrumentation-llama-index` |
+| Google Gemini | `pip install opentelemetry-instrumentation-google-generativeai` |
+| Vertex AI | `pip install opentelemetry-instrumentation-vertexai` |
+| Bedrock | `pip install opentelemetry-instrumentation-bedrock` |
+| Cohere | `pip install opentelemetry-instrumentation-cohere` |
+| Mistral | `pip install opentelemetry-instrumentation-mistralai` |
+| Haystack | `pip install opentelemetry-instrumentation-haystack` |
+| httpx / requests | bundled — generic HTTP spans for raw-HTTP callers |
+
+Opt out with `trodo.init(site_id=..., auto_instrument=False)`.
+
+### Span helpers
+
+Typed function wrappers for custom code — every call becomes a span
+with the args auto-captured as `input`, return value as `output`,
+exception as `error`. Dual-form: helper **and** decorator.
+
+```python
+# trace — generic span
+prepared = trodo.trace('prepare', prepare_fn)(payload)
+
+@trodo.trace('step')
+def step(): ...
+
+# tool — tool span (auto tool_name, kind='tool')
+run_funnel = trodo.tool('run_funnel_query', run_funnel_query)
+result = run_funnel(team_id=1, preset='day7')
+
+@trodo.tool(name='fetch_user')
+async def fetch_user(uid): ...
+
+# llm — LLM span, auto-extracts OpenAI / Anthropic / Gemini usage
+answer = trodo.llm(
+    'answer', call_openai, model='gpt-4o-mini', provider='openai',
+)(messages)
+# Records input_tokens / output_tokens from response['usage'].
+
+# retrieval — vector search / RAG retriever span
+search = trodo.retrieval('vector_search', vector_search)
+docs = search(query)
+```
+
+### Raw-HTTP escape hatches
+
+If your LLM client isn't OTel-instrumented and you can't wrap it as a
+function, record a span post-hoc:
+
+```python
+resp = httpx.post(url, json=body).json()
+trodo.track_llm_call(
+    model='gemini-2.5-flash', provider='google',
+    input_tokens=resp['usageMetadata']['promptTokenCount'],
+    output_tokens=resp['usageMetadata']['candidatesTokenCount'],
+    prompt=body, completion=resp,
+)
+```
+
+For advanced cases, get a raw OTel tracer — the Trodo processor is
+already subscribed:
+
+```python
+tracer = trodo.get_tracer('my.module')
+with tracer.start_as_current_span('custom') as sp:
+    sp.set_attribute('gen_ai.system', 'my-llm')
+```
+
+### Cross-service runs
+
+When one service calls another, the downstream service **joins** the
+caller's run instead of creating its own. All spans nest under a single
+timeline in the dashboard.
+
+```python
+# Caller (FastAPI / Flask / Django / …) — outbound:
+import httpx
+httpx.post(url, headers=trodo.propagation_headers(), json=body)
+
+# Downstream (FastAPI):
+from fastapi import FastAPI
+app = FastAPI()
+app.middleware('http')(trodo.fastapi_middleware())
+# Every LLM call / @tool / trace helper inside handlers now nests under
+# the caller's run — no extra wiring.
+
+# Or manually:
+with trodo.join_run(
+    run_id=headers['x-trodo-run-id'],
+    parent_span_id=headers['x-trodo-parent-span-id'],
+):
+    ...
+```
+
+### 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
+with trodo.wrap_agent(
+    'chat', distinct_id=user_id, conversation_id=session_id,
+) as run:
+    ...
+# Later:
+trodo.feedback(run.run_id, satisfaction='positive', rating=5)
+```
+
+### Cookbook
+
+Runnable scenarios that double as integration tests live in
+`sandbox/scenarios/` — `span_helpers.py`, `raw_http.py`,
+`custom_tools.py`, `cross_service.py`, `concurrent_100.py`,
+`long_run.py`, plus opt-in `openai_auto.py`, `anthropic_auto.py`,
+`langchain_chain.py`. Run them with
+`python -m sandbox.run_all` from the SDK root.
+
+---
+
+## Agent Analytics (legacy event-based API)
+
+The older per-event API below is still supported but superseded by
+`wrap_agent` + span helpers above. Use it only if you're already wired
+into it; new integrations should prefer the tracing API.
 
 **Before you start:** register your agent in **Integrations → AI Agents** in the dashboard to get an `agent_id` (`agt_xxxxxxxx`).
 
@@ -161,6 +340,7 @@ trodo.track_agent_call(AgentCallProps(
     provider='anthropic',
     system_prompt_version='v2',   # optional — track prompt iterations
     distinct_id=user_id,          # optional — link to a Trodo user
+    metadata={'thread_source': 'slack', 'locale': 'en'},  # optional — agent_calls.metadata JSONB
 ))
 ```
 

{trodo_python-1.2.0 → trodo_python-2.2.0}/README.md

@@ -109,9 +109,188 @@ trodo.set_group('user-123', 'company', 'acme')
 
 ---
 
-## Agent Analytics
+## AI Agent Tracing (recommended)
 
-Track every step of your LLM agents. Each call counts as one event toward your plan limit.
+One wrap around your agent captures every LLM call, tool call, and
+nested step as a tree of spans — token counts, costs, inputs, outputs,
+errors. Works with any stack: OpenAI, Anthropic, LangChain, LlamaIndex,
+Gemini, raw HTTP, custom tools. Cost is derived server-side from
+`(provider, model)` — the SDK only sends tokens.
+
+### 30-second quickstart
+
+```python
+import trodo
+trodo.init(site_id='your-site-id')   # auto-instrument on by default
+
+with trodo.wrap_agent('customer-support',
+                       distinct_id=user_id,
+                       conversation_id=session_id) as run:
+    run.set_input({'query': 'where did sales drop'})
+    answer = agent.run(query)        # OpenAI/Anthropic/LangChain auto-captured
+    run.set_output(answer)
+```
+
+Open the Agent Runs dashboard — the row shows tokens in/out, cost,
+span count, tool count, error count, plus the full trace tree.
+
+### Auto-instrumentation
+
+`trodo.init()` calls `enable_auto_instrument()` which registers every
+installed OpenTelemetry instrumentor. No extra code required.
+
+| Framework | Install |
+|-----------|---------|
+| OpenAI | `pip install opentelemetry-instrumentation-openai` |
+| Anthropic | `pip install opentelemetry-instrumentation-anthropic` |
+| LangChain | `pip install opentelemetry-instrumentation-langchain` |
+| LlamaIndex | `pip install opentelemetry-instrumentation-llama-index` |
+| Google Gemini | `pip install opentelemetry-instrumentation-google-generativeai` |
+| Vertex AI | `pip install opentelemetry-instrumentation-vertexai` |
+| Bedrock | `pip install opentelemetry-instrumentation-bedrock` |
+| Cohere | `pip install opentelemetry-instrumentation-cohere` |
+| Mistral | `pip install opentelemetry-instrumentation-mistralai` |
+| Haystack | `pip install opentelemetry-instrumentation-haystack` |
+| httpx / requests | bundled — generic HTTP spans for raw-HTTP callers |
+
+Opt out with `trodo.init(site_id=..., auto_instrument=False)`.
+
+### Span helpers
+
+Typed function wrappers for custom code — every call becomes a span
+with the args auto-captured as `input`, return value as `output`,
+exception as `error`. Dual-form: helper **and** decorator.
+
+```python
+# trace — generic span
+prepared = trodo.trace('prepare', prepare_fn)(payload)
+
+@trodo.trace('step')
+def step(): ...
+
+# tool — tool span (auto tool_name, kind='tool')
+run_funnel = trodo.tool('run_funnel_query', run_funnel_query)
+result = run_funnel(team_id=1, preset='day7')
+
+@trodo.tool(name='fetch_user')
+async def fetch_user(uid): ...
+
+# llm — LLM span, auto-extracts OpenAI / Anthropic / Gemini usage
+answer = trodo.llm(
+    'answer', call_openai, model='gpt-4o-mini', provider='openai',
+)(messages)
+# Records input_tokens / output_tokens from response['usage'].
+
+# retrieval — vector search / RAG retriever span
+search = trodo.retrieval('vector_search', vector_search)
+docs = search(query)
+```
+
+### Raw-HTTP escape hatches
+
+If your LLM client isn't OTel-instrumented and you can't wrap it as a
+function, record a span post-hoc:
+
+```python
+resp = httpx.post(url, json=body).json()
+trodo.track_llm_call(
+    model='gemini-2.5-flash', provider='google',
+    input_tokens=resp['usageMetadata']['promptTokenCount'],
+    output_tokens=resp['usageMetadata']['candidatesTokenCount'],
+    prompt=body, completion=resp,
+)
+```
+
+For advanced cases, get a raw OTel tracer — the Trodo processor is
+already subscribed:
+
+```python
+tracer = trodo.get_tracer('my.module')
+with tracer.start_as_current_span('custom') as sp:
+    sp.set_attribute('gen_ai.system', 'my-llm')
+```
+
+### Cross-service runs
+
+When one service calls another, the downstream service **joins** the
+caller's run instead of creating its own. All spans nest under a single
+timeline in the dashboard.
+
+```python
+# Caller (FastAPI / Flask / Django / …) — outbound:
+import httpx
+httpx.post(url, headers=trodo.propagation_headers(), json=body)
+
+# Downstream (FastAPI):
+from fastapi import FastAPI
+app = FastAPI()
+app.middleware('http')(trodo.fastapi_middleware())
+# Every LLM call / @tool / trace helper inside handlers now nests under
+# the caller's run — no extra wiring.
+
+# Or manually:
+with trodo.join_run(
+    run_id=headers['x-trodo-run-id'],
+    parent_span_id=headers['x-trodo-parent-span-id'],
+):
+    ...
+```
+
+### 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
+with trodo.wrap_agent(
+    'chat', distinct_id=user_id, conversation_id=session_id,
+) as run:
+    ...
+# Later:
+trodo.feedback(run.run_id, satisfaction='positive', rating=5)
+```
+
+### Cookbook
+
+Runnable scenarios that double as integration tests live in
+`sandbox/scenarios/` — `span_helpers.py`, `raw_http.py`,
+`custom_tools.py`, `cross_service.py`, `concurrent_100.py`,
+`long_run.py`, plus opt-in `openai_auto.py`, `anthropic_auto.py`,
+`langchain_chain.py`. Run them with
+`python -m sandbox.run_all` from the SDK root.
+
+---
+
+## Agent Analytics (legacy event-based API)
+
+The older per-event API below is still supported but superseded by
+`wrap_agent` + span helpers above. Use it only if you're already wired
+into it; new integrations should prefer the tracing API.
 
 **Before you start:** register your agent in **Integrations → AI Agents** in the dashboard to get an `agent_id` (`agt_xxxxxxxx`).
 
@@ -134,6 +313,7 @@ trodo.track_agent_call(AgentCallProps(
     provider='anthropic',
     system_prompt_version='v2',   # optional — track prompt iterations
     distinct_id=user_id,          # optional — link to a Trodo user
+    metadata={'thread_source': 'slack', 'locale': 'en'},  # optional — agent_calls.metadata JSONB
 ))
 ```
 

{trodo_python-1.2.0 → trodo_python-2.2.0}/pyproject.toml

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

trodo_python-2.2.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.2.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.2.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.2.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