ci: Add opt-in Langfuse observability at the shared interface boundary

[kennethbruskiewicz]

Summary

This PR adds optional Langfuse observability for TCT calls made through the CLI
and MCP interfaces without decorating individual core-library functions.

It now also:

• records deterministic input/output hashes and canonical payload sizes
• records per-argument sizes, provider counts, batch sizes, and TRAPI identifier counts
• accepts W3C trace context from MCP request metadata so tool calls can join the parent agent turn
• includes a deterministic, offline per-turn benchmark baseline

Behavior

• Langfuse is disabled by default and requires TCT_LANGFUSE_ENABLED=true.
• Direct Python library calls remain uninstrumented.
• CLI and MCP calls produce tool observations named tct.tool.<tool_name>.
• Langfuse is imported lazily and remains an optional dependency.
• Untraced calls avoid trace serialization work.
• MCP tool schemas do not gain observability parameters.

Per-turn benchmark

The checked-in langfuse-turns-v1 fixture makes no network requests and sends
nothing to Langfuse. For a representative turn querying seven identifiers:

Metric	One by one	Batched
Tool calls	7	1
Input bytes	10,269	1,563
Output bytes	679	457
Total payload bytes	10,948	2,020
Provider metadata bytes	8,372	1,196

Batching avoids six tool calls, 8,706 input bytes (84.8%), 8,928 total payload
bytes (81.5%), and 7,176 bytes of repeated provider metadata. A duplicate-call
scenario verifies that stable input hashes identify repeated calls within a turn.

These are TCT tool-boundary measurements. Model tokens and price remain owned by
the parent Langfuse generation; propagated trace context connects both views.

Regenerate the report with:

python -m benchmarks.langfuse_turns

Installation

pip install 'TCT[langfuse]'
pip install 'TCT[mcp,langfuse]'

Documentation

• TCT/interfaces/LANGFUSE.md
• benchmarks/LANGFUSE_TURN_BENCHMARKS.md
• benchmarks/langfuse_turns_baseline.json

Validation

• Full suite: 104 passed, 1 skipped
• Focused Langfuse/configuration suite: 32 passed
• Focused Ruff checks: passed

[kennethbruskiewicz]

Live Langfuse conversational-turn acceptance passed (2026-09-02 16:54 UTC).

Results read back from the Langfuse Observations API:

• One-call-per-identifier turn: 1 agent turn, 7 tool observations, 10,269 input bytes, 679 output bytes, 14 query identifiers.
• Batched turn: 1 agent turn, 1 tool observation, 1,563 input bytes, 457 output bytes, 8 query identifiers.
• Delta: 6 tool calls, 8,706 input bytes, and 222 output bytes avoided.
• Full test suite: 107 passed, 1 skipped.

Published evidence:

• Sanitized acceptance result
• Repeatable live probe
• Batched Langfuse trace
• One-by-one Langfuse trace

[kennethbruskiewicz]

The screenshot clarified that acceptance means a real agent trace hierarchy with model metrics, not only synthetic tool observations.

A real Codex turn was run against the TCT MCP server and read back from Langfuse:

• hierarchy: 1 Codex Turn → 2 LLM generations → 1 successful TCT MCP invocation
• model: gpt-5.6-sol
• tokens: 34,354 prompt + 403 completion = 34,757 total
• trace latency: 13.463 seconds
• Langfuse-computed cost: $0.0450216

Evidence and setup:

• Open the real Langfuse trace
• Sanitized real-turn result
• Codex tracing setup helper

The helper has been applied locally. .codex/langfuse.json is git-ignored, mode 600, and enables future Codex turns in this repo automatically.

Known upstream limitation: tracing plugin 0.1.0 sees Codex 0.152 MCP calls through the unified custom-tool wrapper and labels this child exec; the rollout itself retains translator-component-toolkit.optimize_query_for_api. Tokens, cost, latency, hierarchy, input, output, and status are present.