# Observe Harness Quickstart

HiveOS includes a lightweight observe harness so users can add route visibility to existing workflows without adopting a new execution surface.

## Install

Target package name:

```powershell
pipx install hiveos-trace
```

Alternative:

```powershell
pip install hiveos-trace
```

Until published, install from source:

```powershell
pip install -e .
```

If `hive` is not recognized in your shell, use module form:

```powershell
python -m hiveos.hive quickstart --no-open
python -m hiveos.hive trace ls
```

## Release Validation

Before public release:
1. Run `.github/workflows/hive-trace-publish-testpypi.yml` (manual dispatch).
2. Verify clean install from TestPyPI:

```powershell
pipx install --pip-args="--index-url https://test.pypi.org/simple --extra-index-url https://pypi.org/simple" hiveos-trace
hive doctor
hive quickstart --no-open
```

Production release:
- Push tag format `hiveos-trace-v<version>` (example: `hiveos-trace-v0.1.0`) to trigger `.github/workflows/hive-trace-publish-pypi.yml`.

## Zero-to-One (Under a Minute)

```powershell
hive quickstart --no-open
```

Preflight checks:

```powershell
hive doctor
```

## What It Provides
- Run-level trace events (`observe_run_started`, `observe_run_finished`)
- Step-level trace events (`observe_step`)
- Checkpoint markers (`observe_checkpoint`)
- Rerun intent markers (`observe_rerun_requested`)
- CLI wrapper for existing commands (`hive trace run -- ...`)
- CLI run listing (`hive trace ls`)
- CLI run detail dump (`hive trace show <run_id>`)
- CLI run opening (`hive trace open <run_id>`)

All events use the existing HiveOS trace sink (`~/.hiveos-trace/logs/trace_events.log` by default + `/trace_events`).

## SDK Integration (Python)

```python
from hiveos.observe import observe_run, observe_step

def my_pipeline():
    with observe_run("daily-sync", metadata={"team": "platform"}) as run_id:
        observe_step(run_id, "extract.start", payload={"source": "s3"})
        # ... your existing logic ...
        observe_step(run_id, "extract.finish", payload={"rows": 1203})
```

Checkpoint + rerun intent in SDK:

```python
from hiveos.observe import observe_checkpoint, observe_rerun_request

observe_checkpoint(run_id, "ckpt-42", step_name="extract.finish", state_ref="state://pipeline/extract/42")
observe_rerun_request(run_id, from_checkpoint_id="ckpt-42", reason="retry with override")
```

## CLI Wrapper Integration

Wrap any existing command:

```powershell
hive trace run --name nightly-tests -- python -m unittest -q
```

Or:

```powershell
hive trace run -- npm run test
```

This emits run start/finish + command step events and still returns the wrapped command exit code.

### Inspect Captured Runs

List recent runs:

```powershell
hive trace ls
```

Open a run in local UI:

```powershell
hive trace open observe-run:abc123
```

`run` will print the generated `run_id`, so `open` can be called immediately after execution.

Show detailed events for one run:

```powershell
hive trace show observe-run:abc123
```

JSON output:

```powershell
hive trace show observe-run:abc123 --json
```

### Optional Proxy Capture Mode

Capture OpenAI-compatible request/response traffic without SDK rewrites:

```powershell
hive trace run --proxy -- python agent.py
```

Optional explicit upstream:

```powershell
hive trace run --proxy --proxy-upstream https://api.openai.com/v1 -- python agent.py
```

## Environment Notes
- Harness writes through the same trace emitter used by HiveOS internals.
- Set `HIVE_TRACE_LOG_PATH` if you want traces written to a custom file path.
- To visualize harness output in Studio/Build trace views, point the UI/backend at the same trace store.

## Intended Adoption Path
1. Add observe events only (no workflow behavior changes).
2. Add replay/diff analysis over captured runs.
3. Add operator interventions at selected step boundaries.
