OSOP Execution Report Specification

April 14, 2026 · View on GitHub

Version: 1.0.0-draft Status: Draft Date: 2026-03-31

1. Purpose

This document specifies how .osoplog execution records (defined in agent-runtime-binding.md) are transformed into human-readable reports. A report provides a structured summary of a workflow execution: what ran, what succeeded, what failed, how long it took, and what it cost.

Reports are generated by the osop.report tool and can be produced in three output formats.

2. Output Formats

Format	Extension	Use Case
HTML	`.html`	Browser viewing, email, archival. Self-contained single file with inline CSS.
ANSI text	(terminal)	Terminal display with color codes. For CLI and agent output.
Plain text	`.txt`	Environments without color support. Logs, CI output, accessibility.

The HTML format is the default. All three formats render the same logical structure.

3. Report Structure

A report contains these sections in order:

3.1 Header

Workflow name and ID
Workflow version
Run ID
Overall status: COMPLETED, FAILED, CANCELLED, TIMED_OUT
Start time, end time, total duration

3.2 Summary

One-line result summary (from result_summary in the .osoplog)
Total node count, pass count, fail count, skip count
Total cost (if available)

3.3 Node Timeline

A sequential listing of every node execution record:

Field	Description
Node ID	Identifier of the executed node
Node type	One of the OSOP node types (Core: agent, api, cli, human)
Status	`COMPLETED`, `FAILED`, `SKIPPED`, `TIMED_OUT`
Attempt	Attempt number (shows retries)
Duration	Wall-clock time for this node
Inputs	Summarized input values (truncated at 200 chars)
Outputs	Summarized output values (truncated at 200 chars)
Error	Error code and message (if failed)

Nodes are listed in chronological order by started_at. Retry attempts for the same node appear as indented sub-entries.

3.4 Cost Breakdown

If the .osoplog contains a cost block:

Total cost in USD
Per-node cost table sorted by cost descending
AI-specific costs: prompt tokens, completion tokens, model used

Runtime information: agent, model, platform
Trigger source and actor
Generation timestamp

4. Design Principles

4.1 Zero Icons

Reports use no emoji, no icon fonts, no SVG icons. Status is communicated through text labels and color alone. This ensures compatibility across all rendering contexts and avoids visual noise.

4.2 Five-Color System

All visual differentiation uses exactly five colors:

Color	Role	HTML Value
Green	Success, completed	`#22c55e`
Red	Failure, error	`#ef4444`
Yellow	Warning, timeout, in-progress	`#eab308`
Blue	Informational, metadata	`#3b82f6`
Gray	Neutral, skipped, secondary text	`#6b7280`

In ANSI text mode, these map to the standard terminal colors: green (32), red (31), yellow (33), blue (34), gray (90).

In plain text mode, no colors are used. Status is conveyed by text labels alone (e.g., [PASS], [FAIL], [SKIP]).

4.3 Minimal Output

No decorative elements (borders, shadows, gradients)
No JavaScript in HTML output (fully static)
No external dependencies (fonts, stylesheets, images)
Self-contained: a single HTML file with inline <style>
Maximum width: 80 columns for text formats
Truncate large values; link to full data where possible

5. Input Sources

A report can be generated from:

Mode	Input	Result
Definition only	`.osop` file	Static report showing workflow structure, node list, edge graph. No execution data.
Execution	`.osop` + `.osoplog`	Full execution report with timing, status, costs, and per-node results.
Log only	`.osoplog` (contains `workflow_id`)	Execution report. Workflow structure derived from the log's node records.

The .osoplog format is defined in Section 5 of agent-runtime-binding.md.

6. HTML Report Template

The HTML report follows this structure:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>OSOP Report: {workflow_name} — {run_id}</title>
  <style>
    /* Inline CSS using the 5-color system */
    /* Monospace font stack: system monospace */
    /* Max-width container, responsive */
  </style>
</head>
<body>
  <header><!-- Workflow name, status, timing --></header>
  <section id="summary"><!-- One-line summary, counts --></section>
  <section id="timeline"><!-- Node-by-node results --></section>
  <section id="cost"><!-- Cost breakdown table --></section>
  <footer><!-- Runtime info, generation timestamp --></footer>
</body>
</html>

No <script> tags. No external resources. The file is fully self-contained.

7. Text Report Template

OSOP Execution Report
=====================
Workflow:  {name} ({id})
Run ID:    {run_id}
Status:    {status}
Duration:  {duration}
Started:   {started_at}
Ended:     {ended_at}

Summary
-------
{result_summary}
Nodes: {total} total, {pass} passed, {fail} failed, {skip} skipped

Timeline
--------
[PASS]  receive_request    human    120ms
[PASS]  search_web         mcp     3.2s
[FAIL]  search_academic    api     2.1s   (attempt 1: RATE_LIMITED)
[PASS]  search_academic    api     2.8s   (attempt 2)
[PASS]  analyze_sources    agent   7.8s
[PASS]  draft_report       agent  11.2s
[PASS]  review_report      human   5.2s

Cost
----
Total: \$0.140
  draft_report       \$0.082
  analyze_sources    \$0.058

Runtime
-------
Agent:    claude-code 1.2.0
Model:    claude-sonnet-4-20250514
Platform: darwin-arm64

Generated: {timestamp}

For the .osoplog format definition, see agent-runtime-binding.md. For the OSOP protocol specification, see SPEC.md.