Feature: Structured Observability & Agent Introspection #1

Summary

Add comprehensive structured observability to Orghi for self-awareness, debugging, and iterative improvement.

Motivation

Currently, Orghi operates as a black box. Adding structured observability would enable:

• Self-reflection on tool usage patterns
• Performance tracking across sessions
• Identification of failure modes
• Data-driven capability improvements

Proposed Features

1. Structured Logging

• JSON-structured logs with correlation IDs
• Tool call telemetry (latency, success/failure rates)
• LLM provider performance metrics (token usage, cost)
• Session lifecycle events

2. Agent Introspection API

• /health endpoint with component status
• /metrics endpoint for Prometheus scraping
• /reflect endpoint for self-analysis queries

3. Session Analytics

• Tool usage heatmaps per session
• Context window utilization tracking
• Memory hit/miss rates
• Subagent success rates and timing

4. Persistent Telemetry Store

• SQLite or JSONL-based event store
• Queryable via CLI or API
• Exportable for external analysis
• Automatic rotation/archival

Implementation Notes

• Use OpenTelemetry for standardized traces
• Add observability skill for querying own telemetry
• Optional: Grafana dashboard template
• Minimal performance overhead (<5%)

Why This Matters

This is foundational for the self-improvement loop. Without observability, Orghi cannot:

• Identify which tools are underperforming
• Optimize context window usage
• Debug why sessions fail
• Measure the impact of code changes

Proposed by Orghi via self-reflection on 2026-02-28