sandbox-agent/spec/universal-schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "UniversalEvent",
  "type": "object",
  "required": [
    "data",
    "event_id",
    "sequence",
    "session_id",
    "source",
    "synthetic",
    "time",
    "type"
  ],
  "properties": {
    "data": {
      "$ref": "#/definitions/UniversalEventData"
    },
    "event_id": {
      "type": "string"
    },
    "native_session_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "raw": true,
    "sequence": {
      "type": "integer",
      "format": "uint64",
      "minimum": 0.0
    },
    "session_id": {
      "type": "string"
    },
    "source": {
      "$ref": "#/definitions/EventSource"
    },
    "synthetic": {
      "type": "boolean"
    },
    "time": {
      "type": "string"
    },
    "type": {
      "$ref": "#/definitions/UniversalEventType"
    }
  },
  "definitions": {
    "AgentUnparsedData": {
      "type": "object",
      "required": [
        "error",
        "location"
      ],
      "properties": {
        "error": {
          "type": "string"
        },
        "location": {
          "type": "string"
        },
        "raw_hash": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "ContentPart": {
      "oneOf": [
        {
          "type": "object",
          "required": [
            "text",
            "type"
          ],
          "properties": {
            "text": {
              "type": "string"
            },
            "type": {
              "type": "string",
              "enum": [
                "text"
              ]
            }
          }
        },
        {
          "type": "object",
          "required": [
            "json",
            "type"
          ],
          "properties": {
            "json": true,
            "type": {
              "type": "string",
              "enum": [
                "json"
              ]
            }
          }
        },
        {
          "type": "object",
          "required": [
            "arguments",
            "call_id",
            "name",
            "type"
          ],
          "properties": {
            "arguments": {
              "type": "string"
            },
            "call_id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "type": {
              "type": "string",
              "enum": [
                "tool_call"
              ]
            }
          }
        },
        {
          "type": "object",
          "required": [
            "call_id",
            "output",
            "type"
          ],
          "properties": {
            "call_id": {
              "type": "string"
            },
            "output": {
              "type": "string"
            },
            "type": {
              "type": "string",
              "enum": [
                "tool_result"
              ]
            }
          }
        },
        {
          "type": "object",
          "required": [
            "action",
            "path",
            "type"
          ],
          "properties": {
            "action": {
              "$ref": "#/definitions/FileAction"
            },
            "diff": {
              "type": [
                "string",
                "null"
              ]
            },
            "path": {
              "type": "string"
            },
            "type": {
              "type": "string",
              "enum": [
                "file_ref"
              ]
            }
          }
        },
        {
          "type": "object",
          "required": [
            "text",
            "type",
            "visibility"
          ],
          "properties": {
            "text": {
              "type": "string"
            },
            "type": {
              "type": "string",
              "enum": [
                "reasoning"
              ]
            },
            "visibility": {
              "$ref": "#/definitions/ReasoningVisibility"
            }
          }
        },
        {
          "type": "object",
          "required": [
            "path",
            "type"
          ],
          "properties": {
            "mime": {
              "type": [
                "string",
                "null"
              ]
            },
            "path": {
              "type": "string"
            },
            "type": {
              "type": "string",
              "enum": [
                "image"
              ]
            }
          }
        },
        {
          "type": "object",
          "required": [
            "label",
            "type"
          ],
          "properties": {
            "detail": {
              "type": [
                "string",
                "null"
              ]
            },
            "label": {
              "type": "string"
            },
            "type": {
              "type": "string",
              "enum": [
                "status"
              ]
            }
          }
        }
      ]
    },
    "ErrorData": {
      "type": "object",
      "required": [
        "message"
      ],
      "properties": {
        "code": {
          "type": [
            "string",
            "null"
          ]
        },
        "details": true,
        "message": {
          "type": "string"
        }
      }
    },
    "EventSource": {
      "type": "string",
      "enum": [
        "agent",
        "daemon"
      ]
    },
    "FileAction": {
      "type": "string",
      "enum": [
        "read",
        "write",
        "patch"
      ]
    },
    "ItemDeltaData": {
      "type": "object",
      "required": [
        "delta",
        "item_id"
      ],
      "properties": {
        "delta": {
          "type": "string"
        },
        "item_id": {
          "type": "string"
        },
        "native_item_id": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "ItemEventData": {
      "type": "object",
      "required": [
        "item"
      ],
      "properties": {
        "item": {
          "$ref": "#/definitions/UniversalItem"
        }
      }
    },
    "ItemKind": {
      "type": "string",
      "enum": [
        "message",
        "tool_call",
        "tool_result",
        "system",
        "status",
        "unknown"
      ]
    },
    "ItemRole": {
      "type": "string",
      "enum": [
        "user",
        "assistant",
        "system",
        "tool"
      ]
    },
    "ItemStatus": {
      "type": "string",
      "enum": [
        "in_progress",
        "completed",
        "failed"
      ]
    },
    "PermissionEventData": {
      "type": "object",
      "required": [
        "action",
        "permission_id",
        "status"
      ],
      "properties": {
        "action": {
          "type": "string"
        },
        "metadata": true,
        "permission_id": {
          "type": "string"
        },
        "status": {
          "$ref": "#/definitions/PermissionStatus"
        }
      }
    },
    "PermissionStatus": {
      "type": "string",
      "enum": [
        "requested",
        "accept",
        "accept_for_session",
        "reject"
      ]
    },
    "QuestionEventData": {
      "type": "object",
      "required": [
        "options",
        "prompt",
        "question_id",
        "status"
      ],
      "properties": {
        "options": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "prompt": {
          "type": "string"
        },
        "question_id": {
          "type": "string"
        },
        "response": {
          "type": [
            "string",
            "null"
          ]
        },
        "status": {
          "$ref": "#/definitions/QuestionStatus"
        }
      }
    },
    "QuestionStatus": {
      "type": "string",
      "enum": [
        "requested",
        "answered",
        "rejected"
      ]
    },
    "ReasoningVisibility": {
      "type": "string",
      "enum": [
        "public",
        "private"
      ]
    },
    "SessionEndReason": {
      "type": "string",
      "enum": [
        "completed",
        "error",
        "terminated"
      ]
    },
    "SessionEndedData": {
      "type": "object",
      "required": [
        "reason",
        "terminated_by"
      ],
      "properties": {
        "exit_code": {
          "description": "Process exit code when reason is Error",
          "type": [
            "integer",
            "null"
          ],
          "format": "int32"
        },
        "message": {
          "description": "Error message when reason is Error",
          "type": [
            "string",
            "null"
          ]
        },
        "reason": {
          "$ref": "#/definitions/SessionEndReason"
        },
        "stderr": {
          "description": "Agent stderr output when reason is Error",
          "anyOf": [
            {
              "$ref": "#/definitions/StderrOutput"
            },
            {
              "type": "null"
            }
          ]
        },
        "terminated_by": {
          "$ref": "#/definitions/TerminatedBy"
        }
      }
    },
    "SessionStartedData": {
      "type": "object",
      "properties": {
        "metadata": true
      }
    },
    "StderrOutput": {
      "type": "object",
      "required": [
        "truncated"
      ],
      "properties": {
        "head": {
          "description": "First N lines of stderr (if truncated) or full stderr (if not truncated)",
          "type": [
            "string",
            "null"
          ]
        },
        "tail": {
          "description": "Last N lines of stderr (only present if truncated)",
          "type": [
            "string",
            "null"
          ]
        },
        "total_lines": {
          "description": "Total number of lines in stderr",
          "type": [
            "integer",
            "null"
          ],
          "format": "uint",
          "minimum": 0.0
        },
        "truncated": {
          "description": "Whether the output was truncated",
          "type": "boolean"
        }
      }
    },
    "TerminatedBy": {
      "type": "string",
      "enum": [
        "agent",
        "daemon"
      ]
    },
    "TurnEventData": {
      "type": "object",
      "required": [
        "phase"
      ],
      "properties": {
        "metadata": true,
        "phase": {
          "$ref": "#/definitions/TurnPhase"
        },
        "turn_id": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "TurnPhase": {
      "type": "string",
      "enum": [
        "started",
        "ended"
      ]
    },
    "UniversalEventData": {
      "anyOf": [
        {
          "$ref": "#/definitions/TurnEventData"
        },
        {
          "$ref": "#/definitions/SessionStartedData"
        },
        {
          "$ref": "#/definitions/SessionEndedData"
        },
        {
          "$ref": "#/definitions/ItemEventData"
        },
        {
          "$ref": "#/definitions/ItemDeltaData"
        },
        {
          "$ref": "#/definitions/ErrorData"
        },
        {
          "$ref": "#/definitions/PermissionEventData"
        },
        {
          "$ref": "#/definitions/QuestionEventData"
        },
        {
          "$ref": "#/definitions/AgentUnparsedData"
        }
      ]
    },
    "UniversalEventType": {
      "type": "string",
      "enum": [
        "session.started",
        "session.ended",
        "turn.started",
        "turn.ended",
        "item.started",
        "item.delta",
        "item.completed",
        "error",
        "permission.requested",
        "permission.resolved",
        "question.requested",
        "question.resolved",
        "agent.unparsed"
      ]
    },
    "UniversalItem": {
      "type": "object",
      "required": [
        "content",
        "item_id",
        "kind",
        "status"
      ],
      "properties": {
        "content": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ContentPart"
          }
        },
        "item_id": {
          "type": "string"
        },
        "kind": {
          "$ref": "#/definitions/ItemKind"
        },
        "native_item_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "parent_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "role": {
          "anyOf": [
            {
              "$ref": "#/definitions/ItemRole"
            },
            {
              "type": "null"
            }
          ]
        },
        "status": {
          "$ref": "#/definitions/ItemStatus"
        }
      }
    }
  }
}