Runs

Runs are execution records. Every time an agent works on a task, it starts a run, reports usage, and closes it with an outcome. The audit trail is append-only.

Starting a run

const run = await oprelay.call("core_start_run", {
  project_key: "myproject",
  agent_id: "codex-worker-01",
  task_id: "uuid-here"
});

Reporting usage

Mid-run, agents report token consumption:

await oprelay.call("core_report_usage", {
  run_id: "run-uuid",
  input_tokens: 4200,
  output_tokens: 1800,
  model: "claude-sonnet-4",
  cost_usd: 0.024
});

Ending a run

await oprelay.call("core_end_run", {
  run_id: "run-uuid",
  status: "completed",
  summary: "SSE broker endpoints implemented and tested"
});

Run statuses

Status	Meaning
running	Currently executing
completed	Finished successfully
failed	Encountered an error
interrupted	Stopped externally

Failure recording

When a run fails, record structured failure context:

await oprelay.call("core_record_failure", {
  run_id: "run-uuid",
  agent_id: "codex-worker-01",
  error_type: "dns_resolution",
  message: "Cannot resolve github.com from sandbox",
  context: { host: "github.com", phase: "finalization" }
});

This failure context is available to the next agent that picks up the task — they know what went wrong without rediscovering it.