Console Report Plugin

The Console Report Plugin renders a structured end-of-session report to the terminal. It assembles sections contributed by other plugins (Telemetry, Inference Metrics, etc.) and prints them as a formatted console report.

Overview

The plugin:

Listens on onSessionReportRender to receive collected report sections
Sorts sections by their order field (lower = earlier)
Renders a formatted header, each section's title and lines, and a footer
Supports color via the terminal color utilities when available
Graceful no-op when format is not "console" or no sections are provided

Configuration

The session report is controlled by the session_report config value:

# Enable the session report (default in new installations)
session_report: true

plugins:
  - module: "codumentor.plugins.console_report"
    class: "ConsoleReportPlugin"

The session_report config value is true in the default configuration. It is consumed at the end of a print-mode (-p) run. Set it to false in codumentor.yaml to suppress the report.

The ConsoleReportPlugin itself has no configuration options. What appears in the report is determined by which plugins are configured.

How It Works

The session report system uses a two-phase hook architecture:

codumentor_exit()
  |
  +-- Phase 1: bus.emit("onSessionReport")       # Data plugins contribute sections
  |     +-- TelemetryPlugin --> report_collect    #   timing: wall, LLM, tool times
  |     +-- InferenceMetricsPlugin --> report_collect  #   TTFT, tokens/sec
  |     --> returns actions["report_sections"]
  |
  +-- Phase 2: bus.emit("onSessionReportRender")  # Render plugin assembles + prints
        +-- ConsoleReportPlugin --> prints header, sections, footer

Why two phases: Plugins cannot see other plugins' accumulated actions during a single emit(). Phase 1 collects data from all contributing plugins, then Phase 2 passes the collected sections to the renderer.

Section Format

Plugins contributing to the session report return sections via report_collect:

{
    "type": "report_collect",
    "sections": [{
        "id": "telemetry",          # Unique section identifier
        "title": "Timing Metrics",  # Displayed as section header
        "lines": [                  # Lines of text to display
            "Turns: 5",
            "Wall time: 12.3s",
            "LLM time: 8.1s (66%)",
        ],
        "order": 10,               # Sort order (lower = earlier)
    }]
}

Output

When the session report is enabled (session_report: true), it appears after the core token usage report:

==================================================
  Session Report
==================================================

  Timing Metrics
    Turns: 5
    Wall time: 12.3s
    LLM time:  8.1s (66%)
    Tool time: 3.2s (26%)

      search: 3x / 1.85s
      grep: 2x / 0.92s

  Inference Performance
    Avg TTFT: 245ms
    Avg tokens/sec: 42.5
    Samples: 5

      short: TTFT 150ms, 45.2 tok/s (3 samples)
      medium: TTFT 340ms, 39.8 tok/s (2 samples)
==================================================

Error Handling

No ConsoleReportPlugin configured: onSessionReportRender has no handlers, emit() returns an empty actions dict, nothing is printed
Plugin handler throws: EventBus soft-fails (logs error, emits onError, continues pipeline)
Non-console format: Handler returns None, no output produced
Empty sections: Handler returns None, no output produced

Source Code

See src/codumentor/plugins/console_report/console_report_plugin.py for the complete implementation.