Custom events, PostHog exporter, async identify, and hardened event pipeline

[naji247]

Summary

This PR brings the Python SDK to feature parity with the TypeScript SDK and hardens the event pipeline so that no SDK failure can ever surface into a customer's MCP server. It adds custom event publishing, a PostHog exporter, async identify support with per-request identify events and identity merging, fixes a bug where redaction functions never ran on published events, and adds an extensive failure-injection test suite.

New features

publish_custom_event

Publish agentcat:custom events for actions outside the MCP request lifecycle:

from agentcat import publish_custom_event, CustomEventData

publish_custom_event(server, "proj_...", CustomEventData(
    resource_name="nightly_sync",
    message="Scheduled sync completed",
    duration=1240,
    tags={"pipeline": "nightly"},
    properties={"records": 1832},
))

The first argument accepts either a tracked server or an MCP session ID string. String session IDs are converted with the same deterministic SHA-256 → KSUID derivation used by the TypeScript and Go SDKs, so custom events correlate with tracked sessions across languages and server restarts.

PostHog exporter

Joins the existing OTLP, Datadog, and Sentry exporters:

options = AgentCatOptions(exporters={
    "posthog": {"type": "posthog", "api_key": "phc_...", "enable_ai_tracing": True},
})

Sends capture events with mapped names (mcp_tool_call, mcp_initialize, ...), person profile updates from identified actors, $exception events on errors, and optional $ai_span AI-observability events. Session IDs are mapped to deterministic UUIDv7 values.

Async identify + identity merging

• identify hooks may now be async def; sync hooks work unchanged.
• The hook runs on every captured request, and an agentcat:identify event is published each time it returns an identity. Identities merge across calls — user_id/user_name are overwritten by the newest result while user_data keys accumulate — with an LRU cache (1000 sessions) providing merge continuity across server-object recreation. Actor attribution on individual events is unaffected.
• In stateless mode the cache is bypassed and each request's raw identity is published as-is, so user_data from different actors sharing a server instance can never merge together.

Bug fixes

• Redaction now runs on published events. The redaction pass only traversed plain dict/list/str structures and silently skipped the event model, so redact_sensitive_information functions never ran on the live publish path. The three e2e tests documenting this were previously marked expected-failure and now pass. Async redaction functions are also supported and awaited.
• Full structured errors on the low-level Server path. The low-level integration recorded only the error message; it now captures the same structured data (stack frames, chained exceptions, in-app detection) as the FastMCP integrations.
• publish_custom_event argument errors are confined to the documented ValueError/TypeError contract.

Truncation alignment

Event truncation now applies dedicated per-field limits before the total-size pass — user intent and error messages (2048 chars), resource/server/client names (256), stack frames (50, keeping first and last 25), response text blocks (32KB) — and the general limits were aligned with the published event contract: 32KB per string, depth 10, breadth 100, 100KB total (previously 10KB / 5 / 500).

Reliability hardening

The SDK's contract is that analytics must never break the host server. This PR closes every gap found in an adversarial review of the request path:

• Exception capture, identify hooks, tag/property callbacks, and event publishing are all fully fail-open: failures are logged and the event is dropped, and the customer's tool call proceeds untouched — including pathological cases like exceptions whose own __str__ raises, callbacks returning non-dict values, or objects with a raising __bool__.
• The queue worker survives poisoned events (cyclic structures, NaN/Inf, bytes, objects with raising __repr__, redaction functions that raise sync or async) and keeps delivering subsequent events.
• Exporter failures are isolated per exporter and never affect delivery to the API or other exporters.

Each fix is covered by tests/test_failure_injection.py (38 tests), several of which exercise real Streamable HTTP transports end to end.

Compatibility notes

• An agentcat:identify event is published for every captured request where the identify hook returns an identity. Per-event actor fields are unchanged, and identify events now carry the accumulated (merged) user_data.
• Users who configured redact_sensitive_information will now see redaction actually applied to published events.
• Event payloads may retain more detail due to the raised truncation limits; the 100KB total event cap is unchanged.
• No breaking API changes. New exports: publish_custom_event, CustomEventData, PostHogExporterConfig.

Testing

• Full suite: 611 passed, 4 skipped (skips pre-existing/environmental), including e2e suites over stdio and Streamable HTTP for the official FastMCP, community FastMCP v2/v3, and low-level Server integrations.
• New suites: failure injection (38), custom events (16), PostHog exporter (22), identify semantics and merging (14+), low-level error capture, field-level truncation (19).