hiveos-trace 0.3.2

Drop-in execution trace harness for non-deterministic workflows.

HiveOS Trace CLI Quickstart

hiveos-trace is a standalone CLI wedge extracted from HiveOS tracing concepts. It is built for operators and developers who want execution visibility, replay, and diagnosis without adopting the full HiveOS platform runtime.

Install

pipx install hiveos-trace

Alternative:

python -m pip install -U hiveos-trace

From source:

python -m pip install -e .

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

python -m hiveos.hive --help
python -m hiveos.hive trace ls

Windows command shim note:

• trace run launches commands directly.
• If a shimmed executable fails direct launch, Hive retries with cmd /c.
• Manual explicit form remains valid:

hive trace run --no-open -- cmd /c openclaw agent --session-id main --message "hello"

Verbose help mode:

hive trace replay-plan --help-verbose

Zero-to-One

hive doctor
hive quickstart --no-open
hive trace ls --limit 5

CLI Surface (v0.3.2)

Single source of truth:

• docs/hiveos_trace_source_of_truth.md

Authoritative command/flag reference:

• docs/releases/hiveos-trace-command-reference-v0.3.2.md

Use this quickstart doc for workflow guidance and examples, not full command-surface maintenance.

Open Behavior

• quickstart, trace run, and trace replay default to no-open.
• Use --open to explicitly open UI for a run.
• --no-open always forces no-open.
• If --open is requested and the UI target is unavailable, Hive serves a local fallback run page.
• Set HIVE_TRACE_OPEN_ON_RUN=true if you want default-open behavior globally.

Branding Stamp

• Footer stamp is shown only on screenshot-prone summary commands:
  • hive trace ls
  • hive trace summary
  • hive trace diff
  • hive trace diagnose
• Stamp format:
  • - hiveos-trace v<version>
• JSON outputs remain unchanged (no branding line is added).
• Disable stamp if needed:
  • HIVE_TRACE_BRANDING_DISABLE=true

Terminal UX + Color

• Text output keeps stable key=value shape for easy parsing/scanning.
• JSON outputs are unchanged and never colorized.
• Color mode is global:
  • --color auto (default)
  • --color always
  • --color never
• Environment overrides:
  • HIVE_TRACE_COLOR=auto|always|never
  • NO_COLOR=1 to force disable color
• Examples:

hive --color always trace ls --limit 10
hive --color never trace replay-plan <run_id> --recommended --explain

What This Gives You

• Run-level event lineage (observe_run_started, observe_run_finished)
• Step/output event capture from wrapped commands
• Checkpoint/rerun intent events for SDK-based flows
• Fast operator loop:
  • run (trace run)
  • summarize (trace summary)
  • tail (trace tail)
  • inspect (trace show)
  • compare (trace diff)
  • replay (trace replay)
  • replay preview (trace replay-plan)
  • diagnose (trace diagnose)
• Lifecycle hygiene (trace ops archive|unarchive|prune|reconcile)
• Liveness visibility on active runs (trace ls / trace summary show runtime state + last output activity age + heartbeat age)
• Team handoff path (trace ops export, trace ops import)
• Agentic lineage path (trace flow ls/show/steps/diff)

Run records are stored under ~/.hiveos-trace/runs. Default trace log path is ~/.hiveos-trace/logs/trace_events.log unless overridden.

SDK Integration (Optional)

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"})
        observe_step(run_id, "extract.finish", payload={"rows": 1203})

Structured agent/tool helper events:

from hiveos.observe import (
    observe_agent_step_start,
    observe_agent_step_end,
    observe_tool_call_start,
    observe_tool_call_end,
    observe_step_retry,
    observe_branch_decision,
)

observe_agent_step_start(run_id, "step:plan", flow_id="flow:42", step_name="planner")
observe_tool_call_start(run_id, "tool:web.search:1", flow_id="flow:42", step_id="step:search", parent_step_id="step:plan")
observe_tool_call_end(run_id, "tool:web.search:1", flow_id="flow:42", step_id="step:search", outcome="success")
observe_step_retry(run_id, "step:search", flow_id="flow:42", attempt=2, reason="low confidence")
observe_branch_decision(run_id, "step:branch.next", flow_id="flow:42", selected_branch="summarize", branches=["summarize", "retry"])
observe_agent_step_end(run_id, "step:plan", flow_id="flow:42", outcome="success")

Checkpoint + rerun intent:

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")

Proxy Capture Mode (Optional)

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

Insight Macros

Macros are composed from primitives and include provenance:

hive trace insight explain <run_id>
hive trace insight drift <run_id_a> <run_id_b>
hive trace insight health --window 24h

Useful flags:

• --json
• --show-source
• --emit-primitive

Share Runs Across Machines

Export a run:

hive trace ops export <run_id> --bundle .\trace-bundles\run.bundle.json

Import on another machine:

hive trace ops import --bundle .\trace-bundles\run.bundle.json

If the same run id already exists, remap during import:

hive trace ops import --bundle .\trace-bundles\run.bundle.json --as-run-id observe-run:shared-001

Flow Lineage Views

Flow-level commands let you inspect agentic execution structure when events include lineage fields.

hive trace flow ls --limit 10
hive trace flow show <flow_id>
hive trace flow steps <flow_id> --json
hive trace flow diff <flow_id_a> <flow_id_b> --json

Lineage fields used by flow views:

• flow_id
• step_id
• parent_step_id
• tool_call_id
• attempt
• step_type

Notes:

• Flow commands ignore events that do not include flow_id.
• Existing non-lineage traces remain fully supported by run-level commands.

Replay Controls

Replay stability principle:

• replay is stateful resume from validated protocol boundaries, not prompt reconstruction.
• canonical reference: docs/hiveos_trace_replay_resume_contract_v1.md
• replay execution requires resume admission (resume_envelope.admission.allowed=true).

Preview replay intent without execution:

hive trace replay-plan <run_id> --from-step-id <step_id> --json
hive trace replay-plan <run_id> --recommended --json
hive trace replay-plan <run_id> --recommended --explain

Persist a replay-plan artifact for downstream tooling:

hive trace replay-plan <run_id> --from-step-id <step_id> --emit-artifact --json
hive trace replay-plan <run_id> --from-step-id <step_id> --artifact-path .\tmp\replay-plan.json --json

Inspect persisted artifacts:

hive trace artifacts ls --type replay_plan --json
hive trace artifacts show <artifact_id> --json
hive trace artifacts replay <artifact_id> --no-open

Execute directly from the validated plan:

hive trace replay-plan <run_id> --from-checkpoint-id <checkpoint_id> --apply --no-open

List available anchors on a run:

hive trace anchors <run_id>
hive trace anchors <run_id> --json

Emit a checkpoint marker from CLI (no SDK wiring required):

hive trace checkpoint <run_id> <checkpoint_id> --step-name <step_name> --state-ref <state_ref>
hive trace checkpoint <run_id> --auto-id --from-step-id <step_id>

trace anchors --json includes recommended_replay_anchors with:

• ranked stability and replay admission hints
• boundary strength / idempotency risk
• failure proximity scoring around first failed boundary
• continuation utility scoring:
  • replay_utility_score
  • continuation_viability
  • replay_utility_rationale
• recommendation rationale used for ordering

Optional payload hints (when emitted by runtime/shims) that improve replay safety:

• idempotency_hint (low|medium|high|unknown)
• side_effect (true|false)
• external_write (true|false)

The core CLI wrapper now emits these hints on command lifecycle events by default.

Release Validation

Before public release:

1. Run .github/workflows/hive-trace-publish-testpypi.yml (manual dispatch).
2. Validate clean install from TestPyPI.

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.3.2) to trigger .github/workflows/hive-trace-publish-pypi.yml.