{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://signalstudio.cc/resources/agent-run-envelope.schema.json",
  "title": "Signal Studio Agent Run Envelope",
  "description": "A vendor-neutral correlation envelope for agent runs, steps, model calls, retrieval, tool proposals, authorization decisions, effects, evaluation, and human review.",
  "$comment": "Version 1.0.0; Apache-2.0; maintained by Signal Studio; updated 2026-08-25. Canonical guide: https://signalstudio.cc/guides/agent-trace-schema/. Book: https://signalstudio.cc/books/observability-for-ai-agents/. This schema validates shape, not truth, completeness, privacy, or operational safety.",
  "type": "object",
  "additionalProperties": false,
  "required": ["schema_version", "run_id", "workflow_name", "started_at", "status", "steps"],
  "properties": {
    "schema_version": { "const": "1.0.0" },
    "run_id": { "type": "string", "minLength": 1 },
    "trace_id": { "type": ["string", "null"], "pattern": "^[0-9a-f]{32}$" },
    "workflow_name": { "type": "string", "minLength": 1 },
    "workflow_version": { "type": ["string", "null"] },
    "tenant_ref": { "type": ["string", "null"], "description": "Use a pseudonymous reference; do not place customer names or email addresses here." },
    "started_at": { "type": "string", "format": "date-time" },
    "ended_at": { "type": ["string", "null"], "format": "date-time" },
    "status": { "enum": ["running", "succeeded", "failed", "cancelled", "needs_review", "unknown"] },
    "input_ref": { "type": ["string", "null"], "description": "Reference to governed storage, not raw prompt content." },
    "output_ref": { "type": ["string", "null"], "description": "Reference to governed storage, not raw model content." },
    "steps": {
      "type": "array",
      "items": { "$ref": "#/$defs/step" }
    },
    "evaluation": { "$ref": "#/$defs/evaluation" },
    "human_review": { "$ref": "#/$defs/humanReview" }
  },
  "$defs": {
    "step": {
      "type": "object",
      "additionalProperties": false,
      "required": ["step_id", "kind", "started_at", "status"],
      "properties": {
        "step_id": { "type": "string", "minLength": 1 },
        "parent_step_id": { "type": ["string", "null"] },
        "kind": { "enum": ["model", "retrieval", "memory_read", "memory_write", "tool_proposal", "authorization", "tool_effect", "handoff", "human_review", "other"] },
        "started_at": { "type": "string", "format": "date-time" },
        "ended_at": { "type": ["string", "null"], "format": "date-time" },
        "status": { "enum": ["running", "succeeded", "failed", "denied", "cancelled", "unknown"] },
        "operation_key": { "type": ["string", "null"], "description": "Stable key used to deduplicate retries of the same intended effect." },
        "model": { "type": ["string", "null"] },
        "tool": { "type": ["string", "null"] },
        "resource": { "type": ["string", "null"] },
        "policy_version": { "type": ["string", "null"] },
        "decision_reason_code": { "type": ["string", "null"] },
        "input_ref": { "type": ["string", "null"] },
        "output_ref": { "type": ["string", "null"] },
        "effect_receipt_ref": { "type": ["string", "null"] },
        "error_type": { "type": ["string", "null"] },
        "usage": {
          "type": ["object", "null"],
          "additionalProperties": false,
          "properties": {
            "input_tokens": { "type": ["integer", "null"], "minimum": 0 },
            "output_tokens": { "type": ["integer", "null"], "minimum": 0 },
            "cost_usd": { "type": ["number", "null"], "minimum": 0 }
          }
        }
      }
    },
    "evaluation": {
      "type": ["object", "null"],
      "additionalProperties": false,
      "required": ["task_id", "result"],
      "properties": {
        "task_id": { "type": "string" },
        "result": { "enum": ["pass", "fail", "inconclusive", "not_reviewed"] },
        "serious_failure": { "type": ["boolean", "null"] },
        "grader_versions": { "type": "array", "items": { "type": "string" } }
      }
    },
    "humanReview": {
      "type": ["object", "null"],
      "additionalProperties": false,
      "properties": {
        "status": { "enum": ["not_requested", "pending", "approved", "rejected", "escalated"] },
        "reviewer_role": { "type": ["string", "null"] },
        "reviewed_at": { "type": ["string", "null"], "format": "date-time" },
        "reason_code": { "type": ["string", "null"] }
      }
    }
  }
}