feat: add headless automation protocol and CLI #41

Merged
bquarkz merged 1 commits from dev/studio-headless-runtime-ai-first into master 2026-09-28 16:29:02 +00:00
20 changed files with 3310 additions and 18 deletions
Generated
+590 -8
View File
@@ -18,6 +18,12 @@ version = "0.1.10"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "366ffbaa4442f4684d91e2cd7c5ea7c4ed8add41959a31447066e279e432b618"
[[package]]
name = "adler2"
version = "2.0.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
[[package]]
name = "ahash"
version = "0.8.12"
@@ -27,6 +33,7 @@ dependencies = [
"cfg-if",
"getrandom 0.3.4",
"once_cell",
"serde",
"version_check",
"zerocopy",
]
@@ -199,6 +206,12 @@ version = "1.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
[[package]]
name = "base64"
version = "0.22.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
[[package]]
name = "bindgen"
version = "0.72.1"
@@ -217,15 +230,30 @@ dependencies = [
"syn 2.0.114",
]
[[package]]
name = "bit-set"
version = "0.8.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "08807e080ed7f9d5433fa9b275196cfc35414f66a0c79d864dc51a0d825231a3"
dependencies = [
"bit-vec 0.8.0",
]
[[package]]
name = "bit-set"
version = "0.9.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "34ddef2995421ab6a5c779542c81ee77c115206f4ad9d5a8e05f4ff49716a3dd"
dependencies = [
"bit-vec",
"bit-vec 0.9.1",
]
[[package]]
name = "bit-vec"
version = "0.8.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5e764a1d40d510daf35e07be9eb06e75770908c27d411ee6c92109c9840eaaf7"
[[package]]
name = "bit-vec"
version = "0.9.1"
@@ -262,12 +290,24 @@ dependencies = [
"objc2 0.6.4",
]
[[package]]
name = "borrow-or-share"
version = "0.2.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "dc0b364ead1874514c8c2855ab558056ebfeb775653e7ae45ff72f28f8f3166c"
[[package]]
name = "bumpalo"
version = "3.19.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5dd9dc738b7a8311c7ade152424974d8115f2cdad61e8dab8dac9f2362298510"
[[package]]
name = "bytecount"
version = "0.6.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "175812e0be2bccb6abe50bb8d566126198344f707e304f45c648fd8f2cc0365e"
[[package]]
name = "bytemuck"
version = "1.24.0"
@@ -529,6 +569,15 @@ dependencies = [
"windows 0.54.0",
]
[[package]]
name = "crc32fast"
version = "1.5.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "01a7799fd6b852db0e61728dde9a204c423b44d689dbd432522543614b490e78"
dependencies = [
"cfg-if",
]
[[package]]
name = "crossbeam-utils"
version = "0.8.21"
@@ -569,6 +618,17 @@ dependencies = [
"objc2 0.6.4",
]
[[package]]
name = "displaydoc"
version = "0.2.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c6232dd377dcc64799954cbd3a9bb882e9cdc1308ccd87b1c098f1fb2eaf82a8"
dependencies = [
"proc-macro2",
"quote",
"syn 3.0.6",
]
[[package]]
name = "dlib"
version = "0.5.2"
@@ -605,6 +665,15 @@ version = "1.15.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "48c757948c5ede0e46177b7add2e67155f70e33c07fea8284df6576da70b3719"
[[package]]
name = "email_address"
version = "0.2.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e079f19b08ca6239f47f8ba8509c11cf3ea30095831f7fed61441475edd8c449"
dependencies = [
"serde",
]
[[package]]
name = "equivalent"
version = "1.0.2"
@@ -621,12 +690,54 @@ dependencies = [
"windows-sys 0.61.2",
]
[[package]]
name = "fancy-regex"
version = "0.16.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "998b056554fbe42e03ae0e152895cd1a7e1002aec800fdc6635d20270260c46f"
dependencies = [
"bit-set 0.8.0",
"regex-automata",
"regex-syntax",
]
[[package]]
name = "fdeflate"
version = "0.3.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1e6853b52649d4ac5c0bd02320cddc5ba956bdb407c4b75a2c6b75bf51500f8c"
dependencies = [
"simd-adler32",
]
[[package]]
name = "find-msvc-tools"
version = "0.1.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f449e6c6c08c865631d4890cfacf252b3d396c9bcc83adb6623cdb02a8336c41"
[[package]]
name = "flate2"
version = "1.1.10"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6e634e2e0ebac1ee034020da1ca582e17ffe4e0f5e985823721e168928136dcb"
dependencies = [
"crc32fast",
"miniz_oxide 0.9.1",
"zlib-rs",
]
[[package]]
name = "fluent-uri"
version = "0.3.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1918b65d96df47d3591bed19c5cca17e3fa5d0707318e4b5ef2eae01764df7e5"
dependencies = [
"borrow-or-share",
"ref-cast",
"serde",
]
[[package]]
name = "foldhash"
version = "0.1.5"
@@ -666,6 +777,16 @@ version = "0.3.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "aa9a19cbb55df58761df49b23516a86d432839add4af60fc256da840f66ed35b"
[[package]]
name = "fraction"
version = "0.15.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e076045bb43dac435333ed5f04caf35c7463631d0dae2deb2638d94dd0a5b872"
dependencies = [
"lazy_static",
"num",
]
[[package]]
name = "futures-core"
version = "0.3.34"
@@ -772,7 +893,7 @@ dependencies = [
"log",
"presser",
"thiserror 2.0.21",
"windows 0.54.0",
"windows 0.62.2",
]
[[package]]
@@ -845,6 +966,110 @@ version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "dfa686283ad6dd069f105e5ab091b04c62850d3e4cf5d67debad1933f55023df"
[[package]]
name = "icu_collections"
version = "2.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "fa68d21081c4a05d5a901a1c62add574c77048b6a1c67be3b50ce0b60d4ca513"
dependencies = [
"displaydoc",
"potential_utf",
"utf8_iter",
"yoke",
"zerofrom",
"zerovec",
]
[[package]]
name = "icu_locale_core"
version = "2.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d56e28588da92eee5c3201a6eff33fabdd49b62269c8938d4ff050ce4d900deb"
dependencies = [
"displaydoc",
"litemap",
"tinystr",
"writeable",
"zerovec",
]
[[package]]
name = "icu_normalizer"
version = "2.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "12f9cf5f235641ed274641dd81c3f28d870e276763d0797aeeab72317b1c646f"
dependencies = [
"icu_collections",
"icu_normalizer_data",
"icu_properties",
"icu_provider",
"smallvec",
"zerovec",
]
[[package]]
name = "icu_normalizer_data"
version = "2.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1563da1ed3e0b3bf3d74c9b85917ac9c56464d2f57242270c09c9e752f8021a0"
[[package]]
name = "icu_properties"
version = "2.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7e7ca276ad3145661a65914e6daf131ca5120cd3dcee8f8f3214b8875184a148"
dependencies = [
"displaydoc",
"icu_collections",
"icu_locale_core",
"icu_properties_data",
"icu_provider",
"zerotrie",
"zerovec",
]
[[package]]
name = "icu_properties_data"
version = "2.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e590f038c1464a96894fd6d10127e90a8be4509f56ff7ecef851b15cee0b7caa"
[[package]]
name = "icu_provider"
version = "2.3.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d27bbb9d3abbefac45d55f647c9de1d44aafcd1186eb91879afef17c396c3e73"
dependencies = [
"displaydoc",
"icu_locale_core",
"writeable",
"yoke",
"zerofrom",
"zerotrie",
"zerovec",
]
[[package]]
name = "idna"
version = "1.1.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de"
dependencies = [
"idna_adapter",
"smallvec",
"utf8_iter",
]
[[package]]
name = "idna_adapter"
version = "1.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cb68373c0d6620ef8105e855e7745e18b0d00d3bdb07fb532e434244cdb9a714"
dependencies = [
"icu_normalizer",
"icu_properties",
]
[[package]]
name = "indexmap"
version = "2.13.0"
@@ -919,6 +1144,32 @@ dependencies = [
"wasm-bindgen",
]
[[package]]
name = "jsonschema"
version = "0.33.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d46662859bc5f60a145b75f4632fbadc84e829e45df6c5de74cfc8e05acb96b5"
dependencies = [
"ahash",
"base64",
"bytecount",
"email_address",
"fancy-regex",
"fraction",
"idna",
"itoa",
"num-cmp",
"num-traits",
"once_cell",
"percent-encoding",
"referencing",
"regex",
"regex-syntax",
"serde",
"serde_json",
"uuid-simd",
]
[[package]]
name = "khronos-egl"
version = "6.0.0"
@@ -936,6 +1187,12 @@ version = "3.1.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e2db585e1d738fc771bf08a151420d3ed193d9d895a36df7f6f8a9456b911ddc"
[[package]]
name = "lazy_static"
version = "1.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
[[package]]
name = "libc"
version = "0.2.180"
@@ -981,6 +1238,12 @@ version = "0.11.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "df1d3c3b53da64cf5760482273a98e575c651a67eec7f77df96b5b642de8f039"
[[package]]
name = "litemap"
version = "0.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "47d9d19d1d6efa0109d2f65ff4c85cddd50bd572e5a00127ab10987290bcefae"
[[package]]
name = "litrs"
version = "1.0.0"
@@ -1032,6 +1295,26 @@ version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
[[package]]
name = "miniz_oxide"
version = "0.8.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316"
dependencies = [
"adler2",
"simd-adler32",
]
[[package]]
name = "miniz_oxide"
version = "0.9.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b63fbc4a50860e98e7b2aa7804ded1db5cbc3aff9193adaff57a6931bf7c4b4c"
dependencies = [
"adler2",
"simd-adler32",
]
[[package]]
name = "naga"
version = "29.0.4"
@@ -1039,7 +1322,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b2bf919621e7975acb27d881bae2fb993e0d45c8e0446e85e6272971e00dc8df"
dependencies = [
"arrayvec",
"bit-set",
"bit-set 0.9.1",
"bitflags 2.10.0",
"cfg-if",
"cfg_aliases",
@@ -1121,6 +1404,45 @@ dependencies = [
"minimal-lexical",
]
[[package]]
name = "num"
version = "0.4.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "35bd024e8b2ff75562e5f34e7f4905839deb4b22955ef5e73d2fea1b9813cb23"
dependencies = [
"num-bigint",
"num-complex",
"num-integer",
"num-iter",
"num-rational",
"num-traits",
]
[[package]]
name = "num-bigint"
version = "0.4.8"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c89e69e7e0f03bea5ef08013795c25018e101932225a656383bd384495ecc367"
dependencies = [
"num-integer",
"num-traits",
]
[[package]]
name = "num-cmp"
version = "0.1.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "63335b2e2c34fae2fb0aa2cecfd9f0832a1e24b3b32ecec612c3426d46dc8aaa"
[[package]]
name = "num-complex"
version = "0.4.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "73f88a1307638156682bada9d7604135552957b7818057dcef22705b4d509495"
dependencies = [
"num-traits",
]
[[package]]
name = "num-derive"
version = "0.4.2"
@@ -1132,6 +1454,36 @@ dependencies = [
"syn 2.0.114",
]
[[package]]
name = "num-integer"
version = "0.1.47"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7ce2d95d4b3734dc35aa2f45e1aa22cd416814592a4f9d9205e11affd5b8e10b"
dependencies = [
"num-traits",
]
[[package]]
name = "num-iter"
version = "0.1.46"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c92800bd69a1eac91786bcfe9da64a897eb72911b8dc3095decbd07429e8048b"
dependencies = [
"num-integer",
"num-traits",
]
[[package]]
name = "num-rational"
version = "0.4.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f83d14da390562dca69fc84082e73e548e1ad308d24accdedd2720017cb37824"
dependencies = [
"num-bigint",
"num-integer",
"num-traits",
]
[[package]]
name = "num-traits"
version = "0.2.19"
@@ -1477,6 +1829,12 @@ dependencies = [
"num-traits",
]
[[package]]
name = "outref"
version = "0.5.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1a80800c0488c3a21695ea981a54918fbb37abf04f4d0720c453632255e2ff0e"
[[package]]
name = "owned_ttf_parser"
version = "0.25.1"
@@ -1581,6 +1939,19 @@ version = "0.3.32"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7edddbd0b52d732b21ad9a5fab5c704c14cd949e5e9a1ec5929a24fded1b904c"
[[package]]
name = "png"
version = "0.17.16"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "82151a2fc869e011c153adc57cf2789ccb8d9906ce52c0b39a6b5697749d7526"
dependencies = [
"bitflags 1.3.2",
"crc32fast",
"fdeflate",
"flate2",
"miniz_oxide 0.8.9",
]
[[package]]
name = "polling"
version = "3.11.0"
@@ -1616,6 +1987,15 @@ dependencies = [
"portable-atomic",
]
[[package]]
name = "potential_utf"
version = "0.1.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d83eb9bc6d8e5cf568e7a1101d60ee05e81ed50ea106026f3d18deeb046d7661"
dependencies = [
"zerovec",
]
[[package]]
name = "ppv-lite86"
version = "0.2.21"
@@ -1666,8 +2046,15 @@ dependencies = [
name = "prometeu-cli"
version = "0.1.0"
dependencies = [
"base64",
"clap",
"jsonschema",
"png",
"prometeu-bytecode",
"prometeu-hal",
"prometeu-host-desktop-winit",
"prometeu-host-headless",
"serde_json",
]
[[package]]
@@ -1718,11 +2105,17 @@ dependencies = [
name = "prometeu-host-headless"
version = "0.1.0"
dependencies = [
"base64",
"getrandom 0.3.4",
"png",
"prometeu-bytecode",
"prometeu-drivers",
"prometeu-firmware",
"prometeu-hal",
"prometeu-system",
"prometeu-vm",
"serde",
"serde_json",
]
[[package]]
@@ -1777,9 +2170,9 @@ dependencies = [
[[package]]
name = "quote"
version = "1.0.43"
version = "1.0.47"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "dc74d9a594b72ae6656596548f56f667211f8a97b3d4c3d467150794690dc40a"
checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
dependencies = [
"proc-macro2",
]
@@ -1871,6 +2264,40 @@ dependencies = [
"bitflags 2.10.0",
]
[[package]]
name = "ref-cast"
version = "1.0.27"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7e440fb4e4b4147295338efb76001ab9e4efc0e5839df2c47fc5ac2381d365c3"
dependencies = [
"ref-cast-impl",
]
[[package]]
name = "ref-cast-impl"
version = "1.0.27"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "92ecd8964f8453721699a1ed72037b0db49ce2f5a5138486ee89bed6f67cdf3a"
dependencies = [
"proc-macro2",
"quote",
"syn 3.0.6",
]
[[package]]
name = "referencing"
version = "0.33.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9e9c261f7ce75418b3beadfb3f0eb1299fe8eb9640deba45ffa2cb783098697d"
dependencies = [
"ahash",
"fluent-uri",
"once_cell",
"parking_lot",
"percent-encoding",
"serde_json",
]
[[package]]
name = "regex"
version = "1.12.2"
@@ -2053,6 +2480,12 @@ version = "1.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
[[package]]
name = "simd-adler32"
version = "0.3.10"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea"
[[package]]
name = "slab"
version = "0.4.11"
@@ -2117,6 +2550,12 @@ dependencies = [
"bitflags 2.10.0",
]
[[package]]
name = "stable_deref_trait"
version = "1.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
[[package]]
name = "static_assertions"
version = "1.1.0"
@@ -2157,6 +2596,17 @@ dependencies = [
"unicode-ident",
]
[[package]]
name = "synstructure"
version = "0.14.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "901704edd0dfe137f1987838ee4f259e4e063c31371bdb423f7ae38ec6f77f02"
dependencies = [
"proc-macro2",
"quote",
"syn 3.0.6",
]
[[package]]
name = "termcolor"
version = "1.4.1"
@@ -2231,6 +2681,16 @@ dependencies = [
"strict-num",
]
[[package]]
name = "tinystr"
version = "0.8.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b1e27c91459209c2986af3dcf603a5a74a4368754ce37414f59acc971167f643"
dependencies = [
"displaydoc",
"zerovec",
]
[[package]]
name = "toml_datetime"
version = "0.7.5+spec-1.1.0"
@@ -2310,18 +2770,51 @@ version = "0.1.14"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7dd6e30e90baa6f72411720665d41d89b9a3d039dc45b8faea1ddd07f617f6af"
[[package]]
name = "utf8_iter"
version = "1.0.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
[[package]]
name = "utf8parse"
version = "0.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
[[package]]
name = "uuid"
version = "1.26.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "2ef6dac1e96601b4fb3acccccff2139741fcb757cb9a36089bf5be91cfb285ce"
dependencies = [
"js-sys",
"wasm-bindgen",
]
[[package]]
name = "uuid-simd"
version = "0.8.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "23b082222b4f6619906941c17eb2297fff4c2fb96cb60164170522942a200bd8"
dependencies = [
"outref",
"uuid",
"vsimd",
]
[[package]]
name = "version_check"
version = "0.9.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
[[package]]
name = "vsimd"
version = "0.8.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5c3082ca00d5a5ef149bb8b555a72ae84c9c59f7250f013ac822ac2e49b19c64"
[[package]]
name = "walkdir"
version = "2.5.0"
@@ -2568,8 +3061,8 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "2f519832254e56965a9940c4af57dcb75f702b6f6fa4a0b172f685395843a4d7"
dependencies = [
"arrayvec",
"bit-set",
"bit-vec",
"bit-set 0.9.1",
"bit-vec 0.9.1",
"bitflags 2.10.0",
"bytemuck",
"cfg_aliases",
@@ -2640,7 +3133,7 @@ dependencies = [
"android_system_properties",
"arrayvec",
"ash",
"bit-set",
"bit-set 0.9.1",
"bitflags 2.10.0",
"block2 0.6.2",
"bytemuck",
@@ -3091,6 +3584,12 @@ version = "0.46.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f17a85883d4e6d00e8a97c586de764dabcc06133f7f1d55dce5cdc070ad7fe59"
[[package]]
name = "writeable"
version = "0.6.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3ad82d2a33cdc9674dc7465672f271e096168fcdbe0f799d9e6db8c5892679dc"
[[package]]
name = "x11-dl"
version = "2.21.0"
@@ -3154,6 +3653,29 @@ version = "0.8.28"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3ae8337f8a065cfc972643663ea4279e04e7256de865aa66fe25cec5fb912d3f"
[[package]]
name = "yoke"
version = "0.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "709fe23a0424b6a435d82152b1bd3fdfb0833487d5fa90d05d42762a9891fef5"
dependencies = [
"stable_deref_trait",
"yoke-derive",
"zerofrom",
]
[[package]]
name = "yoke-derive"
version = "0.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "33811428bee40dbceb6d545e95754741d17a6aef9a4849f0fd62e2ba4f412a78"
dependencies = [
"proc-macro2",
"quote",
"syn 3.0.6",
"synstructure",
]
[[package]]
name = "zerocopy"
version = "0.8.33"
@@ -3174,6 +3696,66 @@ dependencies = [
"syn 2.0.114",
]
[[package]]
name = "zerofrom"
version = "0.1.8"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272"
dependencies = [
"zerofrom-derive",
]
[[package]]
name = "zerofrom-derive"
version = "0.1.8"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f75b4683f6c7f45248d4d64056a24298c6281e0993356d7d1b4a1a962ef10d4a"
dependencies = [
"proc-macro2",
"quote",
"syn 3.0.6",
"synstructure",
]
[[package]]
name = "zerotrie"
version = "0.2.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4ea269c3bd32f0a32c321907a2ae912ba6f4649bb0fc764a15627e99a7095a3f"
dependencies = [
"displaydoc",
"yoke",
"zerofrom",
]
[[package]]
name = "zerovec"
version = "0.11.8"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "bb0464e17806c1d976d5cba29399c7f08e516e279e2ba493f63123b5fca67dd8"
dependencies = [
"yoke",
"zerofrom",
"zerovec-derive",
]
[[package]]
name = "zerovec-derive"
version = "0.11.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "34df6fc39dbd26ddc9c10e6a2984476e13acce22e64e4487636ef494369225da"
dependencies = [
"proc-macro2",
"quote",
"syn 3.0.6",
]
[[package]]
name = "zlib-rs"
version = "0.6.8"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b268e58e7c693d7c271f93ffc4ba3b380412554231c85bf61ca7af91042a4112"
[[package]]
name = "zmij"
version = "1.0.14"
@@ -12,6 +12,12 @@ prometeu-drivers = { path = "../../console/prometeu-drivers" }
prometeu-firmware = { path = "../../console/prometeu-firmware" }
prometeu-hal = { path = "../../console/prometeu-hal" }
prometeu-system = { path = "../../console/prometeu-system" }
prometeu-vm = { path = "../../console/prometeu-vm" }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
base64 = "0.22"
png = "0.17"
getrandom = "0.3"
[[bench]]
name = "temporal"
@@ -0,0 +1,406 @@
//! Versioned external tooling boundary; the host API itself remains synchronous.
mod wire;
pub use wire::Limits;
use crate::{AdvanceFrameOutcome, HeadlessHost};
use serde_json::{Value, json};
use std::io::{self, BufRead, Write};
use std::sync::{Arc, Mutex, mpsc};
use wire::{CAPABILITIES, Command, Request, WireError};
#[derive(Default)]
struct Control {
active: Option<String>,
advancing: bool,
canceled: bool,
}
enum Job {
Work(String, Command),
Stop(Option<String>),
ReadError(io::Error),
}
struct Output<W> {
writer: Mutex<W>,
session: String,
limit: usize,
}
impl<W: Write> Output<W> {
fn send(&self, value: Value) -> io::Result<()> {
let mut bytes = serde_json::to_vec(&value)?;
if bytes.len() > self.limit {
bytes = serde_json::to_vec(&json!({"type":"response","sessionId":self.session,
"requestId":value.get("requestId"),"error":{"code":"response_too_large",
"message":"response exceeds configured limit","details":{"maxResponseBytes":self.limit}}}))?;
}
if bytes.len() > self.limit {
return Err(io::Error::other("response limit cannot contain error"));
}
let mut writer = self.writer.lock().map_err(|_| io::Error::other("output poisoned"))?;
writer.write_all(&bytes)?;
writer.write_all(b"\n")?;
writer.flush()
}
fn reply(&self, id: Option<&str>, result: Result<Value, WireError>) -> io::Result<()> {
let mut value = json!({"type":"response","sessionId":self.session,"requestId":id});
match result {
Ok(r) => value["result"] = r,
Err(e) => value["error"] = serde_json::to_value(e)?,
}
self.send(value)
}
}
enum Line {
Data(Vec<u8>),
Oversized,
Truncated,
Eof,
}
/// Consume at most one line without ever accumulating more than the configured bound.
fn read_line(reader: &mut impl BufRead, limit: usize) -> io::Result<Line> {
let mut bytes = Vec::new();
let mut oversized = false;
loop {
let chunk = reader.fill_buf()?;
if chunk.is_empty() {
return Ok(if oversized {
Line::Oversized
} else if bytes.is_empty() {
Line::Eof
} else {
Line::Truncated
});
}
let newline = chunk.iter().position(|b| *b == b'\n');
let length = newline.unwrap_or(chunk.len());
if !oversized {
if length > limit.saturating_sub(bytes.len()) {
oversized = true;
bytes.clear();
} else {
bytes.extend_from_slice(&chunk[..length]);
}
}
reader.consume(length + usize::from(newline.is_some()));
if newline.is_some() {
if bytes.last() == Some(&b'\r') {
bytes.pop();
}
return Ok(if oversized { Line::Oversized } else { Line::Data(bytes) });
}
}
}
fn read_commands<R: BufRead, W: Write>(
mut input: R,
output: &Output<W>,
control: &Mutex<Control>,
sender: &mpsc::Sender<Job>,
limits: &Limits,
) -> io::Result<()> {
let mut initialized = false;
loop {
let bytes = match read_line(&mut input, limits.max_command_bytes)? {
Line::Eof => break,
Line::Truncated => {
output.reply(None, Err(WireError::new("invalid_request", "EOF before LF")))?;
break;
}
Line::Oversized => {
output.reply(
None,
Err(WireError::new("request_too_large", "command exceeds configured limit")),
)?;
continue;
}
Line::Data(bytes) => bytes,
};
let raw: Value = match serde_json::from_slice(&bytes) {
Ok(value) => value,
Err(error) => {
output.reply(None, Err(WireError::new("invalid_request", error.to_string())))?;
continue;
}
};
let id = raw
.get("requestId")
.and_then(Value::as_str)
.filter(|id| wire::valid_id(id))
.map(str::to_owned);
let request = serde_json::from_value::<Request>(raw)
.map_err(|e| WireError::new("invalid_request", e.to_string()))
.and_then(wire::parse);
let (id, command) = match request {
Ok(value) => value,
Err(error) => {
output.reply(id.as_deref(), Err(error))?;
continue;
}
};
if let Command::Shutdown = command {
let mut c = control.lock().unwrap();
c.canceled = true;
sender.send(Job::Stop(Some(id))).map_err(|_| io::Error::other("execution stopped"))?;
return Ok(());
}
if let Command::Initialize(params) = command {
let result = if initialized {
Err(WireError::new("already_initialized", "session already initialized"))
} else if params.protocol_version.major != 1 {
Err(WireError::new("incompatible_version", "protocol major must be 1"))
} else if params
.required_capabilities
.iter()
.any(|c| !CAPABILITIES.contains(&c.as_str()))
{
Err(WireError::new("unsupported_capability", "required capability unavailable"))
} else {
initialized = true;
Ok(json!({"protocolVersion":{"major":1,"minor":0},"capabilities":CAPABILITIES}))
};
output.reply(Some(&id), result)?;
continue;
}
if !initialized {
output.reply(Some(&id), Err(WireError::new("not_initialized", "initialize first")))?;
continue;
}
let mut c = control.lock().unwrap();
if let Command::Cancel(params) = command {
let result = if c.advancing && c.active.as_deref() == Some(&params.target_request_id) {
c.canceled = true;
Ok(json!({"targetRequestId":params.target_request_id,"requested":true}))
} else {
Err(WireError::new("not_cancelable", "no matching active advance"))
};
output.reply(Some(&id), result)?;
continue;
}
if c.active.is_some() {
output.reply(Some(&id), Err(WireError::new("busy", "a host operation is active")))?;
continue;
}
if let Command::Advance(params) = &command
&& params.frames > limits.max_frames
{
output.reply(
Some(&id),
Err(WireError::new("limit_exceeded", "frames exceeds maxFrames")),
)?;
continue;
}
c.active = Some(id.clone());
c.advancing = matches!(command, Command::Advance(_));
c.canceled = false;
sender.send(Job::Work(id, command)).map_err(|_| io::Error::other("execution stopped"))?;
}
let mut c = control.lock().unwrap();
c.canceled = true;
sender.send(Job::Stop(None)).map_err(|_| io::Error::other("execution stopped"))
}
fn execute<W: Write>(
host: &mut HeadlessHost,
command: Command,
id: &str,
output: &Output<W>,
control: &Mutex<Control>,
) -> io::Result<Result<Value, WireError>> {
Ok(match command {
Command::Boot(p) => {
host.boot(p.path).map(|()| wire::state(host.get_state())).map_err(wire::host_error)
}
Command::Reset => {
host.reset();
Ok(wire::state(host.get_state()))
}
Command::SetInput(p) => {
host.set_input(p.into());
Ok(json!({}))
}
Command::ClearInput => {
host.clear_input();
Ok(json!({}))
}
Command::GetState => Ok(wire::state(host.get_state())),
Command::GetFault => Ok(host.get_fault().as_ref().map(wire::fault).unwrap_or(Value::Null)),
Command::Capture => host.capture_frame().map_err(wire::host_error).and_then(wire::capture),
Command::Advance(p) => {
let mut result = json!({"requested":p.frames,"completed":0,"stop":"completed"});
for completed in 0..p.frames {
if control.lock().unwrap().canceled {
result["stop"] = json!("canceled");
break;
}
match host.advance_frame() {
Ok(AdvanceFrameOutcome::FrameCompleted { .. }) => {
result["completed"] = json!(completed + 1);
output.send(
json!({"type":"progress","sessionId":output.session,"requestId":id,
"requested":p.frames,"completed":completed + 1}),
)?;
}
Ok(AdvanceFrameOutcome::Faulted(report)) => {
result["stop"] = json!("faulted");
result["fault"] = wire::fault(&report);
break;
}
Ok(AdvanceFrameOutcome::Terminated) => {
result["stop"] = json!("terminated");
break;
}
Err(error) => {
result["stop"] = json!("host_error");
result["error"] = serde_json::to_value(wire::host_error(error))?;
break;
}
}
}
Ok(result)
}
_ => unreachable!("reader handles control commands"),
})
}
/// Serve one process session. The input reader stays responsive while the owner
/// executes a frame. On fatal output failure the process caller must exit; a
/// blocking OS stdin reader cannot be joined until that input is closed.
pub fn serve<R: BufRead + Send + 'static, W: Write + Send + 'static>(
input: R,
writer: W,
limits: Limits,
runtime_version: &str,
) -> io::Result<()> {
limits.validate()?;
let mut random = [0u8; 16];
getrandom::fill(&mut random).map_err(|e| io::Error::other(e.to_string()))?;
let session: String = random.iter().map(|v| format!("{v:02x}")).collect();
let output =
Arc::new(Output { writer: Mutex::new(writer), session, limit: limits.max_response_bytes });
output.send(
json!({"type":"hello","sessionId":output.session,"protocolVersion":{"major":1,"minor":0},
"runtimeVersion":runtime_version,"capabilities":CAPABILITIES,"limits":limits}),
)?;
let control = Arc::new(Mutex::new(Control::default()));
let (sender, receiver) = mpsc::channel();
let reader_output = output.clone();
let reader_control = control.clone();
let reader = std::thread::spawn(move || {
if let Err(error) = read_commands(input, &reader_output, &reader_control, &sender, &limits)
{
reader_control.lock().unwrap().canceled = true;
let _ = sender.send(Job::ReadError(error));
}
});
let mut host = HeadlessHost::new();
while let Ok(job) = receiver.recv() {
match job {
Job::Work(id, command) => {
let result = execute(&mut host, command, &id, &output, &control)?;
// Release authority under the same lock as response publication:
// a client reacting to this reply cannot race a stale busy flag.
let mut c = control.lock().unwrap();
output.reply(Some(&id), result)?;
c.active = None;
c.advancing = false;
}
Job::Stop(id) => {
drop(host);
if let Some(id) = id {
output.reply(Some(&id), Ok(json!({"closed":true})))?;
}
reader.join().map_err(|_| io::Error::other("input reader panicked"))?;
return Ok(());
}
Job::ReadError(error) => return Err(error),
}
}
reader.join().map_err(|_| io::Error::other("input reader panicked"))?;
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
use std::io::{BufReader, Cursor};
#[test]
fn bounded_lines_accept_fragmentation_and_recover_after_oversize() {
let mut reader = BufReader::with_capacity(2, Cursor::new(b"12345\n123456\nok\r\n"));
assert!(matches!(read_line(&mut reader, 5).unwrap(), Line::Data(v) if v == b"12345"));
assert!(matches!(read_line(&mut reader, 5).unwrap(), Line::Oversized));
assert!(matches!(read_line(&mut reader, 5).unwrap(), Line::Data(v) if v == b"ok"));
assert!(matches!(read_line(&mut reader, 5).unwrap(), Line::Eof));
assert!(matches!(read_line(&mut Cursor::new(b"no LF"), 10).unwrap(), Line::Truncated));
}
#[test]
fn input_snapshot_is_replacement_and_rejects_unknown_fields() {
let input: wire::Input = serde_json::from_value(json!({"right":true})).unwrap();
let signals: prometeu_hal::InputSignals = input.into();
assert!(signals.right_signal);
assert!(!signals.left_signal);
assert_eq!(signals.x_pos, 0);
assert!(serde_json::from_value::<wire::Input>(json!({"rigth":true})).is_err());
}
#[test]
fn response_limit_counts_the_complete_envelope_and_keeps_correlation() {
let output =
Output { writer: Mutex::new(Vec::new()), session: "session".into(), limit: 4096 };
output.reply(Some("capture"), Ok(json!({"data":"x".repeat(4096)}))).unwrap();
let bytes = output.writer.into_inner().unwrap();
assert!(bytes.len() <= 4097);
let result: Value = serde_json::from_slice(&bytes).unwrap();
assert_eq!(result["requestId"], "capture");
assert_eq!(result["sessionId"], "session");
assert_eq!(result["error"]["code"], "response_too_large");
assert!(result.get("result").is_none());
}
#[test]
fn distributed_request_fixtures_are_accepted_by_the_actual_parser() {
let requests: Vec<Value> = serde_json::from_str(include_str!(
"../../../../../devtools/headless-protocol/requests.json"
))
.unwrap();
assert_eq!(requests.len(), 11);
for request in requests {
wire::parse(serde_json::from_value(request).unwrap()).unwrap();
}
}
#[test]
fn capture_preserves_independent_ids_and_excludes_padding_without_channel_loss() {
use base64::Engine as _;
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::{FrameId, OwnedRgba8888Frame, RenderOwnership};
let frame = OwnedRgba8888Frame::new(
FrameId::new(91),
RenderOwnership::new(1, AppMode::Game, 41),
1,
2,
2,
vec![0x12345678, 0xffffffff, 0xabcdef01, 0xffffffff],
)
.unwrap();
let capture =
wire::capture(crate::CapturedFrame { logical_frame_index: 7, frame }).unwrap();
assert_eq!(capture["logicalFrameIndex"], 7);
assert_eq!(capture["frameId"], 91);
assert_eq!(capture["stridePixels"], 2);
let png = base64::engine::general_purpose::STANDARD
.decode(capture["data"].as_str().unwrap())
.unwrap();
let mut reader = png::Decoder::new(Cursor::new(png)).read_info().unwrap();
let mut bytes = vec![0; reader.output_buffer_size()];
let info = reader.next_frame(&mut bytes).unwrap();
assert_eq!((info.width, info.height), (1, 2));
assert_eq!(&bytes[..info.buffer_size()], &[0x12, 0x34, 0x56, 0x78, 0xab, 0xcd, 0xef, 0x01]);
}
}
@@ -0,0 +1,330 @@
use base64::{Engine as _, engine::general_purpose::STANDARD};
use prometeu_bytecode::Value as VmValue;
use prometeu_hal::InputSignals;
use prometeu_system::CrashReport;
use prometeu_vm::VmInitError;
use serde::{Deserialize, Serialize};
use serde_json::{Value, json};
use std::io;
use crate::{CapturedFrame, HostError, HostExecutionStatus, HostState};
pub const CAPABILITIES: &[&str] = &[
"boot",
"reset",
"set_input",
"clear_input",
"advance",
"capture",
"get_state",
"get_fault",
"cancel",
"shutdown",
];
#[derive(Clone, Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct Limits {
pub max_frames: u64,
pub max_command_bytes: usize,
pub max_response_bytes: usize,
pub handshake_timeout_ms: u64,
pub call_timeout_ms: u64,
pub shutdown_timeout_ms: u64,
}
impl Default for Limits {
fn default() -> Self {
Self {
max_frames: 600,
max_command_bytes: 64 * 1024,
max_response_bytes: 32 * 1024 * 1024,
handshake_timeout_ms: 5_000,
call_timeout_ms: 60_000,
shutdown_timeout_ms: 5_000,
}
}
}
impl Limits {
pub fn validate(&self) -> io::Result<()> {
if self.max_frames == 0
|| self.max_command_bytes < 4096
|| self.max_response_bytes < 4096
|| self.handshake_timeout_ms == 0
|| self.call_timeout_ms == 0
|| self.shutdown_timeout_ms == 0
{
return Err(io::Error::new(
io::ErrorKind::InvalidInput,
"limits must be positive and message bounds at least 4096 bytes",
));
}
Ok(())
}
}
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields, rename_all = "camelCase")]
pub(super) struct Request {
pub request_id: String,
pub command: String,
pub params: Value,
}
pub(super) fn valid_id(id: &str) -> bool {
!id.is_empty() && id.len() <= 128
}
#[derive(Debug, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub(super) struct Version {
pub major: u32,
pub minor: u32,
}
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields, rename_all = "camelCase")]
pub(super) struct Initialize {
pub protocol_version: Version,
pub required_capabilities: Vec<String>,
}
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub(super) struct Boot {
pub path: String,
}
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub(super) struct Advance {
pub frames: u64,
}
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields, rename_all = "camelCase")]
pub(super) struct Cancel {
pub target_request_id: String,
}
#[derive(Debug, Default, Deserialize)]
#[serde(default, deny_unknown_fields, rename_all = "camelCase")]
pub(super) struct Input {
up: bool,
down: bool,
left: bool,
right: bool,
a: bool,
b: bool,
x: bool,
y: bool,
l: bool,
r: bool,
start: bool,
select: bool,
touch: bool,
touch_x: i32,
touch_y: i32,
}
impl From<Input> for InputSignals {
fn from(s: Input) -> Self {
Self {
up_signal: s.up,
down_signal: s.down,
left_signal: s.left,
right_signal: s.right,
a_signal: s.a,
b_signal: s.b,
x_signal: s.x,
y_signal: s.y,
l_signal: s.l,
r_signal: s.r,
start_signal: s.start,
select_signal: s.select,
f_signal: s.touch,
x_pos: s.touch_x,
y_pos: s.touch_y,
}
}
}
#[derive(Debug)]
pub(super) enum Command {
Initialize(Initialize),
Boot(Boot),
Reset,
SetInput(Input),
ClearInput,
Advance(Advance),
Capture,
GetState,
GetFault,
Cancel(Cancel),
Shutdown,
}
fn params<T: serde::de::DeserializeOwned>(value: Value) -> Result<T, WireError> {
serde_json::from_value(value).map_err(|e| WireError::new("invalid_params", e.to_string()))
}
fn empty(value: &Value) -> Result<(), WireError> {
if value.as_object().is_some_and(|v| v.is_empty()) {
Ok(())
} else {
Err(WireError::new("invalid_params", "expected an empty params object"))
}
}
pub(super) fn parse(req: Request) -> Result<(String, Command), WireError> {
if !valid_id(&req.request_id) {
return Err(WireError::new("invalid_request", "requestId must contain 1..128 UTF-8 bytes"));
}
let command = match req.command.as_str() {
"initialize" => Command::Initialize(params(req.params)?),
"boot" => {
let p: Boot = params(req.params)?;
if p.path.trim().is_empty() {
return Err(WireError::new("invalid_params", "path is empty"));
}
Command::Boot(p)
}
"advance" => Command::Advance(params(req.params)?),
"set_input" => Command::SetInput(params(req.params)?),
"cancel" => {
let p: Cancel = params(req.params)?;
if !valid_id(&p.target_request_id) {
return Err(WireError::new("invalid_params", "invalid targetRequestId"));
}
Command::Cancel(p)
}
"reset" | "clear_input" | "capture" | "get_state" | "get_fault" | "shutdown" => {
empty(&req.params)?;
match req.command.as_str() {
"reset" => Command::Reset,
"clear_input" => Command::ClearInput,
"capture" => Command::Capture,
"get_state" => Command::GetState,
"get_fault" => Command::GetFault,
_ => Command::Shutdown,
}
}
_ => return Err(WireError::new("unknown_command", "unknown command")),
};
Ok((req.request_id, command))
}
#[derive(Debug, Serialize)]
pub(super) struct WireError {
pub code: &'static str,
pub message: String,
pub details: Value,
}
impl WireError {
pub fn new(code: &'static str, message: impl Into<String>) -> Self {
Self { code, message: message.into(), details: json!({}) }
}
}
pub(super) fn host_error(error: HostError) -> WireError {
let (code, details) = match &error {
HostError::AlreadyBooted => ("already_booted", json!({})),
HostError::BootFailed { reason, report } => {
("boot_failed", json!({"reason":reason,"fault":report.as_ref().map(fault)}))
}
HostError::InvalidState { operation, status } => {
("invalid_state", json!({"operation":operation,"status":status_name(*status)}))
}
HostError::FrameAdvanceWatchdogExpired { host_tick_limit } => {
("watchdog_expired", json!({"hostTickLimit":host_tick_limit}))
}
HostError::FrameNotPublished { previous } => {
("frame_not_published", json!({"previousFrameId":previous.map(|id| id.get())}))
}
HostError::NoFrameAvailable => ("no_frame_available", json!({})),
};
WireError { code, message: error.to_string(), details }
}
fn status_name(status: HostExecutionStatus) -> &'static str {
match status {
HostExecutionStatus::Running => "running",
HostExecutionStatus::Paused => "paused",
HostExecutionStatus::Terminated => "terminated",
HostExecutionStatus::Faulted => "faulted",
}
}
fn stack_value(value: &VmValue) -> Value {
match value {
VmValue::Int32(v) => json!({"kind":"int32","value":v}),
VmValue::Int64(v) => json!({"kind":"int64","value":v.to_string()}),
VmValue::Float(v) => json!({"kind":"float64","value":v.to_string()}),
VmValue::Boolean(v) => json!({"kind":"boolean","value":v}),
VmValue::String(v) => json!({"kind":"string","value":v.as_ref()}),
VmValue::HeapRef(v) => json!({"kind":"heap_ref","value":v.0}),
VmValue::Null => json!({"kind":"null","value":null}),
}
}
pub(super) fn state(s: HostState) -> Value {
json!({"pc":s.pc,"stackTop":s.stack_top.iter().map(stack_value).collect::<Vec<_>>(),
"logicalFrameIndex":s.frame_index,"tickIndex":s.tick_index,"appId":s.app_id,
"status":status_name(s.status)})
}
pub(super) fn fault(report: &CrashReport) -> Value {
let mut result = json!({"kind":report.kind(),"pc":report.pc(),"summary":report.summary()});
match report {
CrashReport::VmTrap { trap } => {
result["trap"] = json!({"code":trap.code,"opcode":trap.opcode,
"message":trap.message,"pc":trap.pc,"span":trap.span});
}
CrashReport::VmPanic { message, .. } => {
result["message"] = json!(message);
}
CrashReport::VmInit { error } => {
let code = match error {
VmInitError::InvalidFormat => "invalid_format",
VmInitError::UnsupportedFormat => "unsupported_format",
VmInitError::ImageLoadFailed(_) => "image_load_failed",
VmInitError::LoaderPatchFailed(_) => "loader_patch_failed",
VmInitError::EntrypointNotFound => "entrypoint_not_found",
VmInitError::VerificationFailed(_) => "verification_failed",
};
result["initError"] = json!({"code":code,"message":format!("{error:?}")});
}
}
result
}
pub(super) fn capture(c: CapturedFrame) -> Result<Value, WireError> {
let frame = c.frame;
let width = u32::try_from(frame.width)
.map_err(|_| WireError::new("capture_failed", "width exceeds PNG limit"))?;
let height = u32::try_from(frame.height)
.map_err(|_| WireError::new("capture_failed", "height exceeds PNG limit"))?;
let mut rgba = Vec::new();
for y in 0..frame.height {
for pixel in frame.row(y).ok_or_else(|| WireError::new("capture_failed", "invalid row"))? {
rgba.extend_from_slice(&pixel.to_be_bytes());
}
}
let mut bytes = Vec::new();
{
let mut encoder = png::Encoder::new(&mut bytes, width, height);
encoder.set_color(png::ColorType::Rgba);
encoder.set_depth(png::BitDepth::Eight);
let mut writer =
encoder.write_header().map_err(|e| WireError::new("capture_failed", e.to_string()))?;
writer
.write_image_data(&rgba)
.map_err(|e| WireError::new("capture_failed", e.to_string()))?;
writer.finish().map_err(|e| WireError::new("capture_failed", e.to_string()))?;
}
Ok(json!({"mimeType":"image/png","encoding":"base64","data":STANDARD.encode(bytes),
"width":width,"height":height,"stridePixels":frame.stride_pixels,"pixelFormat":"RGBA8888",
"logicalFrameIndex":c.logical_frame_index,"frameId":frame.frame_id.get()}))
}
@@ -6,6 +6,7 @@
//! The desktop host's `stepFrame` command still advances on the 60 Hz winit loop.
//! That pacing stays in `prometeu-host-desktop-winit` until a later protocol agenda.
pub mod automation;
mod host;
pub use host::{
+15
View File
@@ -13,11 +13,26 @@ path = "src/main.rs"
name = "prometeu-runtime"
path = "src/bin/prometeu-runtime.rs"
[[bin]]
name = "prometeu-headless"
path = "src/bin/prometeu-headless.rs"
[package.metadata.dist]
dist = true
include = [
"../../../devtools/headless-protocol",
"../../../docs/specs/runtime/11a-headless-automation-protocol.md",
]
[dependencies]
clap = { version = "4.5", features = ["derive"] }
prometeu-host-desktop-winit = { path = "../../host/prometeu-host-desktop-winit" }
prometeu-host-headless = { path = "../../host/prometeu-host-headless" }
[dev-dependencies]
jsonschema = { version = "0.33", default-features = false }
serde_json = "1"
prometeu-bytecode = { path = "../../console/prometeu-bytecode" }
prometeu-hal = { path = "../../console/prometeu-hal" }
base64 = "0.22"
png = "0.17"
@@ -0,0 +1,17 @@
use clap::Parser;
use prometeu_cli::{HeadlessArgs, run_headless};
#[derive(Parser)]
#[command(
name = "prometeu-headless",
version,
about = "Deterministic headless JSONL automation host"
)]
struct Cli {
#[command(flatten)]
options: HeadlessArgs,
}
fn main() -> std::io::Result<()> {
run_headless(Cli::parse().options)
}
+62
View File
@@ -0,0 +1,62 @@
//! Shared CLI options for the dispatcher and its headless executable.
use clap::Args;
use prometeu_host_headless::automation::Limits;
#[derive(Args, Debug)]
pub struct HeadlessArgs {
/// Use the versioned JSONL stdin/stdout protocol (required).
#[arg(long, required = true)]
pub stdio: bool,
#[arg(long, default_value_t = 600)]
pub max_frames: u64,
#[arg(long, default_value_t = 65536)]
pub max_command_bytes: usize,
#[arg(long, default_value_t = 33554432)]
pub max_response_bytes: usize,
#[arg(long, default_value_t = 5000)]
pub handshake_timeout_ms: u64,
#[arg(long, default_value_t = 60000)]
pub call_timeout_ms: u64,
#[arg(long, default_value_t = 5000)]
pub shutdown_timeout_ms: u64,
}
impl HeadlessArgs {
pub fn limits(&self) -> Limits {
Limits {
max_frames: self.max_frames,
max_command_bytes: self.max_command_bytes,
max_response_bytes: self.max_response_bytes,
handshake_timeout_ms: self.handshake_timeout_ms,
call_timeout_ms: self.call_timeout_ms,
shutdown_timeout_ms: self.shutdown_timeout_ms,
}
}
pub fn forwarded_args(&self) -> Vec<String> {
vec![
"--stdio".into(),
"--max-frames".into(),
self.max_frames.to_string(),
"--max-command-bytes".into(),
self.max_command_bytes.to_string(),
"--max-response-bytes".into(),
self.max_response_bytes.to_string(),
"--handshake-timeout-ms".into(),
self.handshake_timeout_ms.to_string(),
"--call-timeout-ms".into(),
self.call_timeout_ms.to_string(),
"--shutdown-timeout-ms".into(),
self.shutdown_timeout_ms.to_string(),
]
}
}
pub fn run_headless(args: HeadlessArgs) -> std::io::Result<()> {
prometeu_host_headless::automation::serve(
std::io::BufReader::new(std::io::stdin()),
std::io::stdout(),
args.limits(),
env!("CARGO_PKG_VERSION"),
)
}
+8
View File
@@ -19,6 +19,8 @@ struct Cli {
#[derive(Subcommand)]
enum Commands {
/// Starts the versioned headless automation process (no native window).
Headless(prometeu_cli::HeadlessArgs),
/// Executes a cartridge using the available runtime.
Run {
/// Path to the cartridge (directory or .pmc file).
@@ -65,6 +67,11 @@ fn main() {
};
match cli.command {
Some(Commands::Headless(options)) => {
let args = options.forwarded_args();
let borrowed: Vec<&str> = args.iter().map(String::as_str).collect();
dispatch(&exe_dir, "prometeu-headless", &borrowed);
}
Some(Commands::Run { cart }) => {
dispatch(&exe_dir, "prometeu-runtime", &["--run", &cart]);
}
@@ -99,6 +106,7 @@ fn dispatch(exe_dir: &Path, bin_name: &str, args: &[&str]) {
"prometeu: command '{}' is not yet available in this distribution on {}",
match bin_name {
"prometeu-runtime" => "run/debug",
"prometeu-headless" => "headless",
"prometeuc" => "build/verify c",
"prometeup" => "pack/verify p",
_ => bin_name,
@@ -0,0 +1,615 @@
use base64::{Engine as _, engine::general_purpose::STANDARD};
use prometeu_bytecode::SourceSpan;
use prometeu_bytecode::assembler::assemble;
use prometeu_bytecode::model::{BytecodeModule, DebugInfo, Export, FunctionMeta, SyscallDecl};
use prometeu_host_headless::{AdvanceFramesStop, HeadlessHost};
use serde_json::{Value, json};
use std::collections::HashMap;
use std::fs;
use std::io::{BufRead, BufReader, Write};
use std::path::{Path, PathBuf};
use std::process::{Child, ChildStdin, Command, Stdio};
use std::sync::{
atomic::{AtomicU64, Ordering},
mpsc,
};
use std::time::{Duration, Instant};
struct TempDir(PathBuf);
impl TempDir {
fn new() -> Self {
static COUNTER: AtomicU64 = AtomicU64::new(0);
let path = std::env::temp_dir().join(format!(
"prometeu-protocol-test-{}-{}-{}",
std::process::id(),
std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos(),
COUNTER.fetch_add(1, Ordering::Relaxed)
));
fs::create_dir(&path).unwrap();
Self(path)
}
}
impl Drop for TempDir {
fn drop(&mut self) {
let _ = fs::remove_dir_all(&self.0);
}
}
struct Client {
child: Child,
input: Option<ChildStdin>,
messages: mpsc::Receiver<Result<Value, String>>,
pending: HashMap<String, Value>,
next: u64,
hello: Value,
}
impl Client {
fn new(args: &[&str]) -> Self {
Self::spawn(Path::new(env!("CARGO_BIN_EXE_prometeu-headless")), args, None)
}
fn spawn(binary: &Path, args: &[&str], cwd: Option<&Path>) -> Self {
let mut command = Command::new(binary);
command.args(args).stdin(Stdio::piped()).stdout(Stdio::piped()).stderr(Stdio::inherit());
if let Some(cwd) = cwd {
command.current_dir(cwd);
}
let mut child = command.spawn().unwrap();
let input = child.stdin.take();
let stdout = child.stdout.take().unwrap();
let (sender, messages) = mpsc::channel();
std::thread::spawn(move || {
for line in BufReader::new(stdout).lines() {
let value = line.map_err(|e| e.to_string()).and_then(|line| {
serde_json::from_str(&line)
.map_err(|e| format!("non-protocol stdout: {e}: {line}"))
});
if sender.send(value).is_err() {
break;
}
}
});
let mut client =
Self { child, input, messages, pending: HashMap::new(), next: 0, hello: Value::Null };
client.hello = client.event();
assert_eq!(client.hello["type"], "hello");
client
}
fn event(&self) -> Value {
let message = self
.messages
.recv_timeout(Duration::from_secs(15))
.expect("protocol reply deadline")
.unwrap();
static SCHEMA: std::sync::OnceLock<jsonschema::Validator> = std::sync::OnceLock::new();
let schema = SCHEMA.get_or_init(|| {
let value: Value = serde_json::from_str(include_str!(
"../../../../devtools/headless-protocol/response.schema.json"
))
.unwrap();
jsonschema::validator_for(&value).unwrap()
});
if let Err(error) = schema.validate(&message) {
panic!("server message violates published schema: {error}: {message}");
}
message
}
fn raw(&mut self, bytes: &[u8]) {
self.input.as_mut().unwrap().write_all(bytes).unwrap();
self.input.as_mut().unwrap().flush().unwrap();
}
fn send(&mut self, command: &str, params: Value) -> String {
self.next += 1;
let id = format!("q{}", self.next);
let mut bytes =
serde_json::to_vec(&json!({"requestId":id,"command":command,"params":params})).unwrap();
bytes.push(b'\n');
self.raw(&bytes);
id
}
fn response(&mut self, id: &str) -> Value {
if let Some(value) = self.pending.remove(id) {
return value;
}
loop {
let message = self.event();
if message["type"] == "progress" {
continue;
}
let message_id = message["requestId"].as_str().unwrap().to_owned();
if message_id == id {
return message;
}
self.pending.insert(message_id, message);
}
}
fn call(&mut self, command: &str, params: Value) -> Value {
let id = self.send(command, params);
self.response(&id)
}
fn ok(&mut self, command: &str, params: Value) -> Value {
let response = self.call(command, params);
assert!(response.get("error").is_none(), "{response}");
response["result"].clone()
}
fn initialize(&mut self) {
self.ok("initialize", json!({"protocolVersion":{"major":1,"minor":0},"requiredCapabilities":["advance","capture","cancel"]}));
}
fn wait_exit(&mut self) {
let deadline = Instant::now() + Duration::from_secs(5);
loop {
if let Some(status) = self.child.try_wait().unwrap() {
assert!(status.success(), "{status}");
return;
}
assert!(Instant::now() < deadline, "process did not exit");
std::thread::sleep(Duration::from_millis(5));
}
}
fn close(&mut self) {
self.ok("shutdown", json!({}));
self.input.take();
self.wait_exit();
}
}
impl Drop for Client {
fn drop(&mut self) {
let _ = self.child.kill();
let _ = self.child.wait();
}
}
fn cartridge(code: &str, gfx: bool) -> TempDir {
cartridge_bytes(assemble(code).unwrap(), gfx)
}
fn cartridge_bytes(code: Vec<u8>, gfx: bool) -> TempDir {
let dir = TempDir::new();
let module = BytecodeModule {
version: 0,
const_pool: vec![],
functions: vec![FunctionMeta {
code_offset: 0,
code_len: code.len() as u32,
param_slots: 0,
local_slots: 0,
return_slots: 0,
max_stack_slots: 8,
}],
code,
debug_info: Some(DebugInfo {
pc_to_span: vec![(0, SourceSpan { file_id: 7, start: 11, end: 15 })],
function_names: vec![(0, "main".into())],
}),
exports: vec![Export { symbol: "main".into(), func_idx: 0 }],
syscalls: if gfx {
vec![SyscallDecl {
module: "gfx2d".into(),
name: "clear".into(),
version: 1,
arg_slots: 1,
ret_slots: 0,
}]
} else {
vec![]
},
};
fs::write(dir.0.join("program.pbx"), module.serialize()).unwrap();
fs::write(
dir.0.join("manifest.json"),
serde_json::to_vec(&json!({"magic":"PMTU","cartridge_version":1,"app_id":41,
"title":"Protocol test","app_version":"0.1.0","app_mode":"Game","capabilities":["gfx2d"]}))
.unwrap(),
)
.unwrap();
dir
}
fn colored_cart() -> TempDir {
cartridge("PUSH_I64 4278190335\nHOSTCALL 0\nFRAME_SYNC\nRET\n", true)
}
fn boot(client: &mut Client, dir: &TempDir) {
client.ok("boot", json!({"path":dir.0}));
}
fn png_bytes(capture: &Value) -> Vec<u8> {
let bytes = STANDARD.decode(capture["data"].as_str().unwrap()).unwrap();
let decoder = png::Decoder::new(std::io::Cursor::new(bytes));
let mut reader = decoder.read_info().unwrap();
let mut output = vec![0; reader.output_buffer_size()];
let info = reader.next_frame(&mut output).unwrap();
assert_eq!(info.color_type, png::ColorType::Rgba);
assert_eq!(info.width as u64, capture["width"].as_u64().unwrap());
assert_eq!(info.height as u64, capture["height"].as_u64().unwrap());
output.truncate(info.buffer_size());
output
}
#[test]
fn handshake_versions_capabilities_and_limits_are_explicit() {
let mut c = Client::new(&["--stdio"]);
assert_eq!(c.hello["runtimeVersion"], env!("CARGO_PKG_VERSION"));
assert_eq!(c.hello["protocolVersion"], json!({"major":1,"minor":0}));
assert_eq!(
c.hello["limits"],
json!({"maxFrames":600,"maxCommandBytes":65536,"maxResponseBytes":33554432,
"handshakeTimeoutMs":5000,"callTimeoutMs":60000,"shutdownTimeoutMs":5000})
);
assert_eq!(c.call("get_state", json!({}))["error"]["code"], "not_initialized");
assert_eq!(
c.call(
"initialize",
json!({"protocolVersion":{"major":2,"minor":0},"requiredCapabilities":[]})
)["error"]["code"],
"incompatible_version"
);
assert_eq!(
c.call(
"initialize",
json!({"protocolVersion":{"major":1,"minor":0},"requiredCapabilities":["telepathy"]})
)["error"]["code"],
"unsupported_capability"
);
assert_eq!(
c.ok(
"initialize",
json!({"protocolVersion":{"major":1,"minor":42},"requiredCapabilities":[]})
)["protocolVersion"]["minor"],
0
);
assert_eq!(
c.call(
"initialize",
json!({"protocolVersion":{"major":1,"minor":0},"requiredCapabilities":[]})
)["error"]["code"],
"already_initialized"
);
c.close();
}
#[test]
fn malformed_fragmented_and_oversized_commands_do_not_desynchronize() {
let mut c = Client::new(&["--stdio", "--max-command-bytes", "4096"]);
c.initialize();
c.raw(b"not json\n");
assert_eq!(c.event()["error"]["code"], "invalid_request");
c.raw(&[0xff, b'\n']);
assert_eq!(c.event()["error"]["code"], "invalid_request");
let mut huge = vec![b' '; 5000];
huge.push(b'\n');
c.raw(&huge);
assert_eq!(c.event()["error"]["code"], "request_too_large");
c.raw(b"{\"requestId\":\"fragment\",\"command\":\"get_");
assert!(c.messages.try_recv().is_err());
c.raw(b"state\",\"params\":{}}\r\n");
assert_eq!(c.response("fragment")["result"]["status"], "terminated");
assert_eq!(c.call("get_state", json!({"typo":1}))["error"]["code"], "invalid_params");
assert_eq!(c.call("advance", json!({"frames":-1}))["error"]["code"], "invalid_params");
assert_eq!(c.call("advance", json!({"frames":601}))["error"]["code"], "limit_exceeded");
assert_eq!(c.call("missing", json!({}))["error"]["code"], "unknown_command");
c.close();
}
#[test]
fn lifecycle_and_capture_match_the_in_process_canonical_oracle() {
let dir = colored_cart();
let mut c = Client::new(&["--stdio"]);
c.initialize();
assert_eq!(c.call("capture", json!({}))["error"]["code"], "no_frame_available");
boot(&mut c, &dir);
assert_eq!(c.call("boot", json!({"path":dir.0}))["error"]["code"], "already_booted");
let initial = c.ok("get_state", json!({}));
assert_eq!(initial, c.ok("get_state", json!({})), "no background ticks");
assert_eq!(
c.ok("advance", json!({"frames":0})),
json!({"requested":0,"completed":0,"stop":"completed"})
);
c.ok("set_input", json!({"right":true,"touch":true,"touchX":123,"touchY":45}));
c.ok("clear_input", json!({}));
let outcome = c.ok("advance", json!({"frames":3}));
assert_eq!(outcome["completed"], 3);
let capture = c.ok("capture", json!({}));
let mut host = HeadlessHost::new();
host.boot(dir.0.to_string_lossy()).unwrap();
assert_eq!(host.advance_frames(3).unwrap().stop, AdvanceFramesStop::Completed);
let expected = host.capture_frame().unwrap();
let pixels: Vec<u8> = expected.frame.pixels.iter().flat_map(|v| v.to_be_bytes()).collect();
assert_eq!(png_bytes(&capture), pixels);
assert_eq!(capture["logicalFrameIndex"], expected.logical_frame_index);
assert_eq!(capture["frameId"], expected.frame.frame_id.get());
assert_eq!(capture["stridePixels"], expected.frame.stride_pixels);
assert_eq!(c.ok("get_fault", json!({})), Value::Null);
c.ok("reset", json!({}));
assert_eq!(c.call("capture", json!({}))["error"]["code"], "no_frame_available");
assert_eq!(c.ok("advance", json!({"frames":1}))["stop"], "terminated");
boot(&mut c, &dir);
c.ok("advance", json!({"frames":3}));
assert_eq!(c.ok("capture", json!({})), capture);
c.close();
}
#[test]
fn independent_processes_match_pixels_ids_state_and_fault() {
// Color is selected by the real normalized RIGHT-down intrinsic.
let mut code = assemble("INTRINSIC 0x2000\nINTRINSIC 0x2013\nINTRINSIC 0x2032\n").unwrap();
let jump = code.len() + 2;
code.extend(
assemble("JMP_IF_FALSE 0\nPUSH_I64 4278190335\nHOSTCALL 0\nFRAME_SYNC\nRET\n").unwrap(),
);
let blue = code.len() as u32;
code[jump..jump + 4].copy_from_slice(&blue.to_le_bytes());
code.extend(assemble("PUSH_I64 65535\nHOSTCALL 0\nFRAME_SYNC\nRET\n").unwrap());
let dir = cartridge_bytes(code, true);
let run = |c: &mut Client| {
boot(c, &dir);
c.ok("set_input", json!({"right":true}));
c.ok("advance", json!({"frames":12}));
let held = c.ok("capture", json!({}));
assert!(png_bytes(&held).as_chunks::<4>().0.iter().all(|p| *p == [255, 0, 0, 255]));
c.ok("clear_input", json!({}));
c.ok("advance", json!({"frames":1}));
let released = c.ok("capture", json!({}));
assert!(png_bytes(&released).as_chunks::<4>().0.iter().all(|p| *p == [0, 0, 255, 255]));
(held, released, c.ok("get_state", json!({})), c.ok("get_fault", json!({})))
};
let mut first = Client::new(&["--stdio"]);
first.initialize();
let expected = run(&mut first);
first.ok("reset", json!({}));
assert_eq!(run(&mut first), expected);
first.close();
let mut second = Client::new(&["--stdio"]);
second.initialize();
assert_eq!(run(&mut second), expected);
second.close();
}
#[test]
fn partial_guest_fault_and_host_watchdog_are_distinct_outcomes() {
let mut code =
assemble("GET_GLOBAL 0\nPUSH_I32 1\nADD\nSET_GLOBAL 0\nGET_GLOBAL 0\nPUSH_I32 3\nEQ\n")
.unwrap();
let jump = code.len() + 2;
code.extend(assemble("JMP_IF_FALSE 0\nTRAP\n").unwrap());
let next = code.len() as u32;
code[jump..jump + 4].copy_from_slice(&next.to_le_bytes());
code.extend(assemble("PUSH_I64 255\nHOSTCALL 0\nFRAME_SYNC\nRET\n").unwrap());
let dir = cartridge_bytes(code, true);
let mut c = Client::new(&["--stdio"]);
c.initialize();
boot(&mut c, &dir);
let outcome = c.ok("advance", json!({"frames":5}));
assert_eq!(outcome["completed"], 2);
assert_eq!(outcome["stop"], "faulted");
assert_eq!(outcome["fault"], c.ok("get_fault", json!({})));
c.ok("reset", json!({}));
let infinite = cartridge("JMP 0\n", false);
boot(&mut c, &infinite);
let outcome = c.ok("advance", json!({"frames":5}));
assert_eq!(outcome["completed"], 0);
assert_eq!(outcome["stop"], "host_error");
assert_eq!(outcome["error"]["code"], "watchdog_expired");
assert_eq!(c.ok("get_fault", json!({})), Value::Null);
assert_eq!(c.ok("get_state", json!({}))["status"], "paused");
c.close();
}
#[test]
fn faults_and_boot_failures_are_structured_not_log_parsing() {
let dir = cartridge("TRAP\nFRAME_SYNC\nRET\n", false);
let mut c = Client::new(&["--stdio"]);
c.initialize();
boot(&mut c, &dir);
let result = c.ok("advance", json!({"frames":5}));
assert_eq!(result["completed"], 0);
assert_eq!(result["stop"], "faulted");
assert_eq!(result["fault"]["kind"], "vm_trap");
assert!(result["fault"]["trap"]["code"].is_number());
assert_eq!(c.ok("get_fault", json!({})), result["fault"]);
assert_eq!(c.ok("get_state", json!({}))["status"], "faulted");
c.ok("reset", json!({}));
fs::write(dir.0.join("program.pbx"), b"not PBX").unwrap();
let response = c.call("boot", json!({"path":dir.0}));
assert_eq!(response["error"]["code"], "boot_failed");
assert_eq!(response["error"]["details"]["fault"]["kind"], "vm_init");
assert!(response["error"]["details"]["fault"]["initError"]["code"].is_string());
c.close();
}
#[test]
fn conflicting_work_is_rejected_and_cancellation_reports_partial_progress() {
let dir = colored_cart();
let mut c = Client::new(&["--stdio", "--max-frames", "100000"]);
c.initialize();
boot(&mut c, &dir);
let advance = c.send("advance", json!({"frames":100000}));
assert_eq!(c.event()["type"], "progress");
assert_eq!(c.call("reset", json!({}))["error"]["code"], "busy");
c.ok("cancel", json!({"targetRequestId":advance}));
let response = c.response(&advance);
let result = &response["result"];
assert_eq!(result["stop"], "canceled");
assert!(
result["completed"].as_u64().unwrap() >= 1
&& result["completed"].as_u64().unwrap() < 100000
);
assert_eq!(c.ok("get_state", json!({}))["logicalFrameIndex"], result["completed"]);
assert_eq!(
c.call("cancel", json!({"targetRequestId":advance}))["error"]["code"],
"not_cancelable"
);
c.close();
}
#[test]
fn shutdown_and_eof_interrupt_active_work_without_resuming_it() {
let dir = colored_cart();
for explicit in [true, false] {
let mut c = Client::new(&["--stdio", "--max-frames", "100000"]);
c.initialize();
boot(&mut c, &dir);
let advance = c.send("advance", json!({"frames":100000}));
assert_eq!(c.event()["type"], "progress");
if explicit {
let shutdown = c.send("shutdown", json!({}));
assert_eq!(c.response(&advance)["result"]["stop"], "canceled");
assert_eq!(c.response(&shutdown)["result"]["closed"], true);
} else {
c.input.take();
assert_eq!(c.response(&advance)["result"]["stop"], "canceled");
}
c.wait_exit();
}
}
#[test]
fn idle_eof_and_truncated_eof_close_the_process() {
for suffix in [b"".as_slice(), b"{\"requestId\":\"partial\"".as_slice()] {
let mut c = Client::new(&["--stdio"]);
c.raw(suffix);
c.input.take();
if !suffix.is_empty() {
assert_eq!(c.event()["error"]["code"], "invalid_request");
}
c.wait_exit();
}
}
#[test]
fn dispatcher_works_from_a_relocated_installation_and_other_cwd() {
let installation = TempDir::new();
let cwd = TempDir::new();
let dispatcher = installation.0.join(if cfg!(windows) { "prometeu.exe" } else { "prometeu" });
let headless = installation.0.join(if cfg!(windows) {
"prometeu-headless.exe"
} else {
"prometeu-headless"
});
fs::copy(env!("CARGO_BIN_EXE_prometeu"), &dispatcher).unwrap();
fs::copy(env!("CARGO_BIN_EXE_prometeu-headless"), &headless).unwrap();
let mut c = Client::spawn(
&dispatcher,
&[
"headless",
"--stdio",
"--max-frames",
"17",
"--max-command-bytes",
"8192",
"--max-response-bytes",
"16384",
"--handshake-timeout-ms",
"1234",
"--call-timeout-ms",
"2345",
"--shutdown-timeout-ms",
"3456",
],
Some(&cwd.0),
);
assert_eq!(
c.hello["limits"],
json!({"maxFrames":17,"maxCommandBytes":8192,"maxResponseBytes":16384,
"handshakeTimeoutMs":1234,"callTimeoutMs":2345,"shutdownTimeoutMs":3456})
);
c.initialize();
c.close();
let help = Command::new(&dispatcher).arg("--help").output().unwrap();
let help = String::from_utf8(help.stdout).unwrap();
for name in ["run", "debug", "headless"] {
assert!(help.contains(name));
}
}
#[test]
fn missing_binary_and_invalid_cli_limits_fail_explicitly() {
let installation = TempDir::new();
let dispatcher = installation.0.join(if cfg!(windows) { "prometeu.exe" } else { "prometeu" });
fs::copy(env!("CARGO_BIN_EXE_prometeu"), &dispatcher).unwrap();
let result = Command::new(&dispatcher).args(["headless", "--stdio"]).output().unwrap();
assert!(!result.status.success());
assert!(String::from_utf8_lossy(&result.stderr).contains("headless"));
for args in
[vec!["--stdio", "--max-frames", "0"], vec!["--stdio", "--max-response-bytes", "1"], vec![]]
{
let result =
Command::new(env!("CARGO_BIN_EXE_prometeu-headless")).args(args).output().unwrap();
assert!(!result.status.success());
assert!(result.stdout.is_empty());
}
}
#[test]
fn schemas_and_distributed_request_fixtures_are_consistent() {
let request: Value = serde_json::from_str(include_str!(
"../../../../devtools/headless-protocol/request.schema.json"
))
.unwrap();
let response: Value = serde_json::from_str(include_str!(
"../../../../devtools/headless-protocol/response.schema.json"
))
.unwrap();
jsonschema::meta::validate(&request).unwrap();
jsonschema::meta::validate(&response).unwrap();
let validator = jsonschema::validator_for(&request).unwrap();
let valid: Vec<Value> =
serde_json::from_str(include_str!("../../../../devtools/headless-protocol/requests.json"))
.unwrap();
for request in valid {
validator.validate(&request).unwrap();
}
let invalid: Vec<Value> = serde_json::from_str(include_str!(
"../../../../devtools/headless-protocol/invalid-requests.json"
))
.unwrap();
let mut c = Client::new(&["--stdio"]);
c.initialize();
for request in invalid {
assert!(!validator.is_valid(&request), "{request}");
let mut bytes = serde_json::to_vec(&request).unwrap();
bytes.push(b'\n');
c.raw(&bytes);
assert!(c.event().get("error").is_some(), "{request}");
}
c.close();
}
#[test]
#[ignore = "requires PROMETEU_PROTOCOL_TEST_INSTALL pointing to an extracted dist archive"]
fn packaged_installation_smoke() {
let installation = PathBuf::from(
std::env::var_os("PROMETEU_PROTOCOL_TEST_INSTALL")
.expect("set extracted distribution path"),
);
for file in [
"prometeu",
"prometeu-runtime",
"prometeu-headless",
"headless-protocol/request.schema.json",
"headless-protocol/response.schema.json",
"11a-headless-automation-protocol.md",
] {
assert!(installation.join(file).is_file(), "missing packaged {file}");
}
let cwd = TempDir::new();
let dir = colored_cart();
let mut c =
Client::spawn(&installation.join("prometeu"), &["headless", "--stdio"], Some(&cwd.0));
assert_eq!(c.hello["runtimeVersion"], env!("CARGO_PKG_VERSION"));
c.initialize();
boot(&mut c, &dir);
c.ok("advance", json!({"frames":3}));
let capture = c.ok("capture", json!({}));
assert!(png_bytes(&capture).as_chunks::<4>().0.iter().all(|p| *p == [255, 0, 0, 255]));
c.input.take();
c.wait_exit();
}
@@ -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
}
}
}
+1 -1
View File
@@ -15,4 +15,4 @@ targets = ["aarch64-apple-darwin", "x86_64-apple-darwin"]
unix-archive = ".zip"
macos-universal-binaries = true
[dist.hooks]
pre-build = ["./scripts/pre-dist.sh"]
pre-build = ["./scripts/gen-version.sh"]
@@ -98,7 +98,9 @@ meanings even though their transports and pacing differ:
| Reset the machine execution | not defined by the debugger protocol | `reset()` |
| Capture the canonical published frame | not defined by the debugger protocol | `capture_frame()` |
The headless API does not define or extend an external automation protocol.
The in-process headless API does not itself define or extend a wire protocol.
The separate [headless automation protocol](11a-headless-automation-protocol.md)
exposes that API over versioned JSONL/stdio without extending human DevTools.
## 4 State Inspection Boundary
@@ -219,6 +219,10 @@ PROMETEU promises:
## 13 Deterministic Headless Control
The external tooling boundary is specified separately in
[Headless Automation Protocol v1](11a-headless-automation-protocol.md). It preserves
the in-process semantics in this section and does not extend the guest ABI.
The headless host is a separate, generic Prometeu host for in-process
automation. It runs the same directory cartridge, firmware, active VM session,
capability checks, normalized input, render submissions, and fault model as an
@@ -0,0 +1,161 @@
# Headless Automation Protocol v1
**Domain:** runtime host tooling. **Function:** normative.
This chapter implements Studio DSC-0068 / DEC-0060 baseline v1, runtime phase
of PLN-0139. The host owns this wire contract. It does not change guest ABI,
firmware, VM, frame/input semantics or the desktop DevTools protocol.
## Process and transport
`prometeu headless --stdio` starts the distributed `prometeu-headless` tool from
the same installation. One process owns one HeadlessHost. No display, native
audio, network service or realtime pacing is required. A client must use its
configured installation; missing binaries/capabilities are explicit failures.
Transport is UTF-8 JSON objects separated by LF (CRLF is accepted). stdout is
protocol-only; diagnostics go to stderr. Fragmented reads must be accumulated;
allocation is bounded by the command limit. An oversized line is rejected and
drained through LF before reading the next request. EOF with an incomplete line
reports `invalid_request`, then closes the session. EOF always requests shutdown.
All sizes exclude the LF delimiter and include the complete JSON envelope and
base64 payload. Responses exceeding their bound become `response_too_large`,
never truncated data. Clients must continuously consume stdout, including events.
Backpressure may block output; the supervising client owns wall-clock deadlines
and may terminate the process tree. There is no transport replay or durable queue.
## Handshake and compatibility
The server first emits a `hello` object with `sessionId`, `protocolVersion`
(`major: 1, minor: 0`), real `runtimeVersion`, `capabilities` and `limits`.
Session identity is opaque and process-local, excluded from deterministic oracles.
Before work, the client sends `initialize` with `protocolVersion` and an array
`requiredCapabilities`. An incompatible major returns `incompatible_version`;
missing capabilities return `unsupported_capability`. The session remains
uninitialized and cannot execute work. Compatible minor additions are permitted;
the initialize result returns the lesser supported minor. Initialize is accepted
once; repeated initialization returns `already_initialized`. Shutdown is permitted
even before initialization. All other work requires successful initialization.
## Envelopes
```json
{"requestId":"a1","command":"advance","params":{"frames":60}}
```
`requestId` is a nonempty string of at most 128 UTF-8 bytes, selected by the
client; concurrent requests must have distinct identities. `command` and `params`
are required. Unknown fields and invalid parameter types are rejected. The
request schema is distributed in `devtools/headless-protocol/request.schema.json`;
`response.schema.json` defines hello, progress and every response/result shape.
Valid and invalid request fixtures are shipped beside the schemas. Process tests
validate actual server output against the response schema (including image results).
```json
{"type":"response","sessionId":"opaque","requestId":"a1","result":{"requested":60,"completed":60,"stop":"completed"}}
{"type":"response","sessionId":"opaque","requestId":"a1","error":{"code":"busy","message":"...","details":{}}}
```
A response contains exactly one of result/error. Errors have stable `code`,
human-readable `message` and structured `details`. Unparseable/unusable request
identity is represented by null; valid identity is preserved on parameter errors.
Malformed JSON, invalid schema and unknown commands must never disappear silently.
Wire requestId is correlation, not deduplication: the client must not retry an
advance blindly after a lost response. Studio task-level clientRequestId and
operationId are a separate boundary, not part of this wire protocol.
## Commands
| Command | Parameters | Result/meaning |
| --- | --- | --- |
| initialize | protocolVersion, requiredCapabilities | negotiated version and capabilities |
| boot | path (nonempty directory-cartridge path) | current state; existing boot preconditions apply |
| reset | empty object | reset state, clears input/fault/frame correlation |
| set_input | complete snapshot fields listed below; omitted fields reset to defaults | input replaced, not patched |
| clear_input | empty object | input restored to defaults |
| advance | frames: unsigned integer, including zero | requested, completed, stop, optional fault/error details |
| capture | empty object | PNG/base64 plus canonical frame metadata |
| get_state | empty object | pc, stackTop, logicalFrameIndex, tickIndex, appId, status |
| get_fault | empty object | fault object or null |
| cancel | targetRequestId | acknowledgement that cancellation was requested for that active advance |
| shutdown | empty object | acknowledgement after the active operation stops and host is dropped |
Input snapshot fields are `up`, `down`, `left`, `right`, `a`, `b`, `x`, `y`, `l`,
`r`, `start`, `select`, `touch` (booleans), and `touchX`, `touchY` (signed i32).
Omitted booleans are false and omitted coordinates are zero. The ordinary runtime
begin-frame sampling derives press/release/hold edges. No new input semantics exist.
State statuses are `running`, `paused`, `terminated`, `faulted`; `running` does
not mean background execution. Stack values preserve their type through tagged
`kind`/`value` objects; i64 values are decimal strings and float values carry an
exact round-trippable string (including non-finite values). Faults expose kind,
pc, summary and structural trap code/opcode/message/source span or init-error code.
No client must parse a summary to distinguish trap, panic or initialization failure.
## Ordering, cancellation and lifecycle
Only one host operation is admitted at a time. Conflicting work, including state
inspection while the host is executing, returns `busy`; it is not implicitly
queued. The command reader remains available for cancel/shutdown while an advance
executes. Cancellation targets an active advance's requestId; no active matching
advance returns `not_cancelable`. An acknowledgement is not a completed cancellation.
Advancement is repeated `advance_frame()`, checking cancellation between frames.
The current frame keeps the existing deterministic host-tick watchdog. Zero frames
is a no-op. Results preserve requested/completed counts and `stop` values:
`completed`, `faulted`, `terminated`, `canceled`, `host_error`.
Guest faults are outcomes, not malformed-request errors. Host errors include a
stable code and known completed progress; they do not manufacture guest faults.
Each completed frame emits `type: progress`, requestId, sessionId, requested and
completed counts before the terminal response. A client can retain known progress
if the process dies. The final response is authoritative when delivered.
Shutdown/EOF requests cancellation, waits for the active work to reach its boundary,
drops the host and exits; explicit shutdown receives its response after cleanup.
Disconnect never starts/resumes execution. A failed process requires a new explicit
session, not replay. Host session loss does not implicitly release Studio authority.
## Capture
Capture returns `mimeType: image/png`, `encoding: base64`, `data`, `width`, `height`,
`stridePixels`, `pixelFormat: RGBA8888`, `logicalFrameIndex` and `frameId`.
The envelope carries sessionId; the Studio consumer adds build correlation.
Frame identities/counters on this wire are unsigned JSON integers and must be
decoded losslessly. logicalFrameIndex and frameId have no numeric equality rule.
PNG stores visible RGBA channels in row order, losslessly, without stride padding.
stridePixels describes the original canonical buffer. Before a completed frame,
including after reset, capture returns `no_frame_available`; it cannot reuse an
old run. No desktop screenshot, hash-only substitute, temporary-image-file transport
or continuous video is permitted.
## Configurable limits and supervision
| CLI option / handshake field | Default |
| --- | --- |
| --max-frames / maxFrames | 600 |
| --max-command-bytes / maxCommandBytes | 65536 |
| --max-response-bytes / maxResponseBytes | 33554432 |
| --handshake-timeout-ms / handshakeTimeoutMs | 5000 |
| --call-timeout-ms / callTimeoutMs | 60000 |
| --shutdown-timeout-ms / shutdownTimeoutMs | 5000 |
Limits must be positive; message bounds must be at least 4096 bytes to admit the
handshake and bounded errors. Limits apply to serialized bytes, not characters.
Clients must enforce the advertised handshake/call deadlines and 5-second default
cancel/shutdown grace, then terminate only the process tree they own. Deadlines are
host supervision, not simulated guest time. Runtime enforces frame/message bounds
without clamping. Requests over limits fail explicitly. Clients configure startup
timeouts before seeing the handshake, then verify the announced values.
## Conformance
The runtime gate includes fragmented/invalid/oversized lines, negotiation failures,
all commands, busy/cancel/shutdown races, EOF, real CLI distribution invocation,
PNG pixel equality, independent logical/render identity, repeat/reset determinism,
structured faults, progress on partial failure and retained desktop run/debug.
Neither Studio UI nor an AI model is required. See `tests/automation_process.rs`
in prometeu-cli and the in-process deterministic-control tests in the headless crate.
+1
View File
@@ -90,6 +90,7 @@ In the current state, no chapter under the active `docs/runtime/specs/` root is
| [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) | VM coroutine model | normative |
| [`10-debug-inspection-and-profiling.md`](10-debug-inspection-and-profiling.md) | machine diagnostics | normative |
| [`11-portability-and-cross-platform-execution.md`](11-portability-and-cross-platform-execution.md) | portability contract | normative |
| [`11a-headless-automation-protocol.md`](11a-headless-automation-protocol.md) | external headless host automation | normative |
| [`12-firmware-pos-and-prometeuhub.md`](12-firmware-pos-and-prometeuhub.md) | firmware and system orchestration | normative |
| [`13-cartridge.md`](13-cartridge.md) | cartridge package | normative |
| [`14-boot-profiles.md`](14-boot-profiles.md) | firmware boot flow | normative |
+13 -8
View File
@@ -1,30 +1,35 @@
#!/bin/bash
set -e
set -euo pipefail
# Resolve inputs from this checkout, independently of the caller's cwd.
cd "$(dirname "$0")/.."
# Generate version
./scripts/gen-version.sh
# Prepare staging for SDK extra files
echo "Preparing dist-staging..."
rm -rf dist-staging/devtools/debugger-protocol
mkdir -p dist-staging/devtools/debugger-protocol
mkdir -p dist-staging/devtools/headless-protocol dist-staging/docs/runtime
cp devtools/debugger-protocol/protocol.json dist-staging/devtools/debugger-protocol/
cp VERSION.txt dist-staging/devtools/debugger-protocol/VERSION.txt
cp devtools/headless-protocol/*.json dist-staging/devtools/headless-protocol/
cp VERSION.txt dist-staging/devtools/headless-protocol/VERSION.txt
cp docs/specs/runtime/11a-headless-automation-protocol.md dist-staging/docs/runtime/
# Clean and prepare the version-specific directory
echo "Cleaning dist-staging/stable..."
echo "Preparing dist-staging/stable (existing archives are retained)..."
mkdir -p "dist-staging/stable"
rm -rf "dist-staging/stable/*"
# Build stable using cargo build
dist build
dist build "$@"
echo "Copying target/distrib content to dist-staging/stable..."
if [ -d "target/distrib" ] && [ "$(ls -A target/distrib)" ]; then
cp -r target/distrib/* "dist-staging/stable/"
else
echo "Warning: target/dist directory not found or empty."
fi
echo "Error: target/distrib directory not found or empty." >&2
exit 1
fi