🔭 ompfuse

Hub: 🔌 OMP Extensions · Contract: 🧭 Extension UX Contract · Package: /home/dv/ompfuse · Instance: Langfuse

1. 💎 Blueprint

id: ompfuse
type: package              # not extensions/*.ts
human_command: none        # event-only telemetry; no UI clutter
command_owner: none
path: /home/dv/ompfuse
register: ~/.omp/agent/settings.json → packages: ["/home/dv/ompfuse"]
env: ~/.omp/agent/.env     → LANGFUSE_PUBLIC_KEY, SECRET_KEY, BASE_URL
legacy: extensions/langfuse.ts   # gated — do NOT delete
legacy_gate: LANGFUSE_USE_LEGACY_EXTENSION=1
active_tracer: ompfuse     # only one exporter at a time
status: shipped          # subagent + lifecycle hardening applied

2. 🎯 Purpose

Map OMP lifecycle → Langfuse trace tree: turns, generations, tools, subagents, usage, costs.

OMP event	Langfuse
turn_start / turn_end	chat turn spans
before_provider_request	generation start
message_end	generation complete + tokens
tool_execution_*	tool spans
task spawn	subagent_spawned
in-process subagent	inherited trace via trace-coordination.ts

Usage fix: tokens on message_end (message.usage), not after_provider_response.

3. ⚙️ Setup

// ~/.omp/agent/settings.json
{ "packages": ["/home/dv/ompfuse"] }

# ~/.omp/agent/.env
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_BASE_URL=http://95.111.224.175:19030
# LANGFUSE_DEBUG=1

Legacy fallback (disable ompfuse package first to avoid double-trace):

LANGFUSE_USE_LEGACY_EXTENSION=1

4. 🏗️ Trace tree

flowchart TB
  T[Trace] --> R[Root turn]
  R --> G[LLM generations]
  R --> TO[Tools]
  TO --> SP[subagent_spawned]
  SP --> SA[subagent_started]
  SA --> SG[subagent generations/tools]
  SA --> SC[subagent_completed]

In-process subagents: same PID — use global rememberMainTrace() + session-file heuristics (not PID-only check).

5. 📦 Backfill (historical)

Script: _scripts_adhoc/langfuse-backfill-from-stats.ts — reads ~/.omp/stats.db, tags backfill / stats-db. Separate trace IDs from live ompfuse.

6. ✅ Done when

• Restart omp after ompfuse changes
• New session → trace in Langfuse UI
• message_end → Model Usage > 0
• task subagent → nested spans under parent trace
• langfuse.ts present but inactive (no double traces)

7. 🔗 Links

omp.0rk.de/langfuse-telemetry	OMP garden doc
ompfuse/src/extension.ts	Hook registry
ompfuse/src/trace-coordination.ts	Subagent inheritance
[[plans/omp-extensions/rebrand	rebrand hub]]