From 4f10f6e584dba031d4d15f80d392312f867c888f Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Mon, 28 Sep 2026 15:36:22 +0100 Subject: [PATCH] feat: add headless automation protocol and CLI --- Cargo.lock | 598 +++++++++++++++- crates/host/prometeu-host-headless/Cargo.toml | 6 + .../src/automation/mod.rs | 406 +++++++++++ .../src/automation/wire.rs | 330 +++++++++ crates/host/prometeu-host-headless/src/lib.rs | 1 + crates/tools/prometeu-cli/Cargo.toml | 15 + .../prometeu-cli/src/bin/prometeu-headless.rs | 17 + crates/tools/prometeu-cli/src/lib.rs | 62 ++ crates/tools/prometeu-cli/src/main.rs | 8 + .../prometeu-cli/tests/automation_process.rs | 615 ++++++++++++++++ .../headless-protocol/invalid-requests.json | 49 ++ .../headless-protocol/request.schema.json | 284 ++++++++ devtools/headless-protocol/requests.json | 78 ++ .../headless-protocol/response.schema.json | 666 ++++++++++++++++++ dist-workspace.toml | 2 +- .../10-debug-inspection-and-profiling.md | 4 +- ...ortability-and-cross-platform-execution.md | 4 + .../11a-headless-automation-protocol.md | 161 +++++ docs/specs/runtime/README.md | 1 + scripts/local-dist.sh | 21 +- 20 files changed, 3310 insertions(+), 18 deletions(-) create mode 100644 crates/host/prometeu-host-headless/src/automation/mod.rs create mode 100644 crates/host/prometeu-host-headless/src/automation/wire.rs create mode 100644 crates/tools/prometeu-cli/src/bin/prometeu-headless.rs create mode 100644 crates/tools/prometeu-cli/src/lib.rs create mode 100644 crates/tools/prometeu-cli/tests/automation_process.rs create mode 100644 devtools/headless-protocol/invalid-requests.json create mode 100644 devtools/headless-protocol/request.schema.json create mode 100644 devtools/headless-protocol/requests.json create mode 100644 devtools/headless-protocol/response.schema.json create mode 100644 docs/specs/runtime/11a-headless-automation-protocol.md diff --git a/Cargo.lock b/Cargo.lock index 49c5aaa..0bdf664 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -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" diff --git a/crates/host/prometeu-host-headless/Cargo.toml b/crates/host/prometeu-host-headless/Cargo.toml index 405c8ed..5b92882 100644 --- a/crates/host/prometeu-host-headless/Cargo.toml +++ b/crates/host/prometeu-host-headless/Cargo.toml @@ -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" diff --git a/crates/host/prometeu-host-headless/src/automation/mod.rs b/crates/host/prometeu-host-headless/src/automation/mod.rs new file mode 100644 index 0000000..b6e234e --- /dev/null +++ b/crates/host/prometeu-host-headless/src/automation/mod.rs @@ -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, + advancing: bool, + canceled: bool, +} + +enum Job { + Work(String, Command), + Stop(Option), + ReadError(io::Error), +} + +struct Output { + writer: Mutex, + session: String, + limit: usize, +} + +impl Output { + 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) -> 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), + 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 { + 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( + mut input: R, + output: &Output, + control: &Mutex, + sender: &mpsc::Sender, + 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::(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(¶ms.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( + host: &mut HeadlessHost, + command: Command, + id: &str, + output: &Output, + control: &Mutex, +) -> io::Result> { + 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( + 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::(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 = 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]); + } +} diff --git a/crates/host/prometeu-host-headless/src/automation/wire.rs b/crates/host/prometeu-host-headless/src/automation/wire.rs new file mode 100644 index 0000000..c67e74a --- /dev/null +++ b/crates/host/prometeu-host-headless/src/automation/wire.rs @@ -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, +} + +#[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 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(value: Value) -> Result { + 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) -> 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::>(), + "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 { + 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()})) +} diff --git a/crates/host/prometeu-host-headless/src/lib.rs b/crates/host/prometeu-host-headless/src/lib.rs index 785e8f0..48e7fdb 100644 --- a/crates/host/prometeu-host-headless/src/lib.rs +++ b/crates/host/prometeu-host-headless/src/lib.rs @@ -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::{ diff --git a/crates/tools/prometeu-cli/Cargo.toml b/crates/tools/prometeu-cli/Cargo.toml index cd07bdf..f9d439b 100644 --- a/crates/tools/prometeu-cli/Cargo.toml +++ b/crates/tools/prometeu-cli/Cargo.toml @@ -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" diff --git a/crates/tools/prometeu-cli/src/bin/prometeu-headless.rs b/crates/tools/prometeu-cli/src/bin/prometeu-headless.rs new file mode 100644 index 0000000..1a1b0bb --- /dev/null +++ b/crates/tools/prometeu-cli/src/bin/prometeu-headless.rs @@ -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) +} diff --git a/crates/tools/prometeu-cli/src/lib.rs b/crates/tools/prometeu-cli/src/lib.rs new file mode 100644 index 0000000..12df0bd --- /dev/null +++ b/crates/tools/prometeu-cli/src/lib.rs @@ -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 { + 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"), + ) +} diff --git a/crates/tools/prometeu-cli/src/main.rs b/crates/tools/prometeu-cli/src/main.rs index 8cbf6ca..cf4a633 100644 --- a/crates/tools/prometeu-cli/src/main.rs +++ b/crates/tools/prometeu-cli/src/main.rs @@ -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, diff --git a/crates/tools/prometeu-cli/tests/automation_process.rs b/crates/tools/prometeu-cli/tests/automation_process.rs new file mode 100644 index 0000000..1bdcd37 --- /dev/null +++ b/crates/tools/prometeu-cli/tests/automation_process.rs @@ -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, + messages: mpsc::Receiver>, + pending: HashMap, + 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 = 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, 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 { + 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 = 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 = + serde_json::from_str(include_str!("../../../../devtools/headless-protocol/requests.json")) + .unwrap(); + for request in valid { + validator.validate(&request).unwrap(); + } + let invalid: Vec = 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(); +} diff --git a/devtools/headless-protocol/invalid-requests.json b/devtools/headless-protocol/invalid-requests.json new file mode 100644 index 0000000..d1de3ca --- /dev/null +++ b/devtools/headless-protocol/invalid-requests.json @@ -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 + } +] diff --git a/devtools/headless-protocol/request.schema.json b/devtools/headless-protocol/request.schema.json new file mode 100644 index 0000000..1ab40ce --- /dev/null +++ b/devtools/headless-protocol/request.schema.json @@ -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 + } + } + } + } +} diff --git a/devtools/headless-protocol/requests.json b/devtools/headless-protocol/requests.json new file mode 100644 index 0000000..5ab3213 --- /dev/null +++ b/devtools/headless-protocol/requests.json @@ -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" + } + } +] diff --git a/devtools/headless-protocol/response.schema.json b/devtools/headless-protocol/response.schema.json new file mode 100644 index 0000000..b0187dc --- /dev/null +++ b/devtools/headless-protocol/response.schema.json @@ -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 + } + } +} diff --git a/dist-workspace.toml b/dist-workspace.toml index 2ee777f..a38529f 100644 --- a/dist-workspace.toml +++ b/dist-workspace.toml @@ -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"] diff --git a/docs/specs/runtime/10-debug-inspection-and-profiling.md b/docs/specs/runtime/10-debug-inspection-and-profiling.md index e7bd2bc..3bf6d29 100644 --- a/docs/specs/runtime/10-debug-inspection-and-profiling.md +++ b/docs/specs/runtime/10-debug-inspection-and-profiling.md @@ -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 diff --git a/docs/specs/runtime/11-portability-and-cross-platform-execution.md b/docs/specs/runtime/11-portability-and-cross-platform-execution.md index 22a04a8..8736e6e 100644 --- a/docs/specs/runtime/11-portability-and-cross-platform-execution.md +++ b/docs/specs/runtime/11-portability-and-cross-platform-execution.md @@ -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 diff --git a/docs/specs/runtime/11a-headless-automation-protocol.md b/docs/specs/runtime/11a-headless-automation-protocol.md new file mode 100644 index 0000000..ef2725f --- /dev/null +++ b/docs/specs/runtime/11a-headless-automation-protocol.md @@ -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. diff --git a/docs/specs/runtime/README.md b/docs/specs/runtime/README.md index f8ee55e..3952c80 100644 --- a/docs/specs/runtime/README.md +++ b/docs/specs/runtime/README.md @@ -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 | diff --git a/scripts/local-dist.sh b/scripts/local-dist.sh index c2b4b59..25b684b 100755 --- a/scripts/local-dist.sh +++ b/scripts/local-dist.sh @@ -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 \ No newline at end of file + echo "Error: target/distrib directory not found or empty." >&2 + exit 1 +fi -- 2.54.0