Langfuse Observability

Langfuse is the LLM observability layer for joelclaw. Every LLM call produces a Langfuse trace with nested hierarchy, I/O, usage, cost, and attribution.

Architecture

joelclaw has two Langfuse integration points:

1. Pi-session extension (langfuse-cost)

• Source: pi/extensions/langfuse-cost/index.ts (canonical, git-tracked in this repo)
• Runtime: loaded as a pi extension from the same source tree
• What it traces: Every gateway + interactive pi session LLM call
• How: Hooks into pi session events (session_start, message_start, message_end, tool_call, tool_result, session_shutdown)
• Dedup: globalThis.__langfuse_cost_loaded__ guard prevents duplicate extension instances
• Optional dependency behavior: langfuse is lazily loaded (no top-level hard import). Missing module must disable telemetry, not crash extension import. Regression test: pi/extensions/langfuse-cost/index.test.ts
• Runtime dependency location: because the extension is loaded from pi/extensions/ at repo root instead of a workspace package, the langfuse npm package must be available from the repo root package.json. If root install drift drops it, gateway/session telemetry silently degrades to the optional-dependency warning again.