Runs and Evidence

Inspect run state, messages, tasks, actors, artifacts, checkpoints, usage, reports, and PRs.

Managed Research runs are designed to leave a reviewable trail.

State flow

Runs usually move through:

queued -> planning -> executing -> finalizing -> done
                         |             |
                         v             v
                      blocked        failed

A run may also stop because of budget, timeout, operator action, or launch/runtime failure.

Status and messages

Use status reads for current state and messages for durable communication with the runtime.

MCP tools:

• smr_get_run
• smr_get_run_execution
• smr_get_run_transcript
• smr_list_run_actor_logs

Python:

result = run.wait(timeout=60 * 60, poll_interval=15)
print(result.state.value)

for message in run.messages(limit=20):
    print(message.get("role"), message.get("status"), message.get("body", "")[:120])

Tasks and actors

Task and actor counts help show what the system actually did.

print("tasks:", run.task_counts())
print("actors:", run.actor_counts())

Artifacts and reports

Artifacts include reports, files, diffs, PR metadata, logs, and workflow-specific outputs.

manifest = run.artifact_manifest()
print("output files:", [artifact.path for artifact in manifest.output_files])

for artifact in run.artifacts():
    print(artifact.artifact_id, artifact.artifact_type, artifact.title)

MCP tools:

• smr_list_run_artifacts
• smr_get_run_artifact_manifest
• smr_get_artifact_content

Checkpoints and branches

Use checkpoints before riskier changes or when a long run finds a useful intermediate state.

checkpoint = run.create_checkpoint(reason="before trying a riskier refactor")
retry = run.branch_from_checkpoint(
    checkpoint_id=checkpoint.checkpoint_id,
    mode="with_message",
    message="Try again from this checkpoint with a smaller patch.",
)

Usage

Usage readback helps connect the evidence to spend and budgets. Use smr_get_run_usage, smr_get_project_usage, and resource-limit progress tools from MCP, or handle.usage.get() / client.research.limits.get() from the hero Python SDK.

Hard stops can come from run budget, monthly budget, timebox, or policy blockers.