Governance and Trace Headers

Use taimoe.platform.proxy.build_taimoe_headers() when an application makes an outbound call that should carry Agent identity and trace context.

from taimoe.platform.proxy import build_taimoe_headers

headers = build_taimoe_headers(
    runtime_id="support-prod",
    agent_id="support",
    parent_agent_id="router",
    session_id="session-123",
    user_id="privacy-filtered-user-id",
    step="model_call",
)

The result contains Taimoe-native X-Taimoe-* headers plus W3C traceparent and tracestate values. Trace IDs use 32 lowercase hex characters and span IDs use 16; malformed or all-zero IDs are rejected.

Header	Purpose
X-Taimoe-Runtime-Id	Calling Runtime identity.
X-Taimoe-Agent-Id	Calling Agent identity.
X-Taimoe-Parent-Agent-Id	Optional parent Agent.
X-Taimoe-Trace-Id	End-to-end trace correlation.
X-Taimoe-Span-Id	Current operation correlation.
X-Taimoe-Parent-Span-Id	Optional parent operation.
X-Taimoe-Session-Id	Conversation/session correlation.
X-Taimoe-User-Id	Privacy-filtered end-user identity.
X-Taimoe-Step	Lifecycle step label.
traceparent	W3C Trace Context propagation.
tracestate	Taimoe vendor state.

Header values reject empty strings, CR/LF characters, and oversized identity fields to prevent malformed requests and header injection. Pass include_traceparent=False when another tracing library owns W3C headers.

The matching parser accepts case-insensitive HTTP mappings and can recover trace context from traceparent when Taimoe-native IDs are absent.