use std::{
collections::{BTreeMap, BTreeSet},
fmt,
path::PathBuf,
process::Stdio,
sync::Arc,
time::Duration,
};
use nachalnik::{
BoxError, Budget, Capability, CompactionPlan, Compactor, ContextItem, ContextKind, OutputSink,
PermissionPolicy, PermissionRequest, Tool, ToolCall, ToolCallId, ToolOutput, ToolSpec, Verdict,
async_trait,
};
use parking_lot::Mutex;
use crate::sandbox::{Reach, Sandbox};
use serde_json::{Value, json};
use tokio::io::{AsyncBufReadExt, AsyncReadExt, BufReader};
const HEARTBEAT: Duration = Duration::from_millis(120);
fn arg<'a>(args: &'a Value, name: &str) -> Result<&'a str, BoxError> {
args[name]
.as_str()
.ok_or_else(|| format!("the `{name}` argument is required").into())
}
pub fn builtin(shell: Shell, reach: Reach) -> Vec<Arc<dyn Tool>> {
let reach = Arc::new(reach);
vec![
Arc::new(Read(reach.clone())),
Arc::new(Write(reach.clone())),
Arc::new(Edit(reach)),
Arc::new(shell),
]
}
struct Read(Arc<Reach>);
#[async_trait]
impl Tool for Read {
fn spec(&self) -> ToolSpec {
ToolSpec::new("read", "reads a file and returns its contents")
.with_schema(json!({
"type": "object",
"properties": { "path": { "type": "string" } },
"required": ["path"],
}))
.with_capabilities([Capability::Read])
.with_output_limit(32_000)
}
async fn invoke(&self, call: &ToolCall, _output: OutputSink) -> Result<ToolOutput, BoxError> {
let path = match self.0.allows(arg(&call.args, "path")?) {
Ok(path) => path,
Err(refusal) => return Ok(ToolOutput::error(refusal)),
};
match tokio::fs::read_to_string(&path).await {
Ok(content) => Ok(ToolOutput::new(content)),
Err(e) => Ok(ToolOutput::error(format!("{}: {e}", path.display()))),
}
}
}
struct Write(Arc<Reach>);
#[async_trait]
impl Tool for Write {
fn spec(&self) -> ToolSpec {
ToolSpec::new("write", "creates or replaces a file")
.with_schema(json!({
"type": "object",
"properties": {
"path": { "type": "string" },
"content": { "type": "string" },
},
"required": ["path", "content"],
}))
.with_capabilities([Capability::Write])
}
async fn invoke(&self, call: &ToolCall, _output: OutputSink) -> Result<ToolOutput, BoxError> {
let (path, content) = (arg(&call.args, "path")?, arg(&call.args, "content")?);
let path = match self.0.allows(path) {
Ok(path) => path,
Err(refusal) => return Ok(ToolOutput::error(refusal)),
};
match tokio::fs::write(&path, content).await {
Ok(()) => Ok(ToolOutput::new(format!(
"wrote {} bytes to {}",
content.len(),
path.display()
))),
Err(e) => Ok(ToolOutput::error(format!("{}: {e}", path.display()))),
}
}
}
struct Edit(Arc<Reach>);
#[async_trait]
impl Tool for Edit {
fn spec(&self) -> ToolSpec {
ToolSpec::new(
"edit",
"replaces the first occurrence of `old` with `new` in a file",
)
.with_schema(json!({
"type": "object",
"properties": {
"path": { "type": "string" },
"old": { "type": "string" },
"new": { "type": "string" },
},
"required": ["path", "old", "new"],
}))
.with_capabilities([Capability::Edit])
}
async fn invoke(&self, call: &ToolCall, _output: OutputSink) -> Result<ToolOutput, BoxError> {
let (old, new) = (arg(&call.args, "old")?, arg(&call.args, "new")?);
let path = match self.0.allows(arg(&call.args, "path")?) {
Ok(path) => path,
Err(refusal) => return Ok(ToolOutput::error(refusal)),
};
let before = match tokio::fs::read_to_string(&path).await {
Ok(before) => before,
Err(e) => return Ok(ToolOutput::error(format!("{}: {e}", path.display()))),
};
let Some(at) = before.find(old) else {
return Ok(ToolOutput::error(format!(
"`old` does not occur in {}",
path.display()
)));
};
let after = format!("{}{new}{}", &before[..at], &before[at + old.len()..]);
match tokio::fs::write(&path, after).await {
Ok(()) => Ok(ToolOutput::new(format!(
"replaced one occurrence in {}",
path.display()
))),
Err(e) => Ok(ToolOutput::error(format!("{}: {e}", path.display()))),
}
}
}
pub struct Shell {
pub policy: Arc<Careful>,
pub workdir: PathBuf,
pub extra: Vec<PathBuf>,
pub confiner: Option<PathBuf>,
}
#[async_trait]
impl Tool for Shell {
fn spec(&self) -> ToolSpec {
ToolSpec::new(
"shell",
"runs a command with `sh -c` and returns its output",
)
.with_schema(json!({
"type": "object",
"properties": { "cmd": { "type": "string" } },
"required": ["cmd"],
}))
.with_capabilities([Capability::Shell])
.with_output_limit(32_000)
}
async fn invoke(&self, call: &ToolCall, output: OutputSink) -> Result<ToolOutput, BoxError> {
let cmd = arg(&call.args, "cmd")?;
let mut command = match &self.confiner {
Some(me) => {
let sandbox = Sandbox::of(
&self.policy,
self.workdir.clone(),
self.extra.clone(),
self.policy.was_granted_the_network(&call.id),
);
let mut command = tokio::process::Command::new(me);
command.args(sandbox.argv(cmd));
command
}
None => {
let mut command = tokio::process::Command::new("sh");
command.arg("-c").arg(cmd).current_dir(&self.workdir);
command
}
};
#[cfg(unix)]
command.process_group(0);
let mut child = match command
.stdin(Stdio::null())
.stdout(Stdio::piped())
.stderr(Stdio::piped())
.spawn()
{
Ok(child) => child,
Err(e) => return Ok(ToolOutput::error(format!("could not run `{cmd}`: {e}"))),
};
let scratch = self
.confiner
.is_some()
.then(|| child.id().map(crate::sandbox::scratch_for))
.flatten();
let stdout = child.stdout.take().expect("stdout was piped");
let stderr = child.stderr.take().expect("stderr was piped");
let mut collecting_stderr = tokio::spawn(async move {
let mut collected = String::new();
let _ = BufReader::new(stderr).read_to_string(&mut collected).await;
collected
});
let mut lines = BufReader::new(stdout).lines();
let mut collected = String::new();
let mut interrupted = false;
loop {
match tokio::time::timeout(HEARTBEAT, lines.next_line()).await {
Ok(Ok(Some(line))) => {
output.push(format!("{line}\n"));
collected.push_str(&line);
collected.push('\n');
}
Ok(Ok(None)) => break,
Ok(Err(e)) => {
collected.push_str(&format!("\n[could not read the output: {e}]\n"));
break;
}
Err(_) => {}
}
if output.is_interrupted() {
stop(&mut child).await;
interrupted = true;
break;
}
}
let errors = match interrupted {
true => match tokio::time::timeout(HEARTBEAT, &mut collecting_stderr).await {
Ok(collected) => collected.unwrap_or_default(),
Err(_) => {
collecting_stderr.abort();
String::new()
}
},
false => collecting_stderr.await.unwrap_or_default(),
};
let status = match child.wait().await {
Ok(status) => status.to_string(),
Err(e) => format!("unknown ({e})"),
};
if let Some(scratch) = scratch {
let _ = tokio::fs::remove_dir_all(scratch).await;
}
let text = format!(
"exit: {status}\n--- stdout ---\n{collected}\n--- stderr ---\n{errors}{}",
match interrupted {
true => "\n\n[the command was stopped before it finished]",
false => "",
}
);
Ok(ToolOutput::new(text))
}
}
#[cfg(unix)]
async fn stop(child: &mut tokio::process::Child) {
if let Some(pid) = child.id() {
let _ = tokio::process::Command::new("sh")
.arg("-c")
.arg(format!("kill -KILL -{pid}"))
.stdin(Stdio::null())
.stdout(Stdio::null())
.stderr(Stdio::null())
.status()
.await;
}
let _ = child.start_kill();
}
#[cfg(not(unix))]
async fn stop(child: &mut tokio::process::Child) {
let _ = child.start_kill();
}
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
pub enum Subject {
Capability(Capability),
Path(String),
}
impl fmt::Display for Subject {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Capability(capability) => write!(f, "{capability}"),
Self::Path(pattern) => write!(f, "{pattern}"),
}
}
}
const SUSPECT: &[&str] = &[
".env*",
"*.pem",
"*.key",
"*.p12",
"id_rsa*",
"id_ed25519*",
"*credentials*",
"secrets/",
".ssh/",
".aws/",
".gnupg/",
];
pub fn path_matches(pattern: &str, path: &str) -> bool {
let path = path.replace('\\', "/");
if let Some(directory) = pattern.strip_suffix('/') {
return path.split('/').any(|part| part == directory);
}
let name = path.rsplit('/').next().unwrap_or(&path);
let mut rest = name;
let mut parts = pattern.split('*');
let Some(first) = parts.next() else {
return false;
};
let Some(after) = rest.strip_prefix(first) else {
return false;
};
rest = after;
let mut last = None;
for part in parts {
last = Some(part);
if part.is_empty() {
continue;
}
match rest.find(part) {
Some(at) => rest = &rest[at + part.len()..],
None => return false,
}
}
match last {
None => rest.is_empty(),
Some(part) => part.is_empty() || rest.is_empty(),
}
}
pub struct Careful {
stances: Mutex<BTreeMap<Capability, Verdict>>,
paths: Mutex<Vec<(String, Verdict)>>,
networked: Mutex<BTreeSet<ToolCallId>>,
refusals: Mutex<BTreeMap<ToolCallId, String>>,
}
impl Default for Careful {
fn default() -> Self {
Self::new()
}
}
impl Careful {
pub fn new() -> Self {
Self {
stances: Mutex::new(BTreeMap::new()),
paths: Mutex::new(
SUSPECT
.iter()
.map(|pattern| ((*pattern).to_owned(), Verdict::Ask))
.collect(),
),
networked: Mutex::new(BTreeSet::new()),
refusals: Mutex::new(BTreeMap::new()),
}
}
pub fn judges(&self, request: &PermissionRequest) -> Vec<Subject> {
let mut judged: Vec<Subject> = request
.capabilities
.iter()
.cloned()
.map(Subject::Capability)
.collect();
if request.capabilities.contains(&Capability::Shell)
&& command(&request.args).is_some_and(reaches_the_network)
{
judged.push(Subject::Capability(Capability::Network));
}
if let Some(path) = request.args.get("path").and_then(|path| path.as_str()) {
judged.extend(
self.paths
.lock()
.iter()
.filter(|(pattern, _)| path_matches(pattern, path))
.map(|(pattern, _)| Subject::Path(pattern.clone())),
);
}
judged
}
pub fn verdict(&self, request: &PermissionRequest) -> Verdict {
self.judges(request)
.iter()
.map(|subject| self.stance(subject))
.fold(Verdict::Allow, Verdict::strictest)
}
pub fn stance(&self, subject: &Subject) -> Verdict {
match subject {
Subject::Capability(capability) => self
.stances
.lock()
.get(capability)
.copied()
.unwrap_or(Verdict::Ask),
Subject::Path(pattern) => self
.paths
.lock()
.iter()
.find(|(known, _)| known == pattern)
.map(|(_, verdict)| *verdict)
.unwrap_or(Verdict::Ask),
}
}
pub fn set(&self, subject: &Subject, verdict: Verdict) {
match subject {
Subject::Capability(capability) => {
self.stances.lock().insert(capability.clone(), verdict);
}
Subject::Path(pattern) => {
let mut paths = self.paths.lock();
match paths.iter_mut().find(|(known, _)| known == pattern) {
Some(rule) => rule.1 = verdict,
None => paths.push((pattern.clone(), verdict)),
}
}
}
}
pub fn cycle(&self, subject: &Subject) -> Verdict {
let next = match self.stance(subject) {
Verdict::Ask => Verdict::Allow,
Verdict::Allow => Verdict::Deny,
Verdict::Deny => Verdict::Ask,
};
self.set(subject, next);
next
}
pub fn always(&self, subjects: &[Subject]) {
for subject in subjects {
self.set(subject, Verdict::Allow);
}
}
pub fn grant_the_network(&self, call: &ToolCallId) {
let mut networked = self.networked.lock();
if networked.len() > 32 {
networked.clear();
}
networked.insert(call.clone());
}
pub fn was_granted_the_network(&self, call: &ToolCallId) -> bool {
self.networked.lock().contains(call)
}
pub fn why(&self, call: &ToolCallId) -> Option<String> {
self.refusals.lock().remove(call)
}
pub fn paths(&self) -> Vec<(String, Verdict)> {
self.paths.lock().clone()
}
pub fn stances(&self) -> Vec<(Capability, Verdict)> {
self.stances
.lock()
.iter()
.map(|(capability, verdict)| (capability.clone(), *verdict))
.collect()
}
}
#[async_trait]
impl PermissionPolicy for Careful {
async fn evaluate(&self, request: &PermissionRequest) -> Verdict {
let verdict = self.verdict(request);
if verdict == Verdict::Deny {
let blamed: Vec<String> = self
.judges(request)
.iter()
.filter(|subject| self.stance(subject) == Verdict::Deny)
.map(|subject| match subject {
Subject::Capability(Capability::Network) => {
"`network`, which this command reaches for".to_owned()
}
Subject::Path(pattern) => format!("the rule for `{pattern}`"),
subject => format!("`{subject}`"),
})
.collect();
let mut refusals = self.refusals.lock();
if refusals.len() > 32 {
refusals.clear();
}
refusals.insert(
request.call.clone(),
match blamed.is_empty() {
true => "the policy refused it".to_owned(),
false => format!("refused by {}", blamed.join(" and ")),
},
);
}
verdict
}
}
fn command(args: &serde_json::Value) -> Option<&str> {
args.get("cmd")?.as_str()
}
const NETWORKED: &[&str] = &[
"curl",
"wget",
"aria2c",
"http",
"https",
"xh",
"httpie",
"nc",
"ncat",
"netcat",
"telnet",
"ssh",
"scp",
"sftp",
"rsync",
"ftp",
"ping",
"dig",
"nslookup",
"host",
"whois",
"git",
"gh",
"cargo",
"npm",
"pnpm",
"yarn",
"npx",
"pip",
"pip3",
"uv",
"poetry",
"gem",
"go",
"brew",
"apt",
"apt-get",
"dnf",
"pacman",
"apk",
"docker",
"podman",
"kubectl",
"helm",
"aws",
"gcloud",
"az",
"terraform",
];
pub fn reaches_the_network(cmd: &str) -> bool {
cmd.split([';', '|', '&', '\n', '(', ')', '`'])
.filter_map(|segment| {
segment.split_whitespace().find(|word| !word.contains('='))
})
.any(|program| {
let program = program.trim_matches(['"', '\'']);
let program = program.rsplit('/').next().unwrap_or(program);
NETWORKED.contains(&program)
})
}
pub struct Trim {
pub threshold: f64,
pub target: f64,
}
#[async_trait]
impl Compactor for Trim {
fn should_compact(&self, budget: &Budget) -> bool {
budget
.fraction_used()
.is_some_and(|used| used >= self.threshold)
}
async fn plan(&self, items: &[Arc<ContextItem>], budget: &Budget) -> Option<CompactionPlan> {
let target = (budget.limit? as f64 * self.target) as usize;
let candidates = items.iter().filter(|item| {
item.is_projected() && matches!(item.kind, ContextKind::ToolResult { .. })
});
let mut used = budget.used();
let mut elide = Vec::new();
for item in candidates {
if used <= target {
break;
}
used -= item.tokens.min(used);
elide.push(item.id);
}
if elide.is_empty() {
return None;
}
Some(CompactionPlan {
summary: Some(ContextItem::summary(format!(
"{} earlier tool result(s) in this conversation have been shortened to a marker \
to make room. Ask for anything you still need.",
elide.len()
))),
reason: format!(
"compacted to make room; the context had reached {}% of the {}-token limit",
(budget.fraction_used().unwrap_or_default() * 100.0).round() as usize,
budget.limit.unwrap_or_default(),
),
elide,
remove: Vec::new(),
})
}
}