Skip to main content

harn_vm/
stdlib.rs

1use std::collections::BTreeMap;
2use std::io::BufRead;
3use std::rc::Rc;
4use std::sync::atomic::{AtomicBool, AtomicI64, AtomicU8, Ordering};
5use std::sync::Arc;
6
7use crate::value::{values_equal, VmAtomicHandle, VmChannelHandle, VmError, VmValue};
8use crate::vm::Vm;
9
10use crate::http::register_http_builtins;
11use crate::llm::register_llm_builtins;
12use crate::mcp::register_mcp_builtins;
13
14/// Build a select result dict with the given index, value, and channel name.
15fn select_result(index: usize, value: VmValue, channel_name: &str) -> VmValue {
16    let mut result = BTreeMap::new();
17    result.insert("index".to_string(), VmValue::Int(index as i64));
18    result.insert("value".to_string(), value);
19    result.insert(
20        "channel".to_string(),
21        VmValue::String(Rc::from(channel_name)),
22    );
23    VmValue::Dict(Rc::new(result))
24}
25
26/// Build a select result dict indicating no channel was ready (index = -1).
27fn select_none() -> VmValue {
28    let mut result = BTreeMap::new();
29    result.insert("index".to_string(), VmValue::Int(-1));
30    result.insert("value".to_string(), VmValue::Nil);
31    result.insert("channel".to_string(), VmValue::Nil);
32    VmValue::Dict(Rc::new(result))
33}
34
35/// Try to receive from a list of channels (non-blocking).
36/// Returns Some((index, value, channel_name)) if a message was received,
37/// or None. Sets all_closed to true if all channels are disconnected.
38fn try_poll_channels(channels: &[VmValue]) -> (Option<(usize, VmValue, String)>, bool) {
39    let mut all_closed = true;
40    for (i, ch_val) in channels.iter().enumerate() {
41        if let VmValue::Channel(ch) = ch_val {
42            if let Ok(mut rx) = ch.receiver.try_lock() {
43                match rx.try_recv() {
44                    Ok(val) => return (Some((i, val, ch.name.clone())), false),
45                    Err(tokio::sync::mpsc::error::TryRecvError::Empty) => {
46                        all_closed = false;
47                    }
48                    Err(tokio::sync::mpsc::error::TryRecvError::Disconnected) => {}
49                }
50            } else {
51                all_closed = false;
52            }
53        }
54    }
55    (None, all_closed)
56}
57
58/// Register standard builtins on a VM.
59pub fn register_vm_stdlib(vm: &mut Vm) {
60    vm.register_builtin("log", |args, out| {
61        let msg = args.first().map(|a| a.display()).unwrap_or_default();
62        out.push_str(&format!("[harn] {msg}\n"));
63        Ok(VmValue::Nil)
64    });
65    vm.register_builtin("print", |args, out| {
66        let msg = args.first().map(|a| a.display()).unwrap_or_default();
67        out.push_str(&msg);
68        Ok(VmValue::Nil)
69    });
70    vm.register_builtin("println", |args, out| {
71        let msg = args.first().map(|a| a.display()).unwrap_or_default();
72        out.push_str(&format!("{msg}\n"));
73        Ok(VmValue::Nil)
74    });
75    vm.register_builtin("type_of", |args, _out| {
76        let val = args.first().unwrap_or(&VmValue::Nil);
77        Ok(VmValue::String(Rc::from(val.type_name())))
78    });
79    vm.register_builtin("to_string", |args, _out| {
80        let val = args.first().unwrap_or(&VmValue::Nil);
81        Ok(VmValue::String(Rc::from(val.display())))
82    });
83    vm.register_builtin("to_int", |args, _out| {
84        let val = args.first().unwrap_or(&VmValue::Nil);
85        match val {
86            VmValue::Int(n) => Ok(VmValue::Int(*n)),
87            VmValue::Float(n) => Ok(VmValue::Int(*n as i64)),
88            VmValue::String(s) => Ok(s.parse::<i64>().map(VmValue::Int).unwrap_or(VmValue::Nil)),
89            _ => Ok(VmValue::Nil),
90        }
91    });
92    vm.register_builtin("to_float", |args, _out| {
93        let val = args.first().unwrap_or(&VmValue::Nil);
94        match val {
95            VmValue::Float(n) => Ok(VmValue::Float(*n)),
96            VmValue::Int(n) => Ok(VmValue::Float(*n as f64)),
97            VmValue::String(s) => Ok(s.parse::<f64>().map(VmValue::Float).unwrap_or(VmValue::Nil)),
98            _ => Ok(VmValue::Nil),
99        }
100    });
101
102    vm.register_builtin("json_stringify", |args, _out| {
103        let val = args.first().unwrap_or(&VmValue::Nil);
104        Ok(VmValue::String(Rc::from(vm_value_to_json(val))))
105    });
106
107    vm.register_builtin("json_parse", |args, _out| {
108        let text = args.first().map(|a| a.display()).unwrap_or_default();
109        match serde_json::from_str::<serde_json::Value>(&text) {
110            Ok(jv) => Ok(json_to_vm_value(&jv)),
111            Err(e) => Err(VmError::Thrown(VmValue::String(Rc::from(format!(
112                "JSON parse error: {e}"
113            ))))),
114        }
115    });
116
117    vm.register_builtin("env", |args, _out| {
118        let name = args.first().map(|a| a.display()).unwrap_or_default();
119        match std::env::var(&name) {
120            Ok(val) => Ok(VmValue::String(Rc::from(val))),
121            Err(_) => Ok(VmValue::Nil),
122        }
123    });
124
125    vm.register_builtin("timestamp", |_args, _out| {
126        use std::time::{SystemTime, UNIX_EPOCH};
127        let secs = SystemTime::now()
128            .duration_since(UNIX_EPOCH)
129            .map(|d| d.as_secs_f64())
130            .unwrap_or(0.0);
131        Ok(VmValue::Float(secs))
132    });
133
134    vm.register_builtin("read_file", |args, _out| {
135        let path = args.first().map(|a| a.display()).unwrap_or_default();
136        match std::fs::read_to_string(&path) {
137            Ok(content) => Ok(VmValue::String(Rc::from(content))),
138            Err(e) => Err(VmError::Thrown(VmValue::String(Rc::from(format!(
139                "Failed to read file {path}: {e}"
140            ))))),
141        }
142    });
143
144    vm.register_builtin("write_file", |args, _out| {
145        if args.len() >= 2 {
146            let path = args[0].display();
147            let content = args[1].display();
148            std::fs::write(&path, &content).map_err(|e| {
149                VmError::Thrown(VmValue::String(Rc::from(format!(
150                    "Failed to write file {path}: {e}"
151                ))))
152            })?;
153        }
154        Ok(VmValue::Nil)
155    });
156
157    vm.register_builtin("exit", |args, _out| {
158        let code = args.first().and_then(|a| a.as_int()).unwrap_or(0);
159        std::process::exit(code as i32);
160    });
161
162    vm.register_builtin("regex_match", |args, _out| {
163        if args.len() >= 2 {
164            let pattern = args[0].display();
165            let text = args[1].display();
166            let re = regex::Regex::new(&pattern).map_err(|e| {
167                VmError::Thrown(VmValue::String(Rc::from(format!("Invalid regex: {e}"))))
168            })?;
169            let matches: Vec<VmValue> = re
170                .find_iter(&text)
171                .map(|m| VmValue::String(Rc::from(m.as_str())))
172                .collect();
173            if matches.is_empty() {
174                return Ok(VmValue::Nil);
175            }
176            return Ok(VmValue::List(Rc::new(matches)));
177        }
178        Ok(VmValue::Nil)
179    });
180
181    vm.register_builtin("regex_replace", |args, _out| {
182        if args.len() >= 3 {
183            let pattern = args[0].display();
184            let replacement = args[1].display();
185            let text = args[2].display();
186            let re = regex::Regex::new(&pattern).map_err(|e| {
187                VmError::Thrown(VmValue::String(Rc::from(format!("Invalid regex: {e}"))))
188            })?;
189            return Ok(VmValue::String(Rc::from(
190                re.replace_all(&text, replacement.as_str()).into_owned(),
191            )));
192        }
193        Ok(VmValue::Nil)
194    });
195
196    vm.register_builtin("prompt_user", |args, out| {
197        let msg = args.first().map(|a| a.display()).unwrap_or_default();
198        out.push_str(&msg);
199        let mut input = String::new();
200        if std::io::stdin().lock().read_line(&mut input).is_ok() {
201            Ok(VmValue::String(Rc::from(input.trim_end())))
202        } else {
203            Ok(VmValue::Nil)
204        }
205    });
206
207    // --- Math builtins ---
208
209    vm.register_builtin("abs", |args, _out| {
210        match args.first().unwrap_or(&VmValue::Nil) {
211            VmValue::Int(n) => Ok(VmValue::Int(n.wrapping_abs())),
212            VmValue::Float(n) => Ok(VmValue::Float(n.abs())),
213            _ => Ok(VmValue::Nil),
214        }
215    });
216
217    vm.register_builtin("min", |args, _out| {
218        if args.len() >= 2 {
219            match (&args[0], &args[1]) {
220                (VmValue::Int(x), VmValue::Int(y)) => Ok(VmValue::Int(*x.min(y))),
221                (VmValue::Float(x), VmValue::Float(y)) => Ok(VmValue::Float(x.min(*y))),
222                (VmValue::Int(x), VmValue::Float(y)) => Ok(VmValue::Float((*x as f64).min(*y))),
223                (VmValue::Float(x), VmValue::Int(y)) => Ok(VmValue::Float(x.min(*y as f64))),
224                _ => Ok(VmValue::Nil),
225            }
226        } else {
227            Ok(VmValue::Nil)
228        }
229    });
230
231    vm.register_builtin("max", |args, _out| {
232        if args.len() >= 2 {
233            match (&args[0], &args[1]) {
234                (VmValue::Int(x), VmValue::Int(y)) => Ok(VmValue::Int(*x.max(y))),
235                (VmValue::Float(x), VmValue::Float(y)) => Ok(VmValue::Float(x.max(*y))),
236                (VmValue::Int(x), VmValue::Float(y)) => Ok(VmValue::Float((*x as f64).max(*y))),
237                (VmValue::Float(x), VmValue::Int(y)) => Ok(VmValue::Float(x.max(*y as f64))),
238                _ => Ok(VmValue::Nil),
239            }
240        } else {
241            Ok(VmValue::Nil)
242        }
243    });
244
245    vm.register_builtin("floor", |args, _out| {
246        match args.first().unwrap_or(&VmValue::Nil) {
247            VmValue::Float(n) => Ok(VmValue::Int(n.floor() as i64)),
248            VmValue::Int(n) => Ok(VmValue::Int(*n)),
249            _ => Ok(VmValue::Nil),
250        }
251    });
252
253    vm.register_builtin("ceil", |args, _out| {
254        match args.first().unwrap_or(&VmValue::Nil) {
255            VmValue::Float(n) => Ok(VmValue::Int(n.ceil() as i64)),
256            VmValue::Int(n) => Ok(VmValue::Int(*n)),
257            _ => Ok(VmValue::Nil),
258        }
259    });
260
261    vm.register_builtin("round", |args, _out| {
262        match args.first().unwrap_or(&VmValue::Nil) {
263            VmValue::Float(n) => Ok(VmValue::Int(n.round() as i64)),
264            VmValue::Int(n) => Ok(VmValue::Int(*n)),
265            _ => Ok(VmValue::Nil),
266        }
267    });
268
269    vm.register_builtin("sqrt", |args, _out| {
270        match args.first().unwrap_or(&VmValue::Nil) {
271            VmValue::Float(n) => Ok(VmValue::Float(n.sqrt())),
272            VmValue::Int(n) => Ok(VmValue::Float((*n as f64).sqrt())),
273            _ => Ok(VmValue::Nil),
274        }
275    });
276
277    vm.register_builtin("pow", |args, _out| {
278        if args.len() >= 2 {
279            match (&args[0], &args[1]) {
280                (VmValue::Int(base), VmValue::Int(exp)) => {
281                    if *exp >= 0 && *exp <= u32::MAX as i64 {
282                        Ok(VmValue::Int(base.wrapping_pow(*exp as u32)))
283                    } else {
284                        Ok(VmValue::Float((*base as f64).powf(*exp as f64)))
285                    }
286                }
287                (VmValue::Float(base), VmValue::Int(exp)) => {
288                    if *exp >= i32::MIN as i64 && *exp <= i32::MAX as i64 {
289                        Ok(VmValue::Float(base.powi(*exp as i32)))
290                    } else {
291                        Ok(VmValue::Float(base.powf(*exp as f64)))
292                    }
293                }
294                (VmValue::Int(base), VmValue::Float(exp)) => {
295                    Ok(VmValue::Float((*base as f64).powf(*exp)))
296                }
297                (VmValue::Float(base), VmValue::Float(exp)) => Ok(VmValue::Float(base.powf(*exp))),
298                _ => Ok(VmValue::Nil),
299            }
300        } else {
301            Ok(VmValue::Nil)
302        }
303    });
304
305    vm.register_builtin("random", |_args, _out| {
306        use rand::Rng;
307        let val: f64 = rand::thread_rng().gen();
308        Ok(VmValue::Float(val))
309    });
310
311    vm.register_builtin("random_int", |args, _out| {
312        use rand::Rng;
313        if args.len() >= 2 {
314            let min = args[0].as_int().unwrap_or(0);
315            let max = args[1].as_int().unwrap_or(0);
316            if min <= max {
317                let val = rand::thread_rng().gen_range(min..=max);
318                return Ok(VmValue::Int(val));
319            }
320        }
321        Ok(VmValue::Nil)
322    });
323
324    // --- Assert builtins ---
325
326    vm.register_builtin("assert", |args, _out| {
327        let condition = args.first().unwrap_or(&VmValue::Nil);
328        if !condition.is_truthy() {
329            let msg = args
330                .get(1)
331                .map(|a| a.display())
332                .unwrap_or_else(|| "Assertion failed".to_string());
333            return Err(VmError::Thrown(VmValue::String(Rc::from(msg))));
334        }
335        Ok(VmValue::Nil)
336    });
337
338    vm.register_builtin("assert_eq", |args, _out| {
339        if args.len() >= 2 {
340            if !values_equal(&args[0], &args[1]) {
341                let msg = args.get(2).map(|a| a.display()).unwrap_or_else(|| {
342                    format!(
343                        "Assertion failed: expected {}, got {}",
344                        args[1].display(),
345                        args[0].display()
346                    )
347                });
348                return Err(VmError::Thrown(VmValue::String(Rc::from(msg))));
349            }
350            Ok(VmValue::Nil)
351        } else {
352            Err(VmError::Thrown(VmValue::String(Rc::from(
353                "assert_eq requires at least 2 arguments",
354            ))))
355        }
356    });
357
358    vm.register_builtin("assert_ne", |args, _out| {
359        if args.len() >= 2 {
360            if values_equal(&args[0], &args[1]) {
361                let msg = args.get(2).map(|a| a.display()).unwrap_or_else(|| {
362                    format!(
363                        "Assertion failed: values should not be equal: {}",
364                        args[0].display()
365                    )
366                });
367                return Err(VmError::Thrown(VmValue::String(Rc::from(msg))));
368            }
369            Ok(VmValue::Nil)
370        } else {
371            Err(VmError::Thrown(VmValue::String(Rc::from(
372                "assert_ne requires at least 2 arguments",
373            ))))
374        }
375    });
376
377    vm.register_builtin("__range__", |args, _out| {
378        let start = args.first().and_then(|a| a.as_int()).unwrap_or(0);
379        let end = args.get(1).and_then(|a| a.as_int()).unwrap_or(0);
380        let inclusive = args.get(2).map(|a| a.is_truthy()).unwrap_or(false);
381        let items: Vec<VmValue> = if inclusive {
382            (start..=end).map(VmValue::Int).collect()
383        } else {
384            (start..end).map(VmValue::Int).collect()
385        };
386        Ok(VmValue::List(Rc::new(items)))
387    });
388
389    // =========================================================================
390    // File system builtins
391    // =========================================================================
392
393    vm.register_builtin("file_exists", |args, _out| {
394        let path = args.first().map(|a| a.display()).unwrap_or_default();
395        Ok(VmValue::Bool(std::path::Path::new(&path).exists()))
396    });
397
398    vm.register_builtin("delete_file", |args, _out| {
399        let path = args.first().map(|a| a.display()).unwrap_or_default();
400        let p = std::path::Path::new(&path);
401        if p.is_dir() {
402            std::fs::remove_dir_all(&path).map_err(|e| {
403                VmError::Thrown(VmValue::String(Rc::from(format!(
404                    "Failed to delete directory {path}: {e}"
405                ))))
406            })?;
407        } else {
408            std::fs::remove_file(&path).map_err(|e| {
409                VmError::Thrown(VmValue::String(Rc::from(format!(
410                    "Failed to delete file {path}: {e}"
411                ))))
412            })?;
413        }
414        Ok(VmValue::Nil)
415    });
416
417    vm.register_builtin("append_file", |args, _out| {
418        use std::io::Write;
419        if args.len() >= 2 {
420            let path = args[0].display();
421            let content = args[1].display();
422            let mut file = std::fs::OpenOptions::new()
423                .append(true)
424                .create(true)
425                .open(&path)
426                .map_err(|e| {
427                    VmError::Thrown(VmValue::String(Rc::from(format!(
428                        "Failed to open file {path}: {e}"
429                    ))))
430                })?;
431            file.write_all(content.as_bytes()).map_err(|e| {
432                VmError::Thrown(VmValue::String(Rc::from(format!(
433                    "Failed to append to file {path}: {e}"
434                ))))
435            })?;
436        }
437        Ok(VmValue::Nil)
438    });
439
440    vm.register_builtin("list_dir", |args, _out| {
441        let path = args
442            .first()
443            .map(|a| a.display())
444            .unwrap_or_else(|| ".".to_string());
445        let entries = std::fs::read_dir(&path).map_err(|e| {
446            VmError::Thrown(VmValue::String(Rc::from(format!(
447                "Failed to list directory {path}: {e}"
448            ))))
449        })?;
450        let mut result = Vec::new();
451        for entry in entries {
452            let entry =
453                entry.map_err(|e| VmError::Thrown(VmValue::String(Rc::from(e.to_string()))))?;
454            let name = entry.file_name().to_string_lossy().to_string();
455            result.push(VmValue::String(Rc::from(name.as_str())));
456        }
457        result.sort_by_key(|a| a.display());
458        Ok(VmValue::List(Rc::new(result)))
459    });
460
461    vm.register_builtin("mkdir", |args, _out| {
462        let path = args.first().map(|a| a.display()).unwrap_or_default();
463        std::fs::create_dir_all(&path).map_err(|e| {
464            VmError::Thrown(VmValue::String(Rc::from(format!(
465                "Failed to create directory {path}: {e}"
466            ))))
467        })?;
468        Ok(VmValue::Nil)
469    });
470
471    vm.register_builtin("path_join", |args, _out| {
472        let mut path = std::path::PathBuf::new();
473        for arg in args {
474            path.push(arg.display());
475        }
476        Ok(VmValue::String(Rc::from(
477            path.to_string_lossy().to_string().as_str(),
478        )))
479    });
480
481    vm.register_builtin("copy_file", |args, _out| {
482        if args.len() >= 2 {
483            let src = args[0].display();
484            let dst = args[1].display();
485            std::fs::copy(&src, &dst).map_err(|e| {
486                VmError::Thrown(VmValue::String(Rc::from(format!(
487                    "Failed to copy {src} to {dst}: {e}"
488                ))))
489            })?;
490        }
491        Ok(VmValue::Nil)
492    });
493
494    vm.register_builtin("temp_dir", |_args, _out| {
495        Ok(VmValue::String(Rc::from(
496            std::env::temp_dir().to_string_lossy().to_string().as_str(),
497        )))
498    });
499
500    vm.register_builtin("stat", |args, _out| {
501        let path = args.first().map(|a| a.display()).unwrap_or_default();
502        let metadata = std::fs::metadata(&path).map_err(|e| {
503            VmError::Thrown(VmValue::String(Rc::from(format!(
504                "Failed to stat {path}: {e}"
505            ))))
506        })?;
507        let mut info = BTreeMap::new();
508        info.insert("size".to_string(), VmValue::Int(metadata.len() as i64));
509        info.insert("is_file".to_string(), VmValue::Bool(metadata.is_file()));
510        info.insert("is_dir".to_string(), VmValue::Bool(metadata.is_dir()));
511        info.insert(
512            "readonly".to_string(),
513            VmValue::Bool(metadata.permissions().readonly()),
514        );
515        if let Ok(modified) = metadata.modified() {
516            if let Ok(dur) = modified.duration_since(std::time::UNIX_EPOCH) {
517                info.insert("modified".to_string(), VmValue::Float(dur.as_secs_f64()));
518            }
519        }
520        Ok(VmValue::Dict(Rc::new(info)))
521    });
522
523    // =========================================================================
524    // Process execution builtins
525    // =========================================================================
526
527    vm.register_builtin("exec", |args, _out| {
528        if args.is_empty() {
529            return Err(VmError::Thrown(VmValue::String(Rc::from(
530                "exec: command is required",
531            ))));
532        }
533        let cmd = args[0].display();
534        let cmd_args: Vec<String> = args[1..].iter().map(|a| a.display()).collect();
535        let output = std::process::Command::new(&cmd)
536            .args(&cmd_args)
537            .output()
538            .map_err(|e| VmError::Thrown(VmValue::String(Rc::from(format!("exec failed: {e}")))))?;
539        Ok(vm_output_to_value(output))
540    });
541
542    vm.register_builtin("shell", |args, _out| {
543        let cmd = args.first().map(|a| a.display()).unwrap_or_default();
544        if cmd.is_empty() {
545            return Err(VmError::Thrown(VmValue::String(Rc::from(
546                "shell: command string is required",
547            ))));
548        }
549        let shell = if cfg!(target_os = "windows") {
550            "cmd"
551        } else {
552            "sh"
553        };
554        let flag = if cfg!(target_os = "windows") {
555            "/C"
556        } else {
557            "-c"
558        };
559        let output = std::process::Command::new(shell)
560            .arg(flag)
561            .arg(&cmd)
562            .output()
563            .map_err(|e| {
564                VmError::Thrown(VmValue::String(Rc::from(format!("shell failed: {e}"))))
565            })?;
566        Ok(vm_output_to_value(output))
567    });
568
569    // =========================================================================
570    // Date/time builtins
571    // =========================================================================
572
573    vm.register_builtin("date_now", |_args, _out| {
574        use std::time::{SystemTime, UNIX_EPOCH};
575        let now = SystemTime::now()
576            .duration_since(UNIX_EPOCH)
577            .unwrap_or_default();
578        let total_secs = now.as_secs();
579        let (y, m, d, hour, minute, second, dow) = vm_civil_from_timestamp(total_secs);
580        let mut result = BTreeMap::new();
581        result.insert("year".to_string(), VmValue::Int(y));
582        result.insert("month".to_string(), VmValue::Int(m));
583        result.insert("day".to_string(), VmValue::Int(d));
584        result.insert("hour".to_string(), VmValue::Int(hour));
585        result.insert("minute".to_string(), VmValue::Int(minute));
586        result.insert("second".to_string(), VmValue::Int(second));
587        result.insert("weekday".to_string(), VmValue::Int(dow));
588        result.insert("timestamp".to_string(), VmValue::Float(now.as_secs_f64()));
589        Ok(VmValue::Dict(Rc::new(result)))
590    });
591
592    vm.register_builtin("date_format", |args, _out| {
593        let ts = match args.first() {
594            Some(VmValue::Float(f)) => *f,
595            Some(VmValue::Int(n)) => *n as f64,
596            Some(VmValue::Dict(map)) => map
597                .get("timestamp")
598                .and_then(|v| match v {
599                    VmValue::Float(f) => Some(*f),
600                    VmValue::Int(n) => Some(*n as f64),
601                    _ => None,
602                })
603                .unwrap_or(0.0),
604            _ => 0.0,
605        };
606        let fmt = args
607            .get(1)
608            .map(|a| a.display())
609            .unwrap_or_else(|| "%Y-%m-%d %H:%M:%S".to_string());
610
611        let (y, m, d, hour, minute, second, _dow) = vm_civil_from_timestamp(ts as u64);
612
613        let result = fmt
614            .replace("%Y", &format!("{y:04}"))
615            .replace("%m", &format!("{m:02}"))
616            .replace("%d", &format!("{d:02}"))
617            .replace("%H", &format!("{hour:02}"))
618            .replace("%M", &format!("{minute:02}"))
619            .replace("%S", &format!("{second:02}"));
620
621        Ok(VmValue::String(Rc::from(result.as_str())))
622    });
623
624    vm.register_builtin("date_parse", |args, _out| {
625        let s = args.first().map(|a| a.display()).unwrap_or_default();
626        let parts: Vec<&str> = s.split(|c: char| !c.is_ascii_digit()).collect();
627        let parts: Vec<i64> = parts.iter().filter_map(|p| p.parse().ok()).collect();
628        if parts.len() < 3 {
629            return Err(VmError::Thrown(VmValue::String(Rc::from(format!(
630                "Cannot parse date: {s}"
631            )))));
632        }
633        let (y, m, d) = (parts[0], parts[1], parts[2]);
634        let hour = parts.get(3).copied().unwrap_or(0);
635        let minute = parts.get(4).copied().unwrap_or(0);
636        let second = parts.get(5).copied().unwrap_or(0);
637
638        let (y_adj, m_adj) = if m <= 2 {
639            (y - 1, (m + 9) as u64)
640        } else {
641            (y, (m - 3) as u64)
642        };
643        let era = if y_adj >= 0 { y_adj } else { y_adj - 399 } / 400;
644        let yoe = (y_adj - era * 400) as u64;
645        let doy = (153 * m_adj + 2) / 5 + d as u64 - 1;
646        let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;
647        let days = era * 146097 + doe as i64 - 719468;
648        let ts = days * 86400 + hour * 3600 + minute * 60 + second;
649        Ok(VmValue::Float(ts as f64))
650    });
651
652    // =========================================================================
653    // String formatting
654    // =========================================================================
655
656    vm.register_builtin("format", |args, _out| {
657        let template = args.first().map(|a| a.display()).unwrap_or_default();
658        let mut result = String::with_capacity(template.len());
659        let mut arg_iter = args.iter().skip(1);
660        let mut rest = template.as_str();
661        while let Some(pos) = rest.find("{}") {
662            result.push_str(&rest[..pos]);
663            if let Some(arg) = arg_iter.next() {
664                result.push_str(&arg.display());
665            } else {
666                result.push_str("{}");
667            }
668            rest = &rest[pos + 2..];
669        }
670        result.push_str(rest);
671        Ok(VmValue::String(Rc::from(result.as_str())))
672    });
673
674    // =========================================================================
675    // Standalone string function builtins
676    // =========================================================================
677
678    vm.register_builtin("trim", |args, _out| {
679        let s = args.first().map(|a| a.display()).unwrap_or_default();
680        Ok(VmValue::String(Rc::from(s.trim())))
681    });
682
683    vm.register_builtin("lowercase", |args, _out| {
684        let s = args.first().map(|a| a.display()).unwrap_or_default();
685        Ok(VmValue::String(Rc::from(s.to_lowercase().as_str())))
686    });
687
688    vm.register_builtin("uppercase", |args, _out| {
689        let s = args.first().map(|a| a.display()).unwrap_or_default();
690        Ok(VmValue::String(Rc::from(s.to_uppercase().as_str())))
691    });
692
693    vm.register_builtin("split", |args, _out| {
694        let s = args.first().map(|a| a.display()).unwrap_or_default();
695        let sep = args
696            .get(1)
697            .map(|a| a.display())
698            .unwrap_or_else(|| " ".to_string());
699        let parts: Vec<VmValue> = s
700            .split(&sep)
701            .map(|p| VmValue::String(Rc::from(p)))
702            .collect();
703        Ok(VmValue::List(Rc::new(parts)))
704    });
705
706    vm.register_builtin("starts_with", |args, _out| {
707        let s = args.first().map(|a| a.display()).unwrap_or_default();
708        let prefix = args.get(1).map(|a| a.display()).unwrap_or_default();
709        Ok(VmValue::Bool(s.starts_with(&prefix)))
710    });
711
712    vm.register_builtin("ends_with", |args, _out| {
713        let s = args.first().map(|a| a.display()).unwrap_or_default();
714        let suffix = args.get(1).map(|a| a.display()).unwrap_or_default();
715        Ok(VmValue::Bool(s.ends_with(&suffix)))
716    });
717
718    vm.register_builtin("contains", |args, _out| {
719        match args.first().unwrap_or(&VmValue::Nil) {
720            VmValue::String(s) => {
721                let substr = args.get(1).map(|a| a.display()).unwrap_or_default();
722                Ok(VmValue::Bool(s.contains(&substr)))
723            }
724            VmValue::List(items) => {
725                let target = args.get(1).unwrap_or(&VmValue::Nil);
726                Ok(VmValue::Bool(
727                    items.iter().any(|item| values_equal(item, target)),
728                ))
729            }
730            _ => Ok(VmValue::Bool(false)),
731        }
732    });
733
734    vm.register_builtin("replace", |args, _out| {
735        let s = args.first().map(|a| a.display()).unwrap_or_default();
736        let old = args.get(1).map(|a| a.display()).unwrap_or_default();
737        let new = args.get(2).map(|a| a.display()).unwrap_or_default();
738        Ok(VmValue::String(Rc::from(s.replace(&old, &new).as_str())))
739    });
740
741    vm.register_builtin("join", |args, _out| {
742        let sep = args.get(1).map(|a| a.display()).unwrap_or_default();
743        match args.first() {
744            Some(VmValue::List(items)) => {
745                let parts: Vec<String> = items.iter().map(|v| v.display()).collect();
746                Ok(VmValue::String(Rc::from(parts.join(&sep).as_str())))
747            }
748            _ => Ok(VmValue::String(Rc::from(""))),
749        }
750    });
751
752    vm.register_builtin("len", |args, _out| {
753        match args.first().unwrap_or(&VmValue::Nil) {
754            VmValue::String(s) => Ok(VmValue::Int(s.len() as i64)),
755            VmValue::List(items) => Ok(VmValue::Int(items.len() as i64)),
756            VmValue::Dict(map) => Ok(VmValue::Int(map.len() as i64)),
757            _ => Ok(VmValue::Int(0)),
758        }
759    });
760
761    vm.register_builtin("substring", |args, _out| {
762        let s = args.first().map(|a| a.display()).unwrap_or_default();
763        let start = args.get(1).and_then(|a| a.as_int()).unwrap_or(0) as usize;
764        let start = start.min(s.len());
765        match args.get(2).and_then(|a| a.as_int()) {
766            Some(length) => {
767                let length = (length as usize).min(s.len() - start);
768                Ok(VmValue::String(Rc::from(&s[start..start + length])))
769            }
770            None => Ok(VmValue::String(Rc::from(&s[start..]))),
771        }
772    });
773
774    // =========================================================================
775    // Path builtins
776    // =========================================================================
777
778    vm.register_builtin("dirname", |args, _out| {
779        let path = args.first().map(|a| a.display()).unwrap_or_default();
780        let p = std::path::Path::new(&path);
781        match p.parent() {
782            Some(parent) => Ok(VmValue::String(Rc::from(parent.to_string_lossy().as_ref()))),
783            None => Ok(VmValue::String(Rc::from(""))),
784        }
785    });
786
787    vm.register_builtin("basename", |args, _out| {
788        let path = args.first().map(|a| a.display()).unwrap_or_default();
789        let p = std::path::Path::new(&path);
790        match p.file_name() {
791            Some(name) => Ok(VmValue::String(Rc::from(name.to_string_lossy().as_ref()))),
792            None => Ok(VmValue::String(Rc::from(""))),
793        }
794    });
795
796    vm.register_builtin("extname", |args, _out| {
797        let path = args.first().map(|a| a.display()).unwrap_or_default();
798        let p = std::path::Path::new(&path);
799        match p.extension() {
800            Some(ext) => Ok(VmValue::String(Rc::from(
801                format!(".{}", ext.to_string_lossy()).as_str(),
802            ))),
803            None => Ok(VmValue::String(Rc::from(""))),
804        }
805    });
806
807    // =========================================================================
808    // Prompt template rendering
809    // =========================================================================
810
811    vm.register_builtin("render", |args, _out| {
812        let path = args.first().map(|a| a.display()).unwrap_or_default();
813        let template = std::fs::read_to_string(&path).map_err(|e| {
814            VmError::Thrown(VmValue::String(Rc::from(format!(
815                "Failed to read template {path}: {e}"
816            ))))
817        })?;
818        if let Some(bindings) = args.get(1).and_then(|a| a.as_dict()) {
819            let mut result = template;
820            for (key, val) in bindings.iter() {
821                result = result.replace(&format!("{{{{{key}}}}}"), &val.display());
822            }
823            Ok(VmValue::String(Rc::from(result)))
824        } else {
825            Ok(VmValue::String(Rc::from(template)))
826        }
827    });
828
829    // =========================================================================
830    // Logging builtins
831    // =========================================================================
832
833    vm.register_builtin("log_debug", |args, out| {
834        vm_write_log("debug", 0, args, out);
835        Ok(VmValue::Nil)
836    });
837
838    vm.register_builtin("log_info", |args, out| {
839        vm_write_log("info", 1, args, out);
840        Ok(VmValue::Nil)
841    });
842
843    vm.register_builtin("log_warn", |args, out| {
844        vm_write_log("warn", 2, args, out);
845        Ok(VmValue::Nil)
846    });
847
848    vm.register_builtin("log_error", |args, out| {
849        vm_write_log("error", 3, args, out);
850        Ok(VmValue::Nil)
851    });
852
853    vm.register_builtin("log_set_level", |args, _out| {
854        let level_str = args.first().map(|a| a.display()).unwrap_or_default();
855        match vm_level_to_u8(&level_str) {
856            Some(n) => {
857                VM_MIN_LOG_LEVEL.store(n, Ordering::Relaxed);
858                Ok(VmValue::Nil)
859            }
860            None => Err(VmError::Thrown(VmValue::String(Rc::from(format!(
861                "log_set_level: invalid level '{}'. Expected debug, info, warn, or error",
862                level_str
863            ))))),
864        }
865    });
866
867    // =========================================================================
868    // Tracing builtins
869    // =========================================================================
870
871    vm.register_builtin("trace_start", |args, _out| {
872        use rand::Rng;
873        let name = args.first().map(|a| a.display()).unwrap_or_default();
874        let trace_id = VM_TRACE_STACK.with(|stack| {
875            stack
876                .borrow()
877                .last()
878                .map(|t| t.trace_id.clone())
879                .unwrap_or_else(|| {
880                    let val: u32 = rand::thread_rng().gen();
881                    format!("{val:08x}")
882                })
883        });
884        let span_id = {
885            let val: u32 = rand::thread_rng().gen();
886            format!("{val:08x}")
887        };
888        let start_ms = std::time::SystemTime::now()
889            .duration_since(std::time::UNIX_EPOCH)
890            .unwrap_or_default()
891            .as_millis() as i64;
892
893        VM_TRACE_STACK.with(|stack| {
894            stack.borrow_mut().push(VmTraceContext {
895                trace_id: trace_id.clone(),
896                span_id: span_id.clone(),
897            });
898        });
899
900        let mut span = BTreeMap::new();
901        span.insert(
902            "trace_id".to_string(),
903            VmValue::String(Rc::from(trace_id.as_str())),
904        );
905        span.insert(
906            "span_id".to_string(),
907            VmValue::String(Rc::from(span_id.as_str())),
908        );
909        span.insert("name".to_string(), VmValue::String(Rc::from(name.as_str())));
910        span.insert("start_ms".to_string(), VmValue::Int(start_ms));
911        Ok(VmValue::Dict(Rc::new(span)))
912    });
913
914    vm.register_builtin("trace_end", |args, out| {
915        let span = match args.first() {
916            Some(VmValue::Dict(d)) => d,
917            _ => {
918                return Err(VmError::Thrown(VmValue::String(Rc::from(
919                    "trace_end: argument must be a span dict from trace_start",
920                ))));
921            }
922        };
923
924        let end_ms = std::time::SystemTime::now()
925            .duration_since(std::time::UNIX_EPOCH)
926            .unwrap_or_default()
927            .as_millis() as i64;
928
929        let start_ms = span
930            .get("start_ms")
931            .and_then(|v| v.as_int())
932            .unwrap_or(end_ms);
933        let duration_ms = end_ms - start_ms;
934        let name = span.get("name").map(|v| v.display()).unwrap_or_default();
935        let trace_id = span
936            .get("trace_id")
937            .map(|v| v.display())
938            .unwrap_or_default();
939        let span_id = span.get("span_id").map(|v| v.display()).unwrap_or_default();
940
941        VM_TRACE_STACK.with(|stack| {
942            stack.borrow_mut().pop();
943        });
944
945        let level_num = 1_u8;
946        if level_num >= VM_MIN_LOG_LEVEL.load(Ordering::Relaxed) {
947            let mut fields = BTreeMap::new();
948            fields.insert(
949                "trace_id".to_string(),
950                VmValue::String(Rc::from(trace_id.as_str())),
951            );
952            fields.insert(
953                "span_id".to_string(),
954                VmValue::String(Rc::from(span_id.as_str())),
955            );
956            fields.insert("name".to_string(), VmValue::String(Rc::from(name.as_str())));
957            fields.insert("duration_ms".to_string(), VmValue::Int(duration_ms));
958            let line = vm_build_log_line("info", "span_end", Some(&fields));
959            out.push_str(&line);
960        }
961
962        Ok(VmValue::Nil)
963    });
964
965    vm.register_builtin("trace_id", |_args, _out| {
966        let id = VM_TRACE_STACK.with(|stack| stack.borrow().last().map(|t| t.trace_id.clone()));
967        match id {
968            Some(trace_id) => Ok(VmValue::String(Rc::from(trace_id.as_str()))),
969            None => Ok(VmValue::Nil),
970        }
971    });
972
973    // =========================================================================
974    // LLM introspection builtins
975    // =========================================================================
976
977    vm.register_builtin("llm_info", |_args, _out| {
978        let provider = std::env::var("HARN_LLM_PROVIDER").unwrap_or_default();
979        let model = std::env::var("HARN_LLM_MODEL").unwrap_or_default();
980        let api_key_set = std::env::var("HARN_API_KEY")
981            .or_else(|_| std::env::var("OPENROUTER_API_KEY"))
982            .or_else(|_| std::env::var("ANTHROPIC_API_KEY"))
983            .is_ok();
984        let mut info = BTreeMap::new();
985        info.insert("provider".to_string(), VmValue::String(Rc::from(provider.as_str())));
986        info.insert("model".to_string(), VmValue::String(Rc::from(model.as_str())));
987        info.insert("api_key_set".to_string(), VmValue::Bool(api_key_set));
988        Ok(VmValue::Dict(Rc::new(info)))
989    });
990
991    vm.register_builtin("llm_usage", |_args, _out| {
992        let (total_input, total_output, total_duration, call_count) =
993            crate::llm::peek_trace_summary();
994        let mut usage = BTreeMap::new();
995        usage.insert("input_tokens".to_string(), VmValue::Int(total_input));
996        usage.insert("output_tokens".to_string(), VmValue::Int(total_output));
997        usage.insert("total_duration_ms".to_string(), VmValue::Int(total_duration));
998        usage.insert("call_count".to_string(), VmValue::Int(call_count));
999        Ok(VmValue::Dict(Rc::new(usage)))
1000    });
1001
1002    // =========================================================================
1003    // Timer builtins
1004    // =========================================================================
1005
1006    vm.register_builtin("timer_start", |args, _out| {
1007        let name = args.first().map(|a| a.display()).unwrap_or_else(|| "default".to_string());
1008        let now_ms = std::time::SystemTime::now()
1009            .duration_since(std::time::UNIX_EPOCH)
1010            .unwrap_or_default()
1011            .as_millis() as i64;
1012        let mut timer = BTreeMap::new();
1013        timer.insert("name".to_string(), VmValue::String(Rc::from(name.as_str())));
1014        timer.insert("start_ms".to_string(), VmValue::Int(now_ms));
1015        Ok(VmValue::Dict(Rc::new(timer)))
1016    });
1017
1018    vm.register_builtin("timer_end", |args, out| {
1019        let timer = match args.first() {
1020            Some(VmValue::Dict(d)) => d,
1021            _ => {
1022                return Err(VmError::Thrown(VmValue::String(Rc::from(
1023                    "timer_end: argument must be a timer dict from timer_start",
1024                ))));
1025            }
1026        };
1027        let now_ms = std::time::SystemTime::now()
1028            .duration_since(std::time::UNIX_EPOCH)
1029            .unwrap_or_default()
1030            .as_millis() as i64;
1031        let start_ms = timer.get("start_ms").and_then(|v| v.as_int()).unwrap_or(now_ms);
1032        let elapsed = now_ms - start_ms;
1033        let name = timer.get("name").map(|v| v.display()).unwrap_or_default();
1034        out.push_str(&format!("[timer] {name}: {elapsed}ms\n"));
1035        Ok(VmValue::Int(elapsed))
1036    });
1037
1038    vm.register_builtin("elapsed", |_args, _out| {
1039        // Milliseconds since process start (approximated via monotonic clock).
1040        // Uses a stable epoch: first call anchors to 0.
1041        static START: std::sync::OnceLock<std::time::Instant> = std::sync::OnceLock::new();
1042        let start = START.get_or_init(std::time::Instant::now);
1043        Ok(VmValue::Int(start.elapsed().as_millis() as i64))
1044    });
1045
1046    vm.register_builtin("log_json", |args, out| {
1047        let key = args.first().map(|a| a.display()).unwrap_or_default();
1048        let value = args.get(1).cloned().unwrap_or(VmValue::Nil);
1049        let json_val = vm_value_to_json_fragment(&value);
1050        let ts = vm_format_timestamp_utc();
1051        out.push_str(&format!(
1052            "{{\"ts\":{},\"key\":{},\"value\":{}}}\n",
1053            vm_escape_json_str_quoted(&ts),
1054            vm_escape_json_str_quoted(&key),
1055            json_val,
1056        ));
1057        Ok(VmValue::Nil)
1058    });
1059
1060    // =========================================================================
1061    // Tool registry builtins
1062    // =========================================================================
1063
1064    vm.register_builtin("tool_registry", |_args, _out| {
1065        let mut registry = BTreeMap::new();
1066        registry.insert(
1067            "_type".to_string(),
1068            VmValue::String(Rc::from("tool_registry")),
1069        );
1070        registry.insert("tools".to_string(), VmValue::List(Rc::new(Vec::new())));
1071        Ok(VmValue::Dict(Rc::new(registry)))
1072    });
1073
1074    vm.register_builtin("tool_add", |args, _out| {
1075        if args.len() < 4 {
1076            return Err(VmError::Thrown(VmValue::String(Rc::from(
1077                "tool_add: requires registry, name, description, and handler",
1078            ))));
1079        }
1080
1081        let registry = match &args[0] {
1082            VmValue::Dict(map) => (**map).clone(),
1083            _ => {
1084                return Err(VmError::Thrown(VmValue::String(Rc::from(
1085                    "tool_add: first argument must be a tool registry",
1086                ))));
1087            }
1088        };
1089
1090        match registry.get("_type") {
1091            Some(VmValue::String(t)) if &**t == "tool_registry" => {}
1092            _ => {
1093                return Err(VmError::Thrown(VmValue::String(Rc::from(
1094                    "tool_add: first argument must be a tool registry",
1095                ))));
1096            }
1097        }
1098
1099        let name = args[1].display();
1100        let description = args[2].display();
1101        let handler = args[3].clone();
1102        let parameters = if args.len() > 4 {
1103            args[4].clone()
1104        } else {
1105            VmValue::Dict(Rc::new(BTreeMap::new()))
1106        };
1107
1108        let mut tool_entry = BTreeMap::new();
1109        tool_entry.insert("name".to_string(), VmValue::String(Rc::from(name.as_str())));
1110        tool_entry.insert(
1111            "description".to_string(),
1112            VmValue::String(Rc::from(description.as_str())),
1113        );
1114        tool_entry.insert("handler".to_string(), handler);
1115        tool_entry.insert("parameters".to_string(), parameters);
1116
1117        let mut tools: Vec<VmValue> = match registry.get("tools") {
1118            Some(VmValue::List(list)) => list
1119                .iter()
1120                .filter(|t| {
1121                    if let VmValue::Dict(e) = t {
1122                        e.get("name").map(|v| v.display()).as_deref() != Some(name.as_str())
1123                    } else {
1124                        true
1125                    }
1126                })
1127                .cloned()
1128                .collect(),
1129            _ => Vec::new(),
1130        };
1131        tools.push(VmValue::Dict(Rc::new(tool_entry)));
1132
1133        let mut new_registry = registry;
1134        new_registry.insert("tools".to_string(), VmValue::List(Rc::new(tools)));
1135        Ok(VmValue::Dict(Rc::new(new_registry)))
1136    });
1137
1138    vm.register_builtin("tool_list", |args, _out| {
1139        let registry = match args.first() {
1140            Some(VmValue::Dict(map)) => map,
1141            _ => {
1142                return Err(VmError::Thrown(VmValue::String(Rc::from(
1143                    "tool_list: requires a tool registry",
1144                ))));
1145            }
1146        };
1147        vm_validate_registry("tool_list", registry)?;
1148
1149        let tools = vm_get_tools(registry);
1150        let mut result = Vec::new();
1151        for tool in tools {
1152            if let VmValue::Dict(entry) = tool {
1153                let mut desc = BTreeMap::new();
1154                if let Some(name) = entry.get("name") {
1155                    desc.insert("name".to_string(), name.clone());
1156                }
1157                if let Some(description) = entry.get("description") {
1158                    desc.insert("description".to_string(), description.clone());
1159                }
1160                if let Some(parameters) = entry.get("parameters") {
1161                    desc.insert("parameters".to_string(), parameters.clone());
1162                }
1163                result.push(VmValue::Dict(Rc::new(desc)));
1164            }
1165        }
1166        Ok(VmValue::List(Rc::new(result)))
1167    });
1168
1169    vm.register_builtin("tool_find", |args, _out| {
1170        if args.len() < 2 {
1171            return Err(VmError::Thrown(VmValue::String(Rc::from(
1172                "tool_find: requires registry and name",
1173            ))));
1174        }
1175
1176        let registry = match &args[0] {
1177            VmValue::Dict(map) => map,
1178            _ => {
1179                return Err(VmError::Thrown(VmValue::String(Rc::from(
1180                    "tool_find: first argument must be a tool registry",
1181                ))));
1182            }
1183        };
1184        vm_validate_registry("tool_find", registry)?;
1185
1186        let target_name = args[1].display();
1187        let tools = vm_get_tools(registry);
1188
1189        for tool in tools {
1190            if let VmValue::Dict(entry) = tool {
1191                if let Some(VmValue::String(name)) = entry.get("name") {
1192                    if &**name == target_name.as_str() {
1193                        return Ok(tool.clone());
1194                    }
1195                }
1196            }
1197        }
1198        Ok(VmValue::Nil)
1199    });
1200
1201    vm.register_builtin("tool_describe", |args, _out| {
1202        let registry = match args.first() {
1203            Some(VmValue::Dict(map)) => map,
1204            _ => {
1205                return Err(VmError::Thrown(VmValue::String(Rc::from(
1206                    "tool_describe: requires a tool registry",
1207                ))));
1208            }
1209        };
1210        vm_validate_registry("tool_describe", registry)?;
1211
1212        let tools = vm_get_tools(registry);
1213
1214        if tools.is_empty() {
1215            return Ok(VmValue::String(Rc::from("Available tools:\n(none)")));
1216        }
1217
1218        let mut tool_infos: Vec<(String, String, String)> = Vec::new();
1219        for tool in tools {
1220            if let VmValue::Dict(entry) = tool {
1221                let name = entry.get("name").map(|v| v.display()).unwrap_or_default();
1222                let description = entry
1223                    .get("description")
1224                    .map(|v| v.display())
1225                    .unwrap_or_default();
1226                let params_str = vm_format_parameters(entry.get("parameters"));
1227                tool_infos.push((name, params_str, description));
1228            }
1229        }
1230
1231        tool_infos.sort_by(|a, b| a.0.cmp(&b.0));
1232
1233        let mut lines = vec!["Available tools:".to_string()];
1234        for (name, params, desc) in &tool_infos {
1235            lines.push(format!("- {name}({params}): {desc}"));
1236        }
1237
1238        Ok(VmValue::String(Rc::from(lines.join("\n").as_str())))
1239    });
1240
1241    vm.register_builtin("tool_remove", |args, _out| {
1242        if args.len() < 2 {
1243            return Err(VmError::Thrown(VmValue::String(Rc::from(
1244                "tool_remove: requires registry and name",
1245            ))));
1246        }
1247
1248        let registry = match &args[0] {
1249            VmValue::Dict(map) => (**map).clone(),
1250            _ => {
1251                return Err(VmError::Thrown(VmValue::String(Rc::from(
1252                    "tool_remove: first argument must be a tool registry",
1253                ))));
1254            }
1255        };
1256        vm_validate_registry("tool_remove", &registry)?;
1257
1258        let target_name = args[1].display();
1259
1260        let tools = match registry.get("tools") {
1261            Some(VmValue::List(list)) => (**list).clone(),
1262            _ => Vec::new(),
1263        };
1264
1265        let filtered: Vec<VmValue> = tools
1266            .into_iter()
1267            .filter(|tool| {
1268                if let VmValue::Dict(entry) = tool {
1269                    if let Some(VmValue::String(name)) = entry.get("name") {
1270                        return &**name != target_name.as_str();
1271                    }
1272                }
1273                true
1274            })
1275            .collect();
1276
1277        let mut new_registry = registry;
1278        new_registry.insert("tools".to_string(), VmValue::List(Rc::new(filtered)));
1279        Ok(VmValue::Dict(Rc::new(new_registry)))
1280    });
1281
1282    vm.register_builtin("tool_count", |args, _out| {
1283        let registry = match args.first() {
1284            Some(VmValue::Dict(map)) => map,
1285            _ => {
1286                return Err(VmError::Thrown(VmValue::String(Rc::from(
1287                    "tool_count: requires a tool registry",
1288                ))));
1289            }
1290        };
1291        vm_validate_registry("tool_count", registry)?;
1292        let count = vm_get_tools(registry).len();
1293        Ok(VmValue::Int(count as i64))
1294    });
1295
1296    vm.register_builtin("tool_schema", |args, _out| {
1297        let registry = match args.first() {
1298            Some(VmValue::Dict(map)) => {
1299                vm_validate_registry("tool_schema", map)?;
1300                map
1301            }
1302            _ => {
1303                return Err(VmError::Thrown(VmValue::String(Rc::from(
1304                    "tool_schema: requires a tool registry",
1305                ))));
1306            }
1307        };
1308
1309        let components = args.get(1).and_then(|v| v.as_dict()).cloned();
1310
1311        let tools = match registry.get("tools") {
1312            Some(VmValue::List(list)) => list,
1313            _ => return Ok(VmValue::Dict(Rc::new(vm_build_empty_schema()))),
1314        };
1315
1316        let mut tool_schemas = Vec::new();
1317        for tool in tools.iter() {
1318            if let VmValue::Dict(entry) = tool {
1319                let name = entry.get("name").map(|v| v.display()).unwrap_or_default();
1320                let description = entry
1321                    .get("description")
1322                    .map(|v| v.display())
1323                    .unwrap_or_default();
1324
1325                let input_schema =
1326                    vm_build_input_schema(entry.get("parameters"), components.as_ref());
1327
1328                let mut tool_def = BTreeMap::new();
1329                tool_def.insert("name".to_string(), VmValue::String(Rc::from(name.as_str())));
1330                tool_def.insert(
1331                    "description".to_string(),
1332                    VmValue::String(Rc::from(description.as_str())),
1333                );
1334                tool_def.insert("inputSchema".to_string(), input_schema);
1335                tool_schemas.push(VmValue::Dict(Rc::new(tool_def)));
1336            }
1337        }
1338
1339        let mut schema = BTreeMap::new();
1340        schema.insert(
1341            "schema_version".to_string(),
1342            VmValue::String(Rc::from("harn-tools/1.0")),
1343        );
1344
1345        if let Some(comps) = &components {
1346            let mut comp_wrapper = BTreeMap::new();
1347            comp_wrapper.insert("schemas".to_string(), VmValue::Dict(Rc::new(comps.clone())));
1348            schema.insert(
1349                "components".to_string(),
1350                VmValue::Dict(Rc::new(comp_wrapper)),
1351            );
1352        }
1353
1354        schema.insert("tools".to_string(), VmValue::List(Rc::new(tool_schemas)));
1355        Ok(VmValue::Dict(Rc::new(schema)))
1356    });
1357
1358    vm.register_builtin("tool_parse_call", |args, _out| {
1359        let text = args.first().map(|a| a.display()).unwrap_or_default();
1360
1361        let mut results = Vec::new();
1362        let mut search_from = 0;
1363
1364        while let Some(start) = text[search_from..].find("<tool_call>") {
1365            let abs_start = search_from + start + "<tool_call>".len();
1366            if let Some(end) = text[abs_start..].find("</tool_call>") {
1367                let json_str = text[abs_start..abs_start + end].trim();
1368                if let Ok(jv) = serde_json::from_str::<serde_json::Value>(json_str) {
1369                    results.push(json_to_vm_value(&jv));
1370                }
1371                search_from = abs_start + end + "</tool_call>".len();
1372            } else {
1373                break;
1374            }
1375        }
1376
1377        Ok(VmValue::List(Rc::new(results)))
1378    });
1379
1380    vm.register_builtin("tool_format_result", |args, _out| {
1381        if args.len() < 2 {
1382            return Err(VmError::Thrown(VmValue::String(Rc::from(
1383                "tool_format_result: requires name and result",
1384            ))));
1385        }
1386        let name = args[0].display();
1387        let result = args[1].display();
1388
1389        let json_name = vm_escape_json_str(&name);
1390        let json_result = vm_escape_json_str(&result);
1391        Ok(VmValue::String(Rc::from(
1392            format!(
1393                "<tool_result>{{\"name\": \"{json_name}\", \"result\": \"{json_result}\"}}</tool_result>"
1394            )
1395            .as_str(),
1396        )))
1397    });
1398
1399    vm.register_builtin("tool_prompt", |args, _out| {
1400        let registry = match args.first() {
1401            Some(VmValue::Dict(map)) => {
1402                vm_validate_registry("tool_prompt", map)?;
1403                map
1404            }
1405            _ => {
1406                return Err(VmError::Thrown(VmValue::String(Rc::from(
1407                    "tool_prompt: requires a tool registry",
1408                ))));
1409            }
1410        };
1411
1412        let tools = match registry.get("tools") {
1413            Some(VmValue::List(list)) => list,
1414            _ => {
1415                return Ok(VmValue::String(Rc::from("No tools are available.")));
1416            }
1417        };
1418
1419        if tools.is_empty() {
1420            return Ok(VmValue::String(Rc::from("No tools are available.")));
1421        }
1422
1423        let mut prompt = String::from("# Available Tools\n\n");
1424        prompt.push_str("You have access to the following tools. To use a tool, output a tool call in this exact format:\n\n");
1425        prompt.push_str("<tool_call>{\"name\": \"tool_name\", \"arguments\": {\"param\": \"value\"}}</tool_call>\n\n");
1426        prompt.push_str("You may make multiple tool calls in a single response. Wait for tool results before proceeding.\n\n");
1427        prompt.push_str("## Tools\n\n");
1428
1429        let mut tool_infos: Vec<(&BTreeMap<String, VmValue>, String)> = Vec::new();
1430        for tool in tools.iter() {
1431            if let VmValue::Dict(entry) = tool {
1432                let name = entry.get("name").map(|v| v.display()).unwrap_or_default();
1433                tool_infos.push((entry, name));
1434            }
1435        }
1436        tool_infos.sort_by(|a, b| a.1.cmp(&b.1));
1437
1438        for (entry, name) in &tool_infos {
1439            let description = entry
1440                .get("description")
1441                .map(|v| v.display())
1442                .unwrap_or_default();
1443            let params_str = vm_format_parameters(entry.get("parameters"));
1444
1445            prompt.push_str(&format!("### {name}\n"));
1446            prompt.push_str(&format!("{description}\n"));
1447            if !params_str.is_empty() {
1448                prompt.push_str(&format!("Parameters: {params_str}\n"));
1449            }
1450            prompt.push('\n');
1451        }
1452
1453        Ok(VmValue::String(Rc::from(prompt.trim_end())))
1454    });
1455
1456    // =========================================================================
1457    // Channel builtins (sync)
1458    // =========================================================================
1459
1460    vm.register_builtin("channel", |args, _out| {
1461        let name = args
1462            .first()
1463            .map(|a| a.display())
1464            .unwrap_or_else(|| "default".to_string());
1465        let capacity = args.get(1).and_then(|a| a.as_int()).unwrap_or(256) as usize;
1466        let capacity = capacity.max(1);
1467        let (tx, rx) = tokio::sync::mpsc::channel(capacity);
1468        #[allow(clippy::arc_with_non_send_sync)]
1469        Ok(VmValue::Channel(VmChannelHandle {
1470            name,
1471            sender: Arc::new(tx),
1472            receiver: Arc::new(tokio::sync::Mutex::new(rx)),
1473            closed: Arc::new(AtomicBool::new(false)),
1474        }))
1475    });
1476
1477    vm.register_builtin("close_channel", |args, _out| {
1478        if args.is_empty() {
1479            return Err(VmError::Thrown(VmValue::String(Rc::from(
1480                "close_channel: requires a channel",
1481            ))));
1482        }
1483        if let VmValue::Channel(ch) = &args[0] {
1484            ch.closed.store(true, Ordering::SeqCst);
1485            Ok(VmValue::Nil)
1486        } else {
1487            Err(VmError::Thrown(VmValue::String(Rc::from(
1488                "close_channel: first argument must be a channel",
1489            ))))
1490        }
1491    });
1492
1493    vm.register_builtin("try_receive", |args, _out| {
1494        if args.is_empty() {
1495            return Err(VmError::Thrown(VmValue::String(Rc::from(
1496                "try_receive: requires a channel",
1497            ))));
1498        }
1499        if let VmValue::Channel(ch) = &args[0] {
1500            match ch.receiver.try_lock() {
1501                Ok(mut rx) => match rx.try_recv() {
1502                    Ok(val) => Ok(val),
1503                    Err(_) => Ok(VmValue::Nil),
1504                },
1505                Err(_) => Ok(VmValue::Nil),
1506            }
1507        } else {
1508            Err(VmError::Thrown(VmValue::String(Rc::from(
1509                "try_receive: first argument must be a channel",
1510            ))))
1511        }
1512    });
1513
1514    // =========================================================================
1515    // Atomic builtins
1516    // =========================================================================
1517
1518    vm.register_builtin("atomic", |args, _out| {
1519        let initial = match args.first() {
1520            Some(VmValue::Int(n)) => *n,
1521            Some(VmValue::Float(f)) => *f as i64,
1522            Some(VmValue::Bool(b)) => {
1523                if *b {
1524                    1
1525                } else {
1526                    0
1527                }
1528            }
1529            _ => 0,
1530        };
1531        Ok(VmValue::Atomic(VmAtomicHandle {
1532            value: Arc::new(AtomicI64::new(initial)),
1533        }))
1534    });
1535
1536    vm.register_builtin("atomic_get", |args, _out| {
1537        if let Some(VmValue::Atomic(a)) = args.first() {
1538            Ok(VmValue::Int(a.value.load(Ordering::SeqCst)))
1539        } else {
1540            Ok(VmValue::Nil)
1541        }
1542    });
1543
1544    vm.register_builtin("atomic_set", |args, _out| {
1545        if args.len() >= 2 {
1546            if let (VmValue::Atomic(a), Some(val)) = (&args[0], args[1].as_int()) {
1547                let old = a.value.swap(val, Ordering::SeqCst);
1548                return Ok(VmValue::Int(old));
1549            }
1550        }
1551        Ok(VmValue::Nil)
1552    });
1553
1554    vm.register_builtin("atomic_add", |args, _out| {
1555        if args.len() >= 2 {
1556            if let (VmValue::Atomic(a), Some(delta)) = (&args[0], args[1].as_int()) {
1557                let prev = a.value.fetch_add(delta, Ordering::SeqCst);
1558                return Ok(VmValue::Int(prev));
1559            }
1560        }
1561        Ok(VmValue::Nil)
1562    });
1563
1564    vm.register_builtin("atomic_cas", |args, _out| {
1565        if args.len() >= 3 {
1566            if let (VmValue::Atomic(a), Some(expected), Some(new_val)) =
1567                (&args[0], args[1].as_int(), args[2].as_int())
1568            {
1569                let result =
1570                    a.value
1571                        .compare_exchange(expected, new_val, Ordering::SeqCst, Ordering::SeqCst);
1572                return Ok(VmValue::Bool(result.is_ok()));
1573            }
1574        }
1575        Ok(VmValue::Bool(false))
1576    });
1577
1578    // =========================================================================
1579    // Async builtins
1580    // =========================================================================
1581
1582    // sleep(ms)
1583    vm.register_async_builtin("sleep", |args| async move {
1584        let ms = match args.first() {
1585            Some(VmValue::Duration(ms)) => *ms,
1586            Some(VmValue::Int(n)) => *n as u64,
1587            _ => 0,
1588        };
1589        if ms > 0 {
1590            tokio::time::sleep(tokio::time::Duration::from_millis(ms)).await;
1591        }
1592        Ok(VmValue::Nil)
1593    });
1594
1595    // send(channel, value)
1596    vm.register_async_builtin("send", |args| async move {
1597        if args.len() < 2 {
1598            return Err(VmError::Thrown(VmValue::String(Rc::from(
1599                "send: requires channel and value",
1600            ))));
1601        }
1602        if let VmValue::Channel(ch) = &args[0] {
1603            if ch.closed.load(Ordering::SeqCst) {
1604                return Ok(VmValue::Bool(false));
1605            }
1606            let val = args[1].clone();
1607            match ch.sender.send(val).await {
1608                Ok(()) => Ok(VmValue::Bool(true)),
1609                Err(_) => Ok(VmValue::Bool(false)),
1610            }
1611        } else {
1612            Err(VmError::Thrown(VmValue::String(Rc::from(
1613                "send: first argument must be a channel",
1614            ))))
1615        }
1616    });
1617
1618    // receive(channel)
1619    vm.register_async_builtin("receive", |args| async move {
1620        if args.is_empty() {
1621            return Err(VmError::Thrown(VmValue::String(Rc::from(
1622                "receive: requires a channel",
1623            ))));
1624        }
1625        if let VmValue::Channel(ch) = &args[0] {
1626            if ch.closed.load(Ordering::SeqCst) {
1627                let mut rx = ch.receiver.lock().await;
1628                return match rx.try_recv() {
1629                    Ok(val) => Ok(val),
1630                    Err(_) => Ok(VmValue::Nil),
1631                };
1632            }
1633            let mut rx = ch.receiver.lock().await;
1634            match rx.recv().await {
1635                Some(val) => Ok(val),
1636                None => Ok(VmValue::Nil),
1637            }
1638        } else {
1639            Err(VmError::Thrown(VmValue::String(Rc::from(
1640                "receive: first argument must be a channel",
1641            ))))
1642        }
1643    });
1644
1645    // select(channel1, channel2, ...) — blocking multiplexed receive (variadic)
1646    vm.register_async_builtin("select", |args| async move {
1647        if args.is_empty() {
1648            return Err(VmError::Thrown(VmValue::String(Rc::from(
1649                "select: requires at least one channel",
1650            ))));
1651        }
1652        for arg in &args {
1653            if !matches!(arg, VmValue::Channel(_)) {
1654                return Err(VmError::Thrown(VmValue::String(Rc::from(
1655                    "select: all arguments must be channels",
1656                ))));
1657            }
1658        }
1659        loop {
1660            let (found, all_closed) = try_poll_channels(&args);
1661            if let Some((i, val, name)) = found {
1662                return Ok(select_result(i, val, &name));
1663            }
1664            if all_closed {
1665                return Ok(select_none());
1666            }
1667            tokio::task::yield_now().await;
1668        }
1669    });
1670
1671    // __select_timeout(channel_list, timeout_ms) — select with timeout
1672    vm.register_async_builtin("__select_timeout", |args| async move {
1673        if args.len() < 2 {
1674            return Err(VmError::Thrown(VmValue::String(Rc::from(
1675                "__select_timeout: requires channel list and timeout",
1676            ))));
1677        }
1678        let channels = match &args[0] {
1679            VmValue::List(items) => (**items).clone(),
1680            _ => {
1681                return Err(VmError::Thrown(VmValue::String(Rc::from(
1682                    "__select_timeout: first argument must be a list of channels",
1683                ))));
1684            }
1685        };
1686        let timeout_ms = match &args[1] {
1687            VmValue::Int(n) => (*n).max(0) as u64,
1688            VmValue::Duration(ms) => *ms,
1689            _ => 5000,
1690        };
1691        let deadline = tokio::time::Instant::now()
1692            + tokio::time::Duration::from_millis(timeout_ms);
1693        loop {
1694            let (found, all_closed) = try_poll_channels(&channels);
1695            if let Some((i, val, name)) = found {
1696                return Ok(select_result(i, val, &name));
1697            }
1698            if all_closed || tokio::time::Instant::now() >= deadline {
1699                return Ok(select_none());
1700            }
1701            tokio::task::yield_now().await;
1702        }
1703    });
1704
1705    // __select_try(channel_list) — non-blocking select (for default case)
1706    vm.register_async_builtin("__select_try", |args| async move {
1707        if args.is_empty() {
1708            return Err(VmError::Thrown(VmValue::String(Rc::from(
1709                "__select_try: requires channel list",
1710            ))));
1711        }
1712        let channels = match &args[0] {
1713            VmValue::List(items) => (**items).clone(),
1714            _ => {
1715                return Err(VmError::Thrown(VmValue::String(Rc::from(
1716                    "__select_try: first argument must be a list of channels",
1717                ))));
1718            }
1719        };
1720        let (found, _) = try_poll_channels(&channels);
1721        if let Some((i, val, name)) = found {
1722            Ok(select_result(i, val, &name))
1723        } else {
1724            Ok(select_none())
1725        }
1726    });
1727
1728    // __select_list(channel_list) — blocking select from a list of channels
1729    vm.register_async_builtin("__select_list", |args| async move {
1730        if args.is_empty() {
1731            return Err(VmError::Thrown(VmValue::String(Rc::from(
1732                "__select_list: requires channel list",
1733            ))));
1734        }
1735        let channels = match &args[0] {
1736            VmValue::List(items) => (**items).clone(),
1737            _ => {
1738                return Err(VmError::Thrown(VmValue::String(Rc::from(
1739                    "__select_list: first argument must be a list of channels",
1740                ))));
1741            }
1742        };
1743        loop {
1744            let (found, all_closed) = try_poll_channels(&channels);
1745            if let Some((i, val, name)) = found {
1746                return Ok(select_result(i, val, &name));
1747            }
1748            if all_closed {
1749                return Ok(select_none());
1750            }
1751            tokio::task::yield_now().await;
1752        }
1753    });
1754
1755    // =========================================================================
1756    // JSON validation and extraction builtins
1757    // =========================================================================
1758
1759    vm.register_builtin("json_validate", |args, _out| {
1760        if args.len() < 2 {
1761            return Err(VmError::Thrown(VmValue::String(Rc::from(
1762                "json_validate requires 2 arguments: data and schema",
1763            ))));
1764        }
1765        let data = &args[0];
1766        let schema = &args[1];
1767        let schema_dict = match schema.as_dict() {
1768            Some(d) => d,
1769            None => {
1770                return Err(VmError::Thrown(VmValue::String(Rc::from(
1771                    "json_validate: schema must be a dict",
1772                ))));
1773            }
1774        };
1775        let mut errors = Vec::new();
1776        validate_value(data, schema_dict, "", &mut errors);
1777        if errors.is_empty() {
1778            Ok(VmValue::Bool(true))
1779        } else {
1780            Err(VmError::Thrown(VmValue::String(Rc::from(
1781                errors.join("; "),
1782            ))))
1783        }
1784    });
1785
1786    vm.register_builtin("json_extract", |args, _out| {
1787        if args.is_empty() {
1788            return Err(VmError::Thrown(VmValue::String(Rc::from(
1789                "json_extract requires at least 1 argument: text",
1790            ))));
1791        }
1792        let text = args[0].display();
1793        let key = args.get(1).map(|a| a.display());
1794
1795        // Extract JSON from text that may contain markdown code fences
1796        let json_str = extract_json_from_text(&text);
1797        let parsed = match serde_json::from_str::<serde_json::Value>(&json_str) {
1798            Ok(jv) => json_to_vm_value(&jv),
1799            Err(e) => {
1800                return Err(VmError::Thrown(VmValue::String(Rc::from(format!(
1801                    "json_extract: failed to parse JSON: {e}"
1802                )))));
1803            }
1804        };
1805
1806        match key {
1807            Some(k) => match &parsed {
1808                VmValue::Dict(map) => match map.get(&k) {
1809                    Some(val) => Ok(val.clone()),
1810                    None => Err(VmError::Thrown(VmValue::String(Rc::from(format!(
1811                        "json_extract: key '{}' not found",
1812                        k
1813                    ))))),
1814                },
1815                _ => Err(VmError::Thrown(VmValue::String(Rc::from(
1816                    "json_extract: parsed value is not a dict, cannot extract key",
1817                )))),
1818            },
1819            None => Ok(parsed),
1820        }
1821    });
1822
1823    // =========================================================================
1824    // HTTP and LLM builtins (registered from separate modules)
1825    // =========================================================================
1826
1827    // =========================================================================
1828    // Internal builtins (used by compiler-generated code)
1829    // =========================================================================
1830
1831    vm.register_builtin("__assert_dict", |args, _out| {
1832        let val = args.first().cloned().unwrap_or(VmValue::Nil);
1833        if matches!(val, VmValue::Dict(_)) {
1834            Ok(VmValue::Nil)
1835        } else {
1836            Err(VmError::TypeError(format!(
1837                "cannot destructure {} with {{...}} pattern — expected dict",
1838                val.type_name()
1839            )))
1840        }
1841    });
1842
1843    vm.register_builtin("__assert_list", |args, _out| {
1844        let val = args.first().cloned().unwrap_or(VmValue::Nil);
1845        if matches!(val, VmValue::List(_)) {
1846            Ok(VmValue::Nil)
1847        } else {
1848            Err(VmError::TypeError(format!(
1849                "cannot destructure {} with [...] pattern — expected list",
1850                val.type_name()
1851            )))
1852        }
1853    });
1854
1855    vm.register_builtin("__dict_rest", |args, _out| {
1856        // __dict_rest(dict, keys_to_exclude) -> new dict without those keys
1857        let dict = args.first().cloned().unwrap_or(VmValue::Nil);
1858        let keys_list = args.get(1).cloned().unwrap_or(VmValue::Nil);
1859        if let VmValue::Dict(map) = dict {
1860            let exclude: std::collections::HashSet<String> = match keys_list {
1861                VmValue::List(items) => items
1862                    .iter()
1863                    .filter_map(|v| {
1864                        if let VmValue::String(s) = v {
1865                            Some(s.to_string())
1866                        } else {
1867                            None
1868                        }
1869                    })
1870                    .collect(),
1871                _ => std::collections::HashSet::new(),
1872            };
1873            let rest: BTreeMap<String, VmValue> = map
1874                .iter()
1875                .filter(|(k, _)| !exclude.contains(k.as_str()))
1876                .map(|(k, v)| (k.clone(), v.clone()))
1877                .collect();
1878            Ok(VmValue::Dict(Rc::new(rest)))
1879        } else {
1880            Ok(VmValue::Nil)
1881        }
1882    });
1883
1884    register_http_builtins(vm);
1885    register_llm_builtins(vm);
1886    register_mcp_builtins(vm);
1887}
1888
1889// =============================================================================
1890// JSON helpers
1891// =============================================================================
1892
1893pub(crate) fn escape_json_string_vm(s: &str) -> String {
1894    let mut out = String::with_capacity(s.len() + 2);
1895    out.push('"');
1896    for ch in s.chars() {
1897        match ch {
1898            '"' => out.push_str("\\\""),
1899            '\\' => out.push_str("\\\\"),
1900            '\n' => out.push_str("\\n"),
1901            '\r' => out.push_str("\\r"),
1902            '\t' => out.push_str("\\t"),
1903            c if c.is_control() => {
1904                out.push_str(&format!("\\u{:04x}", c as u32));
1905            }
1906            c => out.push(c),
1907        }
1908    }
1909    out.push('"');
1910    out
1911}
1912
1913pub(crate) fn vm_value_to_json(val: &VmValue) -> String {
1914    match val {
1915        VmValue::String(s) => escape_json_string_vm(s),
1916        VmValue::Int(n) => n.to_string(),
1917        VmValue::Float(n) => n.to_string(),
1918        VmValue::Bool(b) => b.to_string(),
1919        VmValue::Nil => "null".to_string(),
1920        VmValue::List(items) => {
1921            let inner: Vec<String> = items.iter().map(vm_value_to_json).collect();
1922            format!("[{}]", inner.join(","))
1923        }
1924        VmValue::Dict(map) => {
1925            let inner: Vec<String> = map
1926                .iter()
1927                .map(|(k, v)| format!("{}:{}", escape_json_string_vm(k), vm_value_to_json(v)))
1928                .collect();
1929            format!("{{{}}}", inner.join(","))
1930        }
1931        _ => "null".to_string(),
1932    }
1933}
1934
1935pub(crate) fn json_to_vm_value(jv: &serde_json::Value) -> VmValue {
1936    match jv {
1937        serde_json::Value::Null => VmValue::Nil,
1938        serde_json::Value::Bool(b) => VmValue::Bool(*b),
1939        serde_json::Value::Number(n) => {
1940            if let Some(i) = n.as_i64() {
1941                VmValue::Int(i)
1942            } else {
1943                VmValue::Float(n.as_f64().unwrap_or(0.0))
1944            }
1945        }
1946        serde_json::Value::String(s) => VmValue::String(Rc::from(s.as_str())),
1947        serde_json::Value::Array(arr) => {
1948            VmValue::List(Rc::new(arr.iter().map(json_to_vm_value).collect()))
1949        }
1950        serde_json::Value::Object(map) => {
1951            let mut m = BTreeMap::new();
1952            for (k, v) in map {
1953                m.insert(k.clone(), json_to_vm_value(v));
1954            }
1955            VmValue::Dict(Rc::new(m))
1956        }
1957    }
1958}
1959
1960// =============================================================================
1961// Helper: validate a VmValue against a schema dict
1962// =============================================================================
1963
1964fn validate_value(
1965    value: &VmValue,
1966    schema: &BTreeMap<String, VmValue>,
1967    path: &str,
1968    errors: &mut Vec<String>,
1969) {
1970    // Check "type" constraint
1971    if let Some(VmValue::String(expected_type)) = schema.get("type") {
1972        let actual_type = value.type_name();
1973        let type_str: &str = expected_type;
1974        if type_str != "any" && actual_type != type_str {
1975            let location = if path.is_empty() {
1976                "root".to_string()
1977            } else {
1978                path.to_string()
1979            };
1980            errors.push(format!(
1981                "at {}: expected type '{}', got '{}'",
1982                location, type_str, actual_type
1983            ));
1984            return; // No point checking further if type is wrong
1985        }
1986    }
1987
1988    // Check "required" keys (only for dicts)
1989    if let Some(VmValue::List(required_keys)) = schema.get("required") {
1990        if let VmValue::Dict(map) = value {
1991            for key_val in required_keys.iter() {
1992                let key = key_val.display();
1993                if !map.contains_key(&key) {
1994                    let location = if path.is_empty() {
1995                        "root".to_string()
1996                    } else {
1997                        path.to_string()
1998                    };
1999                    errors.push(format!("at {}: missing required key '{}'", location, key));
2000                }
2001            }
2002        }
2003    }
2004
2005    // Check "properties" (only for dicts)
2006    if let Some(VmValue::Dict(prop_schemas)) = schema.get("properties") {
2007        if let VmValue::Dict(map) = value {
2008            for (key, prop_schema) in prop_schemas.iter() {
2009                if let Some(prop_value) = map.get(key) {
2010                    if let Some(prop_schema_dict) = prop_schema.as_dict() {
2011                        let child_path = if path.is_empty() {
2012                            key.clone()
2013                        } else {
2014                            format!("{}.{}", path, key)
2015                        };
2016                        validate_value(prop_value, prop_schema_dict, &child_path, errors);
2017                    }
2018                }
2019            }
2020        }
2021    }
2022
2023    // Check "items" (only for lists)
2024    if let Some(VmValue::Dict(item_schema)) = schema.get("items") {
2025        if let VmValue::List(items) = value {
2026            for (i, item) in items.iter().enumerate() {
2027                let child_path = if path.is_empty() {
2028                    format!("[{}]", i)
2029                } else {
2030                    format!("{}[{}]", path, i)
2031                };
2032                validate_value(item, item_schema, &child_path, errors);
2033            }
2034        }
2035    }
2036}
2037
2038// =============================================================================
2039// Helper: extract JSON from text with possible markdown fences
2040// =============================================================================
2041
2042fn extract_json_from_text(text: &str) -> String {
2043    let trimmed = text.trim();
2044
2045    // Try to find ```json ... ``` or ``` ... ``` code fences
2046    if let Some(start) = trimmed.find("```") {
2047        let after_backticks = &trimmed[start + 3..];
2048        // Skip optional language tag (e.g., "json")
2049        let content_start = if let Some(nl) = after_backticks.find('\n') {
2050            nl + 1
2051        } else {
2052            0
2053        };
2054        let content = &after_backticks[content_start..];
2055        if let Some(end) = content.find("```") {
2056            return content[..end].trim().to_string();
2057        }
2058    }
2059
2060    // No code fences found; try to find JSON object or array boundaries
2061    // Look for first { or [ and last matching } or ]
2062    if let Some(obj_start) = trimmed.find('{') {
2063        if let Some(obj_end) = trimmed.rfind('}') {
2064            if obj_end > obj_start {
2065                return trimmed[obj_start..=obj_end].to_string();
2066            }
2067        }
2068    }
2069    if let Some(arr_start) = trimmed.find('[') {
2070        if let Some(arr_end) = trimmed.rfind(']') {
2071            if arr_end > arr_start {
2072                return trimmed[arr_start..=arr_end].to_string();
2073            }
2074        }
2075    }
2076
2077    // Fall back to trimmed text as-is
2078    trimmed.to_string()
2079}
2080
2081// =============================================================================
2082// Helper: convert process::Output to VmValue dict
2083// =============================================================================
2084
2085fn vm_output_to_value(output: std::process::Output) -> VmValue {
2086    let mut result = BTreeMap::new();
2087    result.insert(
2088        "stdout".to_string(),
2089        VmValue::String(Rc::from(
2090            String::from_utf8_lossy(&output.stdout).to_string().as_str(),
2091        )),
2092    );
2093    result.insert(
2094        "stderr".to_string(),
2095        VmValue::String(Rc::from(
2096            String::from_utf8_lossy(&output.stderr).to_string().as_str(),
2097        )),
2098    );
2099    result.insert(
2100        "status".to_string(),
2101        VmValue::Int(output.status.code().unwrap_or(-1) as i64),
2102    );
2103    result.insert(
2104        "success".to_string(),
2105        VmValue::Bool(output.status.success()),
2106    );
2107    VmValue::Dict(Rc::new(result))
2108}
2109
2110// =============================================================================
2111// Helper: civil date from timestamp (Howard Hinnant's algorithm)
2112// =============================================================================
2113
2114fn vm_civil_from_timestamp(total_secs: u64) -> (i64, i64, i64, i64, i64, i64, i64) {
2115    let days = total_secs / 86400;
2116    let time_of_day = total_secs % 86400;
2117    let hour = (time_of_day / 3600) as i64;
2118    let minute = ((time_of_day % 3600) / 60) as i64;
2119    let second = (time_of_day % 60) as i64;
2120
2121    let z = days as i64 + 719468;
2122    let era = if z >= 0 { z } else { z - 146096 } / 146097;
2123    let doe = (z - era * 146097) as u64;
2124    let yoe = (doe - doe / 1460 + doe / 36524 - doe / 146096) / 365;
2125    let y = yoe as i64 + era * 400;
2126    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
2127    let mp = (5 * doy + 2) / 153;
2128    let d = (doy - (153 * mp + 2) / 5 + 1) as i64;
2129    let m = if mp < 10 { mp + 3 } else { mp - 9 } as i64;
2130    let y = if m <= 2 { y + 1 } else { y };
2131    let dow = ((days + 4) % 7) as i64;
2132
2133    (y, m, d, hour, minute, second, dow)
2134}
2135
2136// =============================================================================
2137// Logging helpers for VM
2138// =============================================================================
2139
2140pub(crate) static VM_MIN_LOG_LEVEL: AtomicU8 = AtomicU8::new(0);
2141
2142#[derive(Clone)]
2143pub(crate) struct VmTraceContext {
2144    pub(crate) trace_id: String,
2145    pub(crate) span_id: String,
2146}
2147
2148thread_local! {
2149    pub(crate) static VM_TRACE_STACK: std::cell::RefCell<Vec<VmTraceContext>> = const { std::cell::RefCell::new(Vec::new()) };
2150}
2151
2152fn vm_level_to_u8(level: &str) -> Option<u8> {
2153    match level {
2154        "debug" => Some(0),
2155        "info" => Some(1),
2156        "warn" => Some(2),
2157        "error" => Some(3),
2158        _ => None,
2159    }
2160}
2161
2162fn vm_format_timestamp_utc() -> String {
2163    let now = std::time::SystemTime::now()
2164        .duration_since(std::time::UNIX_EPOCH)
2165        .unwrap_or_default();
2166    let total_secs = now.as_secs();
2167    let millis = now.subsec_millis();
2168
2169    let days = total_secs / 86400;
2170    let time_of_day = total_secs % 86400;
2171    let hour = time_of_day / 3600;
2172    let minute = (time_of_day % 3600) / 60;
2173    let second = time_of_day % 60;
2174
2175    let z = days as i64 + 719468;
2176    let era = if z >= 0 { z } else { z - 146096 } / 146097;
2177    let doe = (z - era * 146097) as u64;
2178    let yoe = (doe - doe / 1460 + doe / 36524 - doe / 146096) / 365;
2179    let y = yoe as i64 + era * 400;
2180    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
2181    let mp = (5 * doy + 2) / 153;
2182    let d = doy - (153 * mp + 2) / 5 + 1;
2183    let m = if mp < 10 { mp + 3 } else { mp - 9 };
2184    let y = if m <= 2 { y + 1 } else { y };
2185
2186    format!("{y:04}-{m:02}-{d:02}T{hour:02}:{minute:02}:{second:02}.{millis:03}Z")
2187}
2188
2189pub(crate) fn vm_escape_json_str(s: &str) -> String {
2190    let mut out = String::with_capacity(s.len());
2191    for ch in s.chars() {
2192        match ch {
2193            '"' => out.push_str("\\\""),
2194            '\\' => out.push_str("\\\\"),
2195            '\n' => out.push_str("\\n"),
2196            '\r' => out.push_str("\\r"),
2197            '\t' => out.push_str("\\t"),
2198            c if c.is_control() => {
2199                out.push_str(&format!("\\u{:04x}", c as u32));
2200            }
2201            c => out.push(c),
2202        }
2203    }
2204    out
2205}
2206
2207fn vm_escape_json_str_quoted(s: &str) -> String {
2208    let mut out = String::with_capacity(s.len() + 2);
2209    out.push('"');
2210    out.push_str(&vm_escape_json_str(s));
2211    out.push('"');
2212    out
2213}
2214
2215fn vm_value_to_json_fragment(val: &VmValue) -> String {
2216    match val {
2217        VmValue::String(s) => vm_escape_json_str_quoted(s),
2218        VmValue::Int(n) => n.to_string(),
2219        VmValue::Float(n) => {
2220            if n.is_finite() {
2221                n.to_string()
2222            } else {
2223                "null".to_string()
2224            }
2225        }
2226        VmValue::Bool(b) => b.to_string(),
2227        VmValue::Nil => "null".to_string(),
2228        _ => vm_escape_json_str_quoted(&val.display()),
2229    }
2230}
2231
2232fn vm_build_log_line(level: &str, msg: &str, fields: Option<&BTreeMap<String, VmValue>>) -> String {
2233    let ts = vm_format_timestamp_utc();
2234    let mut parts: Vec<String> = Vec::new();
2235    parts.push(format!("\"ts\":{}", vm_escape_json_str_quoted(&ts)));
2236    parts.push(format!("\"level\":{}", vm_escape_json_str_quoted(level)));
2237    parts.push(format!("\"msg\":{}", vm_escape_json_str_quoted(msg)));
2238
2239    VM_TRACE_STACK.with(|stack| {
2240        if let Some(trace) = stack.borrow().last() {
2241            parts.push(format!(
2242                "\"trace_id\":{}",
2243                vm_escape_json_str_quoted(&trace.trace_id)
2244            ));
2245            parts.push(format!(
2246                "\"span_id\":{}",
2247                vm_escape_json_str_quoted(&trace.span_id)
2248            ));
2249        }
2250    });
2251
2252    if let Some(dict) = fields {
2253        for (k, v) in dict {
2254            parts.push(format!(
2255                "{}:{}",
2256                vm_escape_json_str_quoted(k),
2257                vm_value_to_json_fragment(v)
2258            ));
2259        }
2260    }
2261
2262    format!("{{{}}}\n", parts.join(","))
2263}
2264
2265fn vm_write_log(level: &str, level_num: u8, args: &[VmValue], out: &mut String) {
2266    if level_num < VM_MIN_LOG_LEVEL.load(Ordering::Relaxed) {
2267        return;
2268    }
2269    let msg = args.first().map(|a| a.display()).unwrap_or_default();
2270    let fields = args.get(1).and_then(|v| {
2271        if let VmValue::Dict(d) = v {
2272            Some(&**d)
2273        } else {
2274            None
2275        }
2276    });
2277    let line = vm_build_log_line(level, &msg, fields);
2278    out.push_str(&line);
2279}
2280
2281// =============================================================================
2282// Tool registry helpers for VM
2283// =============================================================================
2284
2285fn vm_validate_registry(name: &str, dict: &BTreeMap<String, VmValue>) -> Result<(), VmError> {
2286    match dict.get("_type") {
2287        Some(VmValue::String(t)) if &**t == "tool_registry" => Ok(()),
2288        _ => Err(VmError::Thrown(VmValue::String(Rc::from(format!(
2289            "{name}: argument must be a tool registry (created with tool_registry())"
2290        ))))),
2291    }
2292}
2293
2294fn vm_get_tools(dict: &BTreeMap<String, VmValue>) -> &[VmValue] {
2295    match dict.get("tools") {
2296        Some(VmValue::List(list)) => list,
2297        _ => &[],
2298    }
2299}
2300
2301fn vm_format_parameters(params: Option<&VmValue>) -> String {
2302    match params {
2303        Some(VmValue::Dict(map)) if !map.is_empty() => {
2304            let mut pairs: Vec<(String, String)> =
2305                map.iter().map(|(k, v)| (k.clone(), v.display())).collect();
2306            pairs.sort_by(|a, b| a.0.cmp(&b.0));
2307            pairs
2308                .iter()
2309                .map(|(k, v)| format!("{k}: {v}"))
2310                .collect::<Vec<_>>()
2311                .join(", ")
2312        }
2313        _ => String::new(),
2314    }
2315}
2316
2317fn vm_build_empty_schema() -> BTreeMap<String, VmValue> {
2318    let mut schema = BTreeMap::new();
2319    schema.insert(
2320        "schema_version".to_string(),
2321        VmValue::String(Rc::from("harn-tools/1.0")),
2322    );
2323    schema.insert("tools".to_string(), VmValue::List(Rc::new(Vec::new())));
2324    schema
2325}
2326
2327fn vm_build_input_schema(
2328    params: Option<&VmValue>,
2329    components: Option<&BTreeMap<String, VmValue>>,
2330) -> VmValue {
2331    let mut schema = BTreeMap::new();
2332    schema.insert("type".to_string(), VmValue::String(Rc::from("object")));
2333
2334    let params_map = match params {
2335        Some(VmValue::Dict(map)) if !map.is_empty() => map,
2336        _ => {
2337            schema.insert(
2338                "properties".to_string(),
2339                VmValue::Dict(Rc::new(BTreeMap::new())),
2340            );
2341            return VmValue::Dict(Rc::new(schema));
2342        }
2343    };
2344
2345    let mut properties = BTreeMap::new();
2346    let mut required = Vec::new();
2347
2348    for (key, val) in params_map.iter() {
2349        let prop = vm_resolve_param_type(val, components);
2350        properties.insert(key.clone(), prop);
2351        required.push(VmValue::String(Rc::from(key.as_str())));
2352    }
2353
2354    schema.insert("properties".to_string(), VmValue::Dict(Rc::new(properties)));
2355    if !required.is_empty() {
2356        required.sort_by_key(|a| a.display());
2357        schema.insert("required".to_string(), VmValue::List(Rc::new(required)));
2358    }
2359
2360    VmValue::Dict(Rc::new(schema))
2361}
2362
2363fn vm_resolve_param_type(val: &VmValue, components: Option<&BTreeMap<String, VmValue>>) -> VmValue {
2364    match val {
2365        VmValue::String(type_name) => {
2366            let json_type = vm_harn_type_to_json_schema(type_name);
2367            let mut prop = BTreeMap::new();
2368            prop.insert("type".to_string(), VmValue::String(Rc::from(json_type)));
2369            VmValue::Dict(Rc::new(prop))
2370        }
2371        VmValue::Dict(map) => {
2372            if let Some(VmValue::String(ref_name)) = map.get("$ref") {
2373                if let Some(comps) = components {
2374                    if let Some(resolved) = comps.get(&**ref_name) {
2375                        return resolved.clone();
2376                    }
2377                }
2378                let mut prop = BTreeMap::new();
2379                prop.insert(
2380                    "$ref".to_string(),
2381                    VmValue::String(Rc::from(
2382                        format!("#/components/schemas/{ref_name}").as_str(),
2383                    )),
2384                );
2385                VmValue::Dict(Rc::new(prop))
2386            } else {
2387                VmValue::Dict(Rc::new((**map).clone()))
2388            }
2389        }
2390        _ => {
2391            let mut prop = BTreeMap::new();
2392            prop.insert("type".to_string(), VmValue::String(Rc::from("string")));
2393            VmValue::Dict(Rc::new(prop))
2394        }
2395    }
2396}
2397
2398fn vm_harn_type_to_json_schema(harn_type: &str) -> &str {
2399    match harn_type {
2400        "int" => "integer",
2401        "float" => "number",
2402        "bool" | "boolean" => "boolean",
2403        "list" | "array" => "array",
2404        "dict" | "object" => "object",
2405        _ => "string",
2406    }
2407}