{
"$schema": "http://json-schema.org/draft-07/schema#",
"$comment": "2026-02-19T00:00:00Z",
"title": "agent-exec CLI response schema",
"description": "JSON Schema for all stdout responses produced by agent-exec v0.1.",
"definitions": {
"Envelope": {
"type": "object",
"required": [
"schema_version",
"ok",
"type"
],
"properties": {
"schema_version": {
"type": "string",
"const": "0.1",
"description": "Schema version identifier."
},
"ok": {
"type": "boolean",
"description": "True for successful responses, false for errors."
},
"type": {
"type": "string",
"description": "Response type discriminator."
}
}
},
"ErrorDetail": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string",
"description": "Machine-readable error code (e.g. job_not_found, internal_error)."
},
"message": {
"type": "string",
"description": "Human-readable error description."
},
"retryable": {
"type": "boolean",
"description": "Whether the caller may retry the same request."
}
}
},
"ErrorResponse": {
"allOf": [
{
"$ref": "#/definitions/Envelope"
},
{
"type": "object",
"required": [
"error"
],
"properties": {
"ok": {
"const": false
},
"type": {
"const": "error"
},
"error": {
"$ref": "#/definitions/ErrorDetail"
}
}
}
]
},
"Snapshot": {
"type": "object",
"required": [
"stdout_tail",
"stderr_tail",
"truncated",
"encoding",
"stdout_observed_bytes",
"stderr_observed_bytes",
"stdout_included_bytes",
"stderr_included_bytes"
],
"properties": {
"stdout_tail": {
"type": "string"
},
"stderr_tail": {
"type": "string"
},
"truncated": {
"type": "boolean"
},
"encoding": {
"type": "string"
},
"stdout_observed_bytes": {
"type": "integer",
"minimum": 0
},
"stderr_observed_bytes": {
"type": "integer",
"minimum": 0
},
"stdout_included_bytes": {
"type": "integer",
"minimum": 0
},
"stderr_included_bytes": {
"type": "integer",
"minimum": 0
}
}
},
"CompressionData": {
"type": "object",
"required": [
"mode", "applied", "detected_kind", "stdout", "stderr",
"stdout_original_bytes", "stderr_original_bytes",
"stdout_compressed_bytes", "stderr_compressed_bytes", "omitted", "strategy"
],
"properties": {
"mode": { "type": "string", "enum": ["off", "route", "errors", "tests", "logs", "git", "json", "summary"] },
"applied": { "type": "boolean" },
"detected_kind": { "type": "string" },
"stdout": { "type": "string" },
"stderr": { "type": "string" },
"stdout_original_bytes": { "type": "integer", "minimum": 0 },
"stderr_original_bytes": { "type": "integer", "minimum": 0 },
"stdout_compressed_bytes": { "type": "integer", "minimum": 0 },
"stderr_compressed_bytes": { "type": "integer", "minimum": 0 },
"omitted": { "type": "boolean" },
"strategy": { "type": "array", "items": { "type": "string" } }
}
},
"RunLikeResponse": {
"allOf": [
{
"$ref": "#/definitions/Envelope"
},
{
"type": "object",
"required": [
"job_id",
"state",
"stdout_log_path",
"stderr_log_path",
"waited_ms",
"elapsed_ms",
"stdout",
"stderr",
"stdout_range",
"stderr_range",
"stdout_total_bytes",
"stderr_total_bytes",
"encoding"
],
"properties": {
"type": {
"enum": [
"run",
"restart"
]
},
"job_id": {
"type": "string"
},
"state": {
"type": "string",
"enum": [
"running",
"exited",
"killed",
"failed",
"unknown"
]
},
"env_vars": {
"type": "array",
"items": {
"type": "string"
},
"description": "KEY=VALUE strings with masked values replaced by ***."
},
"snapshot": {
"$ref": "#/definitions/Snapshot"
},
"stdout_log_path": {
"type": "string"
},
"stderr_log_path": {
"type": "string"
},
"waited_ms": {
"type": "integer",
"minimum": 0
},
"elapsed_ms": {
"type": "integer",
"minimum": 0
},
"stdout": {
"type": "string"
},
"stderr": {
"type": "string"
},
"stdout_range": {
"type": "array",
"items": {
"type": "integer"
},
"minItems": 2,
"maxItems": 2
},
"stderr_range": {
"type": "array",
"items": {
"type": "integer"
},
"minItems": 2,
"maxItems": 2
},
"stdout_total_bytes": {
"type": "integer",
"minimum": 0
},
"stderr_total_bytes": {
"type": "integer",
"minimum": 0
},
"encoding": {
"type": "string"
},
"compression": {
"$ref": "#/definitions/CompressionData"
}
}
}
]
},
"StatusResponse": {
"allOf": [
{
"$ref": "#/definitions/Envelope"
},
{
"type": "object",
"required": [
"job_id",
"state",
"started_at"
],
"properties": {
"type": {
"const": "status"
},
"job_id": {
"type": "string"
},
"state": {
"type": "string",
"enum": [
"running",
"exited",
"killed",
"failed",
"unknown"
]
},
"exit_code": {
"type": [
"integer",
"null"
]
},
"started_at": {
"type": "string",
"format": "date-time"
},
"finished_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}
]
},
"TailResponse": {
"allOf": [
{
"$ref": "#/definitions/Envelope"
},
{
"type": "object",
"required": [
"job_id",
"stdout",
"stderr",
"encoding",
"stdout_log_path",
"stderr_log_path",
"stdout_range",
"stderr_range",
"stdout_total_bytes",
"stderr_total_bytes"
],
"properties": {
"type": {
"const": "tail"
},
"job_id": {
"type": "string"
},
"stdout": {
"type": "string"
},
"stderr": {
"type": "string"
},
"encoding": {
"type": "string"
},
"stdout_log_path": {
"type": "string"
},
"stderr_log_path": {
"type": "string"
},
"stdout_range": {
"type": "array",
"items": {
"type": "integer"
},
"minItems": 2,
"maxItems": 2
},
"stderr_range": {
"type": "array",
"items": {
"type": "integer"
},
"minItems": 2,
"maxItems": 2
},
"stdout_total_bytes": {
"type": "integer",
"minimum": 0
},
"stderr_total_bytes": {
"type": "integer",
"minimum": 0
},
"compression": {
"$ref": "#/definitions/CompressionData"
}
}
}
]
},
"WaitResponse": {
"allOf": [
{
"$ref": "#/definitions/Envelope"
},
{
"type": "object",
"required": [
"job_id",
"state"
],
"properties": {
"type": {
"const": "wait"
},
"job_id": {
"type": "string"
},
"state": {
"type": "string",
"enum": [
"running",
"exited",
"killed",
"failed",
"unknown"
]
},
"exit_code": {
"type": [
"integer",
"null"
]
}
}
}
]
},
"KillResponse": {
"allOf": [
{
"$ref": "#/definitions/Envelope"
},
{
"type": "object",
"required": [
"job_id",
"signal"
],
"properties": {
"type": {
"const": "kill"
},
"job_id": {
"type": "string"
},
"signal": {
"type": "string"
}
}
}
]
},
"JobSummary": {
"type": "object",
"required": [
"job_id",
"state",
"started_at"
],
"properties": {
"job_id": {
"type": "string"
},
"state": {
"type": "string",
"enum": [
"running",
"exited",
"killed",
"failed",
"unknown"
]
},
"exit_code": {
"type": [
"integer",
"null"
]
},
"started_at": {
"type": "string",
"format": "date-time"
},
"finished_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
},
"ListResponse": {
"allOf": [
{
"$ref": "#/definitions/Envelope"
},
{
"type": "object",
"required": [
"root",
"jobs",
"truncated",
"skipped"
],
"properties": {
"type": {
"const": "list"
},
"root": {
"type": "string"
},
"jobs": {
"type": "array",
"items": {
"$ref": "#/definitions/JobSummary"
}
},
"truncated": {
"type": "boolean"
},
"skipped": {
"type": "integer",
"minimum": 0
}
}
}
]
},
"SchemaResponse": {
"allOf": [
{
"$ref": "#/definitions/Envelope"
},
{
"type": "object",
"required": [
"schema_format",
"schema",
"generated_at"
],
"properties": {
"type": {
"const": "schema"
},
"schema_format": {
"type": "string",
"const": "json-schema-draft-07",
"description": "The JSON Schema specification version."
},
"schema": {
"type": "object",
"description": "The full JSON Schema document."
},
"generated_at": {
"type": "string",
"description": "RFC 3339 timestamp of when the schema was last updated."
}
}
}
]
},
"Compression": {
"type": "object",
"required": [
"mode",
"applied",
"detected_kind",
"stdout",
"stderr",
"stdout_original_bytes",
"stderr_original_bytes",
"stdout_compressed_bytes",
"stderr_compressed_bytes",
"omitted",
"strategy"
],
"properties": {
"mode": {
"type": "string",
"enum": [
"off",
"route",
"errors",
"tests",
"logs",
"git",
"json",
"summary"
]
},
"applied": {
"type": "boolean"
},
"detected_kind": {
"type": "string"
},
"stdout": {
"type": "string"
},
"stderr": {
"type": "string"
},
"stdout_original_bytes": {
"type": "integer",
"minimum": 0
},
"stderr_original_bytes": {
"type": "integer",
"minimum": 0
},
"stdout_compressed_bytes": {
"type": "integer",
"minimum": 0
},
"stderr_compressed_bytes": {
"type": "integer",
"minimum": 0
},
"omitted": {
"type": "boolean"
},
"strategy": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"oneOf": [
{
"$ref": "#/definitions/ErrorResponse"
},
{
"$ref": "#/definitions/RunLikeResponse"
},
{
"$ref": "#/definitions/StatusResponse"
},
{
"$ref": "#/definitions/TailResponse"
},
{
"$ref": "#/definitions/WaitResponse"
},
{
"$ref": "#/definitions/KillResponse"
},
{
"$ref": "#/definitions/ListResponse"
},
{
"$ref": "#/definitions/SchemaResponse"
}
]
}