feat: add headless automation protocol and CLI
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good

This commit is contained in:
2026-09-28 15:36:22 +01:00
parent e8e4d64e42
commit 4f10f6e584
20 changed files with 3310 additions and 18 deletions
@@ -0,0 +1,49 @@
[
{
"requestId": "negative",
"command": "advance",
"params": {
"frames": -1
}
},
{
"requestId": "wrong-input",
"command": "set_input",
"params": {
"rigth": true
}
},
{
"requestId": "extra",
"command": "get_state",
"params": {
"extra": true
}
},
{
"requestId": "unknown",
"command": "missing",
"params": {}
},
{
"requestId": "blank-path",
"command": "boot",
"params": {
"path": ""
}
},
{
"requestId": "",
"command": "reset",
"params": {}
},
{
"requestId": "no-params",
"command": "get_state"
},
{
"requestId": "null-params",
"command": "get_state",
"params": null
}
]
@@ -0,0 +1,284 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://prometeu.dev/headless/v1/request.schema.json",
"title": "Prometeu Headless v1 Request",
"type": "object",
"additionalProperties": false,
"required": [
"requestId",
"command",
"params"
],
"properties": {
"requestId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"command": {
"type": "string"
},
"params": {
"type": "object"
}
},
"oneOf": [
{
"properties": {
"command": {
"const": "initialize"
},
"params": {
"type": "object",
"additionalProperties": false,
"required": [
"protocolVersion",
"requiredCapabilities"
],
"properties": {
"protocolVersion": {
"$ref": "#/$defs/version"
},
"requiredCapabilities": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
},
{
"properties": {
"command": {
"const": "boot"
},
"params": {
"type": "object",
"additionalProperties": false,
"required": [
"path"
],
"properties": {
"path": {
"type": "string",
"minLength": 1,
"pattern": "\\S"
}
}
}
}
},
{
"properties": {
"command": {
"const": "advance"
},
"params": {
"type": "object",
"additionalProperties": false,
"required": [
"frames"
],
"properties": {
"frames": {
"type": "integer",
"minimum": 0,
"maximum": 18446744073709551615
}
}
}
}
},
{
"properties": {
"command": {
"const": "set_input"
},
"params": {
"$ref": "#/$defs/input"
}
}
},
{
"properties": {
"command": {
"const": "cancel"
},
"params": {
"type": "object",
"additionalProperties": false,
"required": [
"targetRequestId"
],
"properties": {
"targetRequestId": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
}
}
}
},
{
"properties": {
"command": {
"const": "reset"
},
"params": {
"type": "object",
"maxProperties": 0
}
}
},
{
"properties": {
"command": {
"const": "clear_input"
},
"params": {
"type": "object",
"maxProperties": 0
}
}
},
{
"properties": {
"command": {
"const": "capture"
},
"params": {
"type": "object",
"maxProperties": 0
}
}
},
{
"properties": {
"command": {
"const": "get_state"
},
"params": {
"type": "object",
"maxProperties": 0
}
}
},
{
"properties": {
"command": {
"const": "get_fault"
},
"params": {
"type": "object",
"maxProperties": 0
}
}
},
{
"properties": {
"command": {
"const": "shutdown"
},
"params": {
"type": "object",
"maxProperties": 0
}
}
}
],
"$defs": {
"version": {
"type": "object",
"additionalProperties": false,
"required": [
"major",
"minor"
],
"properties": {
"major": {
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"minor": {
"type": "integer",
"minimum": 0,
"maximum": 4294967295
}
}
},
"input": {
"type": "object",
"additionalProperties": false,
"properties": {
"up": {
"type": "boolean",
"default": false
},
"down": {
"type": "boolean",
"default": false
},
"left": {
"type": "boolean",
"default": false
},
"right": {
"type": "boolean",
"default": false
},
"a": {
"type": "boolean",
"default": false
},
"b": {
"type": "boolean",
"default": false
},
"x": {
"type": "boolean",
"default": false
},
"y": {
"type": "boolean",
"default": false
},
"l": {
"type": "boolean",
"default": false
},
"r": {
"type": "boolean",
"default": false
},
"start": {
"type": "boolean",
"default": false
},
"select": {
"type": "boolean",
"default": false
},
"touch": {
"type": "boolean",
"default": false
},
"touchX": {
"type": "integer",
"minimum": -2147483648,
"maximum": 2147483647,
"default": 0
},
"touchY": {
"type": "integer",
"minimum": -2147483648,
"maximum": 2147483647,
"default": 0
}
}
}
}
}
+78
View File
@@ -0,0 +1,78 @@
[
{
"requestId": "init",
"command": "initialize",
"params": {
"protocolVersion": {
"major": 1,
"minor": 0
},
"requiredCapabilities": [
"advance",
"capture",
"cancel"
]
}
},
{
"requestId": "boot",
"command": "boot",
"params": {
"path": "/cartridge"
}
},
{
"requestId": "reset",
"command": "reset",
"params": {}
},
{
"requestId": "input",
"command": "set_input",
"params": {
"right": true,
"touch": true,
"touchX": 123,
"touchY": 45
}
},
{
"requestId": "clear",
"command": "clear_input",
"params": {}
},
{
"requestId": "advance",
"command": "advance",
"params": {
"frames": 60
}
},
{
"requestId": "capture",
"command": "capture",
"params": {}
},
{
"requestId": "get_state",
"command": "get_state",
"params": {}
},
{
"requestId": "get_fault",
"command": "get_fault",
"params": {}
},
{
"requestId": "shutdown",
"command": "shutdown",
"params": {}
},
{
"requestId": "cancel",
"command": "cancel",
"params": {
"targetRequestId": "advance"
}
}
]
@@ -0,0 +1,666 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Prometeu headless server messages v1.0",
"$comment": "requestId additionally has a 128 UTF-8-byte bound; uint counters require lossless decoding. v1.0 producers are checked strictly. Consumers must allow compatible minor extensions.",
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"const": "hello"
},
"sessionId": {
"type": "string",
"minLength": 1
},
"protocolVersion": {
"$ref": "#/$defs/version"
},
"runtimeVersion": {
"type": "string",
"minLength": 1
},
"capabilities": {
"type": "array",
"items": {
"type": "string"
}
},
"limits": {
"$ref": "#/$defs/limits"
}
},
"required": [
"type",
"sessionId",
"protocolVersion",
"runtimeVersion",
"capabilities",
"limits"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"const": "progress"
},
"sessionId": {
"type": "string",
"minLength": 1
},
"requestId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"requested": {
"type": "integer",
"minimum": 0
},
"completed": {
"type": "integer",
"minimum": 0
}
},
"required": [
"type",
"sessionId",
"requestId",
"requested",
"completed"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"const": "response"
},
"sessionId": {
"type": "string",
"minLength": 1
},
"requestId": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 128
},
"error": {
"$ref": "#/$defs/error"
}
},
"required": [
"type",
"sessionId",
"requestId",
"error"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"const": "response"
},
"sessionId": {
"type": "string",
"minLength": 1
},
"requestId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"result": {
"anyOf": [
{
"$ref": "#/$defs/negotiated"
},
{
"$ref": "#/$defs/state"
},
{
"$ref": "#/$defs/advance"
},
{
"$ref": "#/$defs/capture"
},
{
"$ref": "#/$defs/fault"
},
{
"type": "null"
},
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"targetRequestId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"requested": {
"const": true
}
},
"required": [
"targetRequestId",
"requested"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"closed": {
"const": true
}
},
"required": [
"closed"
],
"additionalProperties": false
}
]
}
},
"required": [
"type",
"sessionId",
"requestId",
"result"
],
"additionalProperties": false
}
],
"$defs": {
"version": {
"type": "object",
"properties": {
"major": {
"const": 1
},
"minor": {
"type": "integer",
"minimum": 0
}
},
"required": [
"major",
"minor"
],
"additionalProperties": false
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object"
}
},
"required": [
"code",
"message",
"details"
],
"additionalProperties": false
},
"stack": {
"oneOf": [
{
"type": "object",
"properties": {
"kind": {
"const": "int32"
},
"value": {
"type": "integer",
"minimum": -2147483648,
"maximum": 2147483647
}
},
"required": [
"kind",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"enum": [
"int64",
"float64",
"string"
]
},
"value": {
"type": "string"
}
},
"required": [
"kind",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"const": "heap_ref"
},
"value": {
"type": "integer",
"minimum": 0
}
},
"required": [
"kind",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"const": "boolean"
},
"value": {
"type": "boolean"
}
},
"required": [
"kind",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"const": "null"
},
"value": {
"type": "null"
}
},
"required": [
"kind",
"value"
],
"additionalProperties": false
}
]
},
"state": {
"type": "object",
"properties": {
"pc": {
"type": "integer",
"minimum": 0
},
"stackTop": {
"type": "array",
"items": {
"$ref": "#/$defs/stack"
}
},
"logicalFrameIndex": {
"type": "integer",
"minimum": 0
},
"tickIndex": {
"type": "integer",
"minimum": 0
},
"appId": {
"type": "integer",
"minimum": 0
},
"status": {
"enum": [
"running",
"paused",
"terminated",
"faulted"
]
}
},
"required": [
"pc",
"stackTop",
"logicalFrameIndex",
"tickIndex",
"appId",
"status"
],
"additionalProperties": false
},
"fault": {
"oneOf": [
{
"type": "object",
"properties": {
"pc": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"summary": {
"type": "string"
},
"kind": {
"const": "vm_trap"
},
"trap": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"minimum": 0
},
"opcode": {
"type": "integer",
"minimum": 0
},
"message": {
"type": "string"
},
"pc": {
"type": "integer",
"minimum": 0
},
"span": {
"type": [
"object",
"null"
]
}
},
"required": [
"code",
"opcode",
"message",
"pc",
"span"
],
"additionalProperties": false
}
},
"required": [
"pc",
"summary",
"kind",
"trap"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"pc": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"summary": {
"type": "string"
},
"kind": {
"const": "vm_panic"
},
"message": {
"type": "string"
}
},
"required": [
"pc",
"summary",
"kind",
"message"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"pc": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"summary": {
"type": "string"
},
"kind": {
"const": "vm_init"
},
"initError": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
}
},
"required": [
"pc",
"summary",
"kind",
"initError"
],
"additionalProperties": false
}
]
},
"advance": {
"type": "object",
"properties": {
"requested": {
"type": "integer",
"minimum": 0
},
"completed": {
"type": "integer",
"minimum": 0
},
"stop": {
"enum": [
"completed",
"faulted",
"terminated",
"canceled",
"host_error"
]
},
"fault": {
"$ref": "#/$defs/fault"
},
"error": {
"$ref": "#/$defs/error"
}
},
"required": [
"requested",
"completed",
"stop"
],
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"stop": {
"const": "faulted"
}
}
},
"then": {
"required": [
"fault"
]
}
},
{
"if": {
"properties": {
"stop": {
"const": "host_error"
}
}
},
"then": {
"required": [
"error"
]
}
}
]
},
"capture": {
"type": "object",
"properties": {
"mimeType": {
"const": "image/png"
},
"encoding": {
"const": "base64"
},
"data": {
"type": "string",
"contentEncoding": "base64"
},
"width": {
"type": "integer",
"minimum": 1
},
"height": {
"type": "integer",
"minimum": 1
},
"stridePixels": {
"type": "integer",
"minimum": 1
},
"pixelFormat": {
"const": "RGBA8888"
},
"logicalFrameIndex": {
"type": "integer",
"minimum": 0
},
"frameId": {
"type": "integer",
"minimum": 0
}
},
"required": [
"mimeType",
"encoding",
"data",
"width",
"height",
"stridePixels",
"pixelFormat",
"logicalFrameIndex",
"frameId"
],
"additionalProperties": false
},
"negotiated": {
"type": "object",
"properties": {
"protocolVersion": {
"$ref": "#/$defs/version"
},
"capabilities": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"protocolVersion",
"capabilities"
],
"additionalProperties": false
},
"limits": {
"type": "object",
"properties": {
"maxFrames": {
"type": "integer",
"minimum": 1
},
"maxCommandBytes": {
"type": "integer",
"minimum": 1
},
"maxResponseBytes": {
"type": "integer",
"minimum": 1
},
"handshakeTimeoutMs": {
"type": "integer",
"minimum": 1
},
"callTimeoutMs": {
"type": "integer",
"minimum": 1
},
"shutdownTimeoutMs": {
"type": "integer",
"minimum": 1
}
},
"required": [
"maxFrames",
"maxCommandBytes",
"maxResponseBytes",
"handshakeTimeoutMs",
"callTimeoutMs",
"shutdownTimeoutMs"
],
"additionalProperties": false
}
}
}