Files
marqdo/src/host/mod.rs
T
cflmyandCursor 1730f26fc7 release: v2.2.0 call one function in any .mq.md
The same page is the document, the knowledge and the program. marqdo call runs that function with arguments, so reuse, tools and tests do not need a second skill system.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-30 09:07:23 +08:00

308 lines
9.6 KiB
Rust

//! L0.5 host primitives for official stdlib (`lib/fs`, `time`, `math`, …).
//!
//! User docs should import L1 wrappers; these `host_*` names are the Rust surface.
//! Capabilities default **on** (importing a lib means you intend to use it).
//! Soft side-effects (no process::exit; sleep clamp) apply under view / capture only.
pub mod agent_rt;
pub mod collection;
mod dispatch;
mod cli;
mod csv;
mod datetime;
mod encoding;
pub mod event_bus;
#[cfg(feature = "exec-host")]
pub mod foreign;
#[cfg(feature = "exec-host")]
pub mod foreign_doc;
#[cfg(feature = "exec-host")]
pub mod foreign_session;
mod fs;
mod hash;
mod html_ops;
pub(crate) mod json;
mod log;
pub mod math;
mod net;
mod path;
mod re;
mod secrets;
mod stats;
mod text_ops;
mod time;
pub(crate) mod toml_ops;
mod url_ops;
mod uuid_ops;
#[cfg(feature = "plugin-host")]
pub mod plugin;
#[cfg(not(feature = "plugin-host"))]
#[path = "plugin_stub.rs"]
pub mod plugin;
#[cfg(feature = "exec-host")]
pub mod subtask;
#[cfg(not(feature = "exec-host"))]
#[path = "subtask_stub.rs"]
pub mod subtask;
pub mod sandbox_fs;
mod sys;
pub mod writeback;
pub use dispatch::{call_host, HostFn};
/// Shared `text` argument extraction for host modules.
///
/// `<TAB>` slimming: this used to be copy-pasted in 17 host modules with two
/// different wordings; one implementation keeps messages consistent.
pub fn as_text<'a>(v: &'a crate::value::Value, label: &str) -> Result<&'a str, String> {
match v {
crate::value::Value::Text(s) => Ok(s.as_str()),
_ => Err(format!("{label} needs text")),
}
}
pub use fs::path_under_root;
pub use plugin::PluginState;
use std::collections::HashMap;
use std::path::{Path, PathBuf};
/// Host capability flags. Default: all enabled.
#[derive(Debug, Clone, Copy)]
pub struct HostCaps {
pub fs_write: bool,
pub exec: bool,
pub net: bool,
pub plugin: bool,
}
impl Default for HostCaps {
fn default() -> Self {
Self {
fs_write: true,
exec: true,
net: true,
plugin: true,
}
}
}
/// SVG plot produced during a run (for CLI auto-write / view embed).
#[derive(Debug, Clone)]
pub struct PlotArtifact {
/// User-requested path, if any.
pub path: Option<String>,
pub svg: String,
}
#[derive(Debug)]
pub struct HostContext {
pub caps: HostCaps,
pub fs_root: Option<PathBuf>,
pub cwd: PathBuf,
pub argv: Vec<String>,
/// Soft mode: do not `process::exit`; honor sleep_limit (view / capture / export).
pub soft_side_effects: bool,
pub sleep_limit_ms: Option<u64>,
/// LCG state for `random` / `random_int`.
pub rng: u64,
pub plots: Vec<PlotArtifact>,
/// lang → interpreter argv (from `set_cmd`).
pub foreign_cmds: HashMap<String, Vec<String>>,
/// Process-local language registrations (`register` / `set_cmd`).
pub foreign_specs: HashMap<String, crate::foreign::registry::LangSpec>,
/// Project config specs (`.marqdo/foreign.toml`), lower priority than runtime.
pub foreign_config_specs: HashMap<String, crate::foreign::registry::LangSpec>,
/// Whether project config has been discovered/loaded.
pub foreign_config_loaded: bool,
/// Persistent foreign kernels (`session_open`).
#[cfg(feature = "exec-host")]
pub foreign_sessions: HashMap<String, foreign_session::Session>,
/// Monotonic session id counter.
#[cfg(feature = "exec-host")]
pub foreign_session_seq: u64,
/// Loaded native plugins (ABI v1/v2).
pub plugins: PluginState,
/// Entry `.mq.md` source text (for ABI host_query / context injection).
pub entry_source: Option<String>,
pub entry_path: Option<PathBuf>,
/// Active function names (outer → inner) for call-site injection.
pub call_stack: Vec<String>,
/// Last statement line (updated by interpreters for call-site queries).
pub current_line: u32,
/// Entry-file line of each active user call (for writeback anchoring).
pub call_site_lines: Vec<u32>,
/// Bound Artifact Metadata from the entry `.mq.md` (Phase 1 Binding).
pub entry_metadata: Vec<(String, crate::value::Value)>,
/// Concurrent subtasks (`lib/subtask`): file / function / foreign.
#[cfg_attr(not(feature = "exec-host"), allow(dead_code))]
pub(crate) subtasks: HashMap<u64, subtask::Handle>,
pub subtask_seq: u64,
/// Minimum log level (`lib/log`); default Info (20). See `host::log::Level`.
pub log_min_level: u8,
/// Active `ext/ai/sandbox` CoW session id (nested `sandbox_run`).
pub sandbox_session: Option<String>,
}
impl Default for HostContext {
fn default() -> Self {
Self {
caps: HostCaps::default(),
fs_root: None,
cwd: std::env::current_dir().unwrap_or_else(|_| PathBuf::from(".")),
argv: Vec::new(),
soft_side_effects: false,
sleep_limit_ms: Some(30_000),
rng: 0xC0FF_EE42_CAFE_BABE,
plots: Vec::new(),
foreign_cmds: HashMap::new(),
foreign_specs: HashMap::new(),
foreign_config_specs: HashMap::new(),
foreign_config_loaded: false,
#[cfg(feature = "exec-host")]
foreign_sessions: HashMap::new(),
#[cfg(feature = "exec-host")]
foreign_session_seq: 0,
plugins: PluginState::default(),
entry_source: None,
entry_path: None,
call_stack: Vec::new(),
current_line: 1,
call_site_lines: Vec::new(),
entry_metadata: Vec::new(),
subtasks: HashMap::new(),
subtask_seq: 0,
log_min_level: 20, // Info
sandbox_session: None,
}
}
}
impl Drop for HostContext {
fn drop(&mut self) {
subtask::kill_all(self);
#[cfg(feature = "exec-host")]
foreign_session::shutdown(self);
}
}
impl HostContext {
pub fn for_run(path: Option<&Path>, caps: HostCaps, argv: Vec<String>) -> Self {
let mut ctx = Self::default();
ctx.caps = caps;
ctx.argv = argv;
if let Some(p) = path {
if let Some(parent) = p.parent() {
let parent = if parent.as_os_str().is_empty() {
PathBuf::from(".")
} else {
parent.to_path_buf()
};
ctx.cwd = parent.clone();
ctx.fs_root = Some(parent);
}
}
ctx
}
/// Capture stdout / view / export: soft exit + sleep clamp; same caps as CLI by default.
pub fn for_capture(path: Option<&Path>, caps: HostCaps) -> Self {
let mut ctx = Self::for_run(path, caps, Vec::new());
ctx.soft_side_effects = true;
ctx.sleep_limit_ms = Some(0);
ctx
}
pub fn allow_fs_write(&self) -> bool {
self.caps.fs_write
}
pub fn allow_exec(&self) -> bool {
self.caps.exec
}
pub fn allow_net(&self) -> bool {
self.caps.net
}
pub fn push_call_site_line(&mut self, line: u32) {
self.call_site_lines.push(line);
}
pub fn pop_call_site_line(&mut self) {
self.call_site_lines.pop();
}
pub fn allow_plugin(&self) -> bool {
self.caps.plugin
}
pub fn next_u64(&mut self) -> u64 {
// SplitMix64-ish LCG step
self.rng = self
.rng
.wrapping_mul(6364136223846793005)
.wrapping_add(1);
let mut z = self.rng;
z = (z ^ (z >> 30)).wrapping_mul(0xbf58476d1ce4e5b9);
z = (z ^ (z >> 27)).wrapping_mul(0x94d049bb133111eb);
z ^ (z >> 31)
}
pub fn next_f64(&mut self) -> f64 {
let x = self.next_u64() >> 11;
(x as f64) / ((1u64 << 53) as f64)
}
pub fn resolve_path(&self, rel: &str) -> Result<PathBuf, String> {
let p = Path::new(rel);
let abs = if p.is_absolute() {
p.to_path_buf()
} else {
self.cwd.join(p)
};
if let Some(root) = &self.fs_root {
let root_canon = root.canonicalize().unwrap_or_else(|_| root.clone());
let check = abs.canonicalize().unwrap_or_else(|_| abs.clone());
if !path_under_root(&check, &root_canon) && !path_under_root(&abs, root) {
if let Some(parent) = abs.parent() {
let parent_ok = parent
.canonicalize()
.map(|p| path_under_root(&p, &root_canon))
.unwrap_or_else(|_| path_under_root(parent, root));
if !parent_ok {
return Err(format!("path escapes sandbox root: {}", abs.display()));
}
} else {
return Err(format!("path escapes sandbox root: {}", abs.display()));
}
}
}
Ok(abs)
}
}
/// Write auto-named plot files for CLI runs when `path` was omitted.
pub fn flush_auto_plots(source_path: Option<&Path>, plots: &[PlotArtifact]) -> Result<(), String> {
let mut auto_i = 0usize;
for plot in plots {
if plot.path.is_some() {
continue;
}
auto_i += 1;
let stem = source_path
.and_then(|p| p.file_stem())
.and_then(|s| s.to_str())
.unwrap_or("out");
let stem = stem.trim_end_matches(".mq");
let name = format!("{stem}-plot-{auto_i}.svg");
let dir = source_path
.and_then(|p| p.parent())
.unwrap_or_else(|| Path::new("."));
let dest = dir.join(&name);
std::fs::write(&dest, plot.svg.as_bytes())
.map_err(|e| format!("failed to write plot {}: {e}", dest.display()))?;
println!("plot: {}", dest.display());
}
Ok(())
}