> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cascadeflow.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# HarnessRunContext

> Run context object yielded by cascadeflow.run() with summary(), trace(), and budget tracking methods.

The context object yielded by `cascadeflow.run()`. Provides access to run metrics, decision traces, and budget state.

## Methods

### summary()

Returns aggregate metrics for the run.

```python theme={null}
summary = session.summary()
```

Returns a dict with:

| Key                | Type            | Description                           |
| ------------------ | --------------- | ------------------------------------- |
| `cost_total`       | `float`         | Cumulative cost in USD                |
| `steps`            | `int`           | Number of LLM calls                   |
| `tool_calls`       | `int`           | Number of tool/function calls         |
| `latency_total_ms` | `float`         | Total wall-clock latency in ms        |
| `energy_used`      | `float`         | Total energy units consumed           |
| `budget_remaining` | `float \| None` | USD remaining (None if no budget set) |

### trace()

Returns the list of decision records for the run.

```python theme={null}
records = session.trace()
```

Each record is a dict with:

| Key            | Type    | Description                                             |
| -------------- | ------- | ------------------------------------------------------- |
| `action`       | `str`   | `"allow"`, `"switch_model"`, `"deny_tool"`, or `"stop"` |
| `reason`       | `str`   | Human-readable explanation                              |
| `model`        | `str`   | Model name                                              |
| `step`         | `int`   | Step number (1-indexed)                                 |
| `cost_total`   | `float` | Cumulative cost at this step                            |
| `budget_state` | `str`   | `"ok"`, `"warning"`, or `"exceeded"`                    |
| `applied`      | `bool`  | Whether the action was enforced                         |

## Usage

```python theme={null}
import cascadeflow

cascadeflow.init(mode="enforce")

with cascadeflow.run(budget=0.50) as session:
    result = await agent.run("Analyze this dataset")

    # Aggregate metrics
    summary = session.summary()
    print(f"Cost: ${summary['cost_total']:.4f}")
    print(f"Steps: {summary['steps']}")
    print(f"Budget remaining: ${summary['budget_remaining']:.4f}")

    # Decision trace
    for record in session.trace():
        print(f"Step {record['step']}: {record['action']} — {record['reason']}")
```

## Import

```python theme={null}
from cascadeflow import HarnessRunContext
```