feat(challenge-sdk-wasm): add terminal host function bindings and types (#26)

Extend the guest-side WASM SDK to support terminal challenge evaluation
scenarios requiring process execution, filesystem access, timing, and
deterministic random seeds.

Terminal types (new term_types.rs module): CommandRequest/CommandResult
for process execution with args, env vars, working dir, and timeout;
FileReadRequest/FileWriteRequest/FileListRequest with corresponding
response types; TaskDefinition for task generation with scoring params
and environment config; TermEvaluationMetrics for detailed scoring
(execution time, correctness, partial credit, cost); TermEvaluationInput
and TermEvaluationOutput wrappers. All types are no_std-compatible using
alloc:: only and derive Serialize/Deserialize.

Existing types extended: EvaluationInput gains optional task_definition
and environment_config fields; EvaluationOutput gains optional metrics
field and a with_metrics builder method.

Host function bindings (platform_terminal import module): terminal_exec,
terminal_read_file, terminal_write_file, terminal_list_dir,
terminal_get_time, terminal_random_seed extern declarations with safe
Rust wrappers following the existing host_http_get/host_http_post
pattern. Also fixes ABI mismatch in http_get which declared 3 params
but host expects 4 — adds the missing resp_len parameter.

Challenge trait extended with optional lifecycle methods generate_task
and setup_environment (with default no-op implementations). The
register_challenge! macro now exports these as additional WASM functions
using the same ptr/len ABI convention.

Allocator arena increased from 1 MiB to 4 MiB to accommodate terminal
output capture (stdout/stderr from command execution).

Author: echobt

crates/challenge-sdk-wasm/src/alloc_impl.rs

@@ -1,6 +1,6 @@
 use core::cell::UnsafeCell;
 
-const ARENA_SIZE: usize = 1024 * 1024; // 1 MiB
+const ARENA_SIZE: usize = 4 * 1024 * 1024; // 4 MiB
 
 struct BumpAllocator {
     arena: UnsafeCell<[u8; ARENA_SIZE]>,

crates/challenge-sdk-wasm/src/host_functions.rs

@@ -3,7 +3,7 @@ use alloc::vec::Vec;
 
 #[link(wasm_import_module = "platform_network")]
 extern "C" {
-    fn http_get(req_ptr: i32, req_len: i32, resp_ptr: i32) -> i32;
+    fn http_get(req_ptr: i32, req_len: i32, resp_ptr: i32, resp_len: i32) -> i32;
     fn http_post(req_ptr: i32, req_len: i32, resp_ptr: i32, resp_len: i32, extra: i32) -> i32;
     fn dns_resolve(req_ptr: i32, req_len: i32, resp_ptr: i32) -> i32;
 }
@@ -14,13 +14,24 @@ extern "C" {
     fn storage_set(key_ptr: i32, key_len: i32, value_ptr: i32, value_len: i32) -> i32;
 }
 
+#[link(wasm_import_module = "platform_terminal")]
+extern "C" {
+    fn terminal_exec(cmd_ptr: i32, cmd_len: i32, result_ptr: i32, result_len: i32) -> i32;
+    fn terminal_read_file(path_ptr: i32, path_len: i32, buf_ptr: i32, buf_len: i32) -> i32;
+    fn terminal_write_file(path_ptr: i32, path_len: i32, data_ptr: i32, data_len: i32) -> i32;
+    fn terminal_list_dir(path_ptr: i32, path_len: i32, buf_ptr: i32, buf_len: i32) -> i32;
+    fn terminal_get_time() -> i64;
+    fn terminal_random_seed(buf_ptr: i32, buf_len: i32) -> i32;
+}
+
 pub fn host_http_get(request: &[u8]) -> Result<Vec<u8>, i32> {
     let mut response_buf = vec![0u8; 65536];
     let status = unsafe {
         http_get(
             request.as_ptr() as i32,
             request.len() as i32,
             response_buf.as_mut_ptr() as i32,
+            response_buf.len() as i32,
         )
     };
     if status < 0 {
@@ -94,3 +105,81 @@ pub fn host_storage_set(key: &[u8], value: &[u8]) -> Result<(), i32> {
     }
     Ok(())
 }
+
+pub fn host_terminal_exec(request: &[u8]) -> Result<Vec<u8>, i32> {
+    let mut result_buf = vec![0u8; 262144];
+    let status = unsafe {
+        terminal_exec(
+            request.as_ptr() as i32,
+            request.len() as i32,
+            result_buf.as_mut_ptr() as i32,
+            result_buf.len() as i32,
+        )
+    };
+    if status < 0 {
+        return Err(status);
+    }
+    result_buf.truncate(status as usize);
+    Ok(result_buf)
+}
+
+pub fn host_read_file(path: &[u8]) -> Result<Vec<u8>, i32> {
+    let mut buf = vec![0u8; 262144];
+    let status = unsafe {
+        terminal_read_file(
+            path.as_ptr() as i32,
+            path.len() as i32,
+            buf.as_mut_ptr() as i32,
+            buf.len() as i32,
+        )
+    };
+    if status < 0 {
+        return Err(status);
+    }
+    buf.truncate(status as usize);
+    Ok(buf)
+}
+
+pub fn host_write_file(path: &[u8], data: &[u8]) -> Result<(), i32> {
+    let status = unsafe {
+        terminal_write_file(
+            path.as_ptr() as i32,
+            path.len() as i32,
+            data.as_ptr() as i32,
+            data.len() as i32,
+        )
+    };
+    if status < 0 {
+        return Err(status);
+    }
+    Ok(())
+}
+
+pub fn host_list_dir(path: &[u8]) -> Result<Vec<u8>, i32> {
+    let mut buf = vec![0u8; 65536];
+    let status = unsafe {
+        terminal_list_dir(
+            path.as_ptr() as i32,
+            path.len() as i32,
+            buf.as_mut_ptr() as i32,
+            buf.len() as i32,
+        )
+    };
+    if status < 0 {
+        return Err(status);
+    }
+    buf.truncate(status as usize);
+    Ok(buf)
+}
+
+pub fn host_get_time() -> i64 {
+    unsafe { terminal_get_time() }
+}
+
+pub fn host_random_seed(buf: &mut [u8]) -> Result<(), i32> {
+    let status = unsafe { terminal_random_seed(buf.as_mut_ptr() as i32, buf.len() as i32) };
+    if status < 0 {
+        return Err(status);
+    }
+    Ok(())
+}

crates/challenge-sdk-wasm/src/lib.rs

@@ -4,15 +4,25 @@ extern crate alloc;
 
 pub mod alloc_impl;
 pub mod host_functions;
+pub mod term_types;
 pub mod types;
 
+pub use term_types::*;
 pub use types::{EvaluationInput, EvaluationOutput};
 
 pub trait Challenge {
     fn name(&self) -> &'static str;
     fn version(&self) -> &'static str;
     fn evaluate(&self, input: EvaluationInput) -> EvaluationOutput;
     fn validate(&self, input: EvaluationInput) -> bool;
+
+    fn generate_task(&self, _params: &[u8]) -> alloc::vec::Vec<u8> {
+        alloc::vec::Vec::new()
+    }
+
+    fn setup_environment(&self, _config: &[u8]) -> bool {
+        true
+    }
 }
 
 /// Pack a pointer and length into a single i64 value.
@@ -25,7 +35,8 @@ pub fn pack_ptr_len(ptr: i32, len: i32) -> i64 {
 }
 
 /// Register a [`Challenge`] implementation and export the required WASM ABI
-/// functions (`evaluate`, `validate`, `get_name`, `get_version`, and `alloc`).
+/// functions (`evaluate`, `validate`, `get_name`, `get_version`,
+/// `generate_task`, `setup_environment`, and `alloc`).
 ///
 /// # Usage
 ///
@@ -119,5 +130,36 @@ macro_rules! register_challenge {
             }
             ptr as i32
         }
+
+        #[no_mangle]
+        pub extern "C" fn generate_task(params_ptr: i32, params_len: i32) -> i64 {
+            let slice = unsafe {
+                core::slice::from_raw_parts(params_ptr as *const u8, params_len as usize)
+            };
+            let output = <$ty as $crate::Challenge>::generate_task(&_CHALLENGE, slice);
+            if output.is_empty() {
+                return $crate::pack_ptr_len(0, 0);
+            }
+            let ptr = $crate::alloc_impl::sdk_alloc(output.len());
+            if ptr.is_null() {
+                return $crate::pack_ptr_len(0, 0);
+            }
+            unsafe {
+                core::ptr::copy_nonoverlapping(output.as_ptr(), ptr, output.len());
+            }
+            $crate::pack_ptr_len(ptr as i32, output.len() as i32)
+        }
+
+        #[no_mangle]
+        pub extern "C" fn setup_environment(config_ptr: i32, config_len: i32) -> i32 {
+            let slice = unsafe {
+                core::slice::from_raw_parts(config_ptr as *const u8, config_len as usize)
+            };
+            if <$ty as $crate::Challenge>::setup_environment(&_CHALLENGE, slice) {
+                1
+            } else {
+                0
+            }
+        }
     };
 }

crates/challenge-sdk-wasm/src/term_types.rs

@@ -0,0 +1,123 @@
+use alloc::string::String;
+use alloc::vec::Vec;
+use serde::{Deserialize, Serialize};
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct CommandRequest {
+    pub command: String,
+    pub args: Vec<String>,
+    pub env_vars: Vec<(String, String)>,
+    pub working_dir: Option<String>,
+    pub timeout_ms: u64,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct CommandResult {
+    pub exit_code: i32,
+    pub stdout: Vec<u8>,
+    pub stderr: Vec<u8>,
+    pub execution_time_ms: u64,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct FileReadRequest {
+    pub path: String,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct FileReadResponse {
+    pub data: Vec<u8>,
+    pub success: bool,
+    pub error: Option<String>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct FileWriteRequest {
+    pub path: String,
+    pub data: Vec<u8>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct FileWriteResponse {
+    pub success: bool,
+    pub bytes_written: u64,
+    pub error: Option<String>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct FileListRequest {
+    pub path: String,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct FileListResponse {
+    pub entries: Vec<FileEntry>,
+    pub success: bool,
+    pub error: Option<String>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct FileEntry {
+    pub name: String,
+    pub is_dir: bool,
+    pub size: u64,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct TaskDefinition {
+    pub task_id: String,
+    pub description: String,
+    pub expected_output_hash: Option<Vec<u8>>,
+    pub environment_config: Vec<u8>,
+    pub scoring_params: Vec<u8>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct TermEvaluationMetrics {
+    pub execution_time_ms: u64,
+    pub correctness_score: f64,
+    pub partial_credit: f64,
+    pub cost: f64,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct TermEvaluationInput {
+    pub agent_data: Vec<u8>,
+    pub challenge_id: String,
+    pub params: Vec<u8>,
+    pub task_definition: Option<Vec<u8>>,
+    pub environment_config: Option<Vec<u8>>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct TermEvaluationOutput {
+    pub score: i64,
+    pub valid: bool,
+    pub message: String,
+    pub metrics: Option<Vec<u8>>,
+}
+
+impl TermEvaluationOutput {
+    pub fn success(score: i64, message: &str) -> Self {
+        Self {
+            score,
+            valid: true,
+            message: String::from(message),
+            metrics: None,
+        }
+    }
+
+    pub fn failure(message: &str) -> Self {
+        Self {
+            score: 0,
+            valid: false,
+            message: String::from(message),
+            metrics: None,
+        }
+    }
+
+    pub fn with_metrics(mut self, metrics: Vec<u8>) -> Self {
+        self.metrics = Some(metrics);
+        self
+    }
+}

crates/challenge-sdk-wasm/src/types.rs

@@ -7,13 +7,16 @@ pub struct EvaluationInput {
     pub agent_data: Vec<u8>,
     pub challenge_id: String,
     pub params: Vec<u8>,
+    pub task_definition: Option<Vec<u8>>,
+    pub environment_config: Option<Vec<u8>>,
 }
 
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct EvaluationOutput {
     pub score: i64,
     pub valid: bool,
     pub message: String,
+    pub metrics: Option<Vec<u8>>,
 }
 
 impl EvaluationOutput {
@@ -22,6 +25,7 @@ impl EvaluationOutput {
             score,
             valid: true,
             message: String::from(message),
+            metrics: None,
         }
     }
 
@@ -30,6 +34,12 @@ impl EvaluationOutput {
             score: 0,
             valid: false,
             message: String::from(message),
+            metrics: None,
         }
     }
+
+    pub fn with_metrics(mut self, metrics: Vec<u8>) -> Self {
+        self.metrics = Some(metrics);
+        self
+    }
 }