Run Tools

Tools for execution tracking — start, report usage, and close agent runs.

Every agent execution that touches OpRelay should open a run at the start and close it at the end. The run_id threads tasks, facts, and failures together for audit and cost tracking.

---

core_start_run

Begin an execution run. Returns a run_id used for all subsequent reporting.

Parameter	Type	Required	Description
project_key	string	✓	Project identifier
agent_id	UUID	✓	Executing agent
run_id	UUID		Explicit run ID (generated if omitted)
summary	string		Intent or description (max 2000)
meta_json	object		Arbitrary metadata

const { run_id } = await oprelay.call("core_start_run", {
  project_key: "myproject",
  agent_id: "agent-uuid",
  summary: "Deploying rate limiter to staging"
});

---

core_report_usage

Accumulate token usage mid-run. Adds to existing totals — safe to call multiple times per run.

Parameter	Type	Required	Description
run_id	UUID	✓	Run UUID from core_start_run
token_usage	object	✓	Usage object (see fields below)
traces	array		Per-call trace entries (max 200)

token_usage fields:

Field	Type	Description
input_tokens	number	Input token count
output_tokens	number	Output token count
total_tokens	number	Total token count
cost_usd	number	Estimated cost
model	string	Model identifier (e.g. claude-opus-4)
llm_calls	number	Number of LLM calls in this batch
prompt_preview	string	Sanitized prompt excerpt (max 2000)

await oprelay.call("core_report_usage", {
  run_id: "run-uuid",
  token_usage: {
    input_tokens: 8400,
    output_tokens: 1200,
    cost_usd: 0.028,
    model: "claude-opus-4",
    llm_calls: 3
  }
});

---

core_end_run

Close a run with final status and summary.

Parameter	Type	Required	Description
run_id	UUID	✓	Run UUID to close
status	string	✓	completed, failed, or interrupted
summary	string		Human-readable outcome (max 2000)
meta_json	object		Final metadata
token_usage	object		Final token usage (same shape as core_report_usage)
traces	array		Final trace entries (max 200)

await oprelay.call("core_end_run", {
  run_id: "run-uuid",
  status: "completed",
  summary: "Rate limiter deployed and verified in staging",
  token_usage: {
    input_tokens: 12400,
    output_tokens: 3200,
    cost_usd: 0.042,
    model: "claude-opus-4",
    llm_calls: 7
  }
});

---

core_record_failure

Record a structured failure event linked to a run. Used for dispatch learning and failure resolution matching.

Parameter	Type	Required	Description
project_key	string	✓	Project identifier
run_id	UUID	✓	Run that produced the failure
agent_id	UUID	✓	Agent that failed
summary	string	✓	Short failure description (max 2000)
task_id	UUID		Associated task
error	string		Full error message or stack trace (max 8000)
context	object		Structured context at time of failure
meta	object		Arbitrary metadata

await oprelay.call("core_record_failure", {
  project_key: "myproject",
  run_id: "run-uuid",
  agent_id: "agent-uuid",
  task_id: "task-uuid",
  summary: "Database connection timeout during migration",
  error: "Error: connect ETIMEDOUT 10.0.0.5:5432",
  context: { migration: "0042_add_index", attempt: 2 }
});

---

record_run

v1 run tool. Append a plain audit trail entry for an agent session. Does not require a pre-existing run ID — creates a complete record in one call.

Parameter	Type	Required	Description
project_key	string	✓	Project identifier
agent	string	✓	Agent name or identifier (max 128)
summary	string	✓	What the agent did (max 2000)
ticket	string		Linked ticket ID (max 64)
meta_json	object		Arbitrary metadata

await oprelay.call("record_run", {
  project_key: "myproject",
  agent: "claude-opus",
  ticket: "OPR-429",
  summary: "Implemented project isolation. All MCP tools now enforce project_key access."
});

Use core_start_run / core_end_run for new work that needs token tracking. Use record_run for lightweight audit entries or v1 compatibility.