{
  "name": "Waxell Run Structure",
  "description": "Logical structure for a Waxell Observe agent execution run, mapping fields to their sources in agent SDK telemetry.",
  "entity": "Run",
  "fields": [
    { "name": "run_id", "type": "uuid", "required": true, "source": "Generated by control plane on POST /runs/start/" },
    { "name": "agent_name", "type": "string", "required": true, "source": "@waxell.observe(agent_name=...) decorator" },
    { "name": "status", "type": "enum", "values": ["pending", "running", "paused", "completed", "failed"], "source": "Lifecycle managed by SDK + control plane" },
    { "name": "session_id", "type": "string", "source": "WaxellContext or explicit init parameter" },
    { "name": "user_id", "type": "string", "source": "WaxellContext metadata" },
    { "name": "started_at", "type": "datetime", "source": "Server timestamp at /runs/start/" },
    { "name": "completed_at", "type": "datetime", "source": "Server timestamp at /runs/{id}/complete/" },
    { "name": "total_tokens", "type": "integer", "source": "Aggregated from associated llm-calls" },
    { "name": "total_cost_usd", "type": "number", "source": "Server-side recalculation using model-costs table" },
    { "name": "metadata", "type": "object", "source": "Free-form attributes from SDK" }
  ],
  "relationships": [
    { "name": "llm_calls", "type": "hasMany", "target": "LlmCall" },
    { "name": "spans", "type": "hasMany", "target": "Span" },
    { "name": "steps", "type": "hasMany", "target": "Step" },
    { "name": "scores", "type": "hasMany", "target": "Score" },
    { "name": "events", "type": "hasMany", "target": "Event" }
  ]
}