use crate::agents::{
definition::{
AgentDefinition, MAX_AGENT_CATALOG_BYTES, MAX_AGENT_FILE_BYTES, MAX_DISCOVERED_AGENTS,
},
markdown::{MarkdownFlavor, parse_markdown},
toml::parse_toml,
};
use anyhow::{Context, Result, bail};
use std::{
collections::{BTreeMap, BTreeSet, btree_map::Entry},
fs,
io::Read,
path::{Path, PathBuf},
sync::Arc,
};
const MAX_SCAN_DEPTH: usize = 8;
const MAX_SCAN_ENTRIES: usize = 4096;
#[derive(Clone)]
pub(crate) struct AgentRegistry {
workspace: PathBuf,
agents: BTreeMap<String, Arc<AgentDefinition>>,
}
impl AgentRegistry {
pub(crate) fn discover(workspace: impl AsRef<Path>) -> Result<Self> {
let workspace = fs::canonicalize(workspace.as_ref()).context("canonicalizing workspace")?;
if !workspace.is_dir() {
bail!("workspace must be a directory")
}
let specs = [
(".agents/agents", MarkdownFlavor::Canonical, true),
(".claude/agents", MarkdownFlavor::Claude, false),
];
let mut candidates = Vec::new();
for (precedence, (relative, markdown, canonical_toml)) in specs.into_iter().enumerate() {
collect(
&workspace.join(relative),
&workspace,
markdown,
canonical_toml,
precedence as u8,
&mut candidates,
)?;
}
candidates.sort_by(|a, b| a.0.cmp(&b.0).then_with(|| a.1.cmp(&b.1)));
let mut paths = BTreeSet::new();
let mut agents = BTreeMap::new();
let mut warned = BTreeSet::new();
for (_, path, flavor) in candidates {
if !paths.insert(path.clone()) {
continue;
}
let input = match read_agent_file(&path) {
Ok(value) => value,
Err(error) => {
tracing::warn!(path=%path.display(), %error, "cannot read agent");
continue;
}
};
let parsed = match flavor {
Some(flavor) => parse_markdown(path.clone(), &input, flavor),
None => parse_toml(path.clone(), &input),
};
match parsed {
Ok(agent) => {
let name = agent.name.clone();
match agents.entry(name) {
Entry::Occupied(entry) => {
if warned.insert(entry.key().clone()) {
tracing::warn!(name=%entry.key(), "agent name collision; retaining higher-precedence definition");
}
}
Entry::Vacant(entry) => {
entry.insert(Arc::new(agent));
}
}
}
Err(error) => {
tracing::warn!(path=%path.display(), %error, "ignoring malformed agent")
}
}
}
if agents.len() > MAX_DISCOVERED_AGENTS {
bail!(
"discovered agent count {} exceeds the limit of {MAX_DISCOVERED_AGENTS}",
agents.len()
);
}
let catalog_bytes = agents
.values()
.map(|agent| 5 + agent.name.len() + agent.description.len())
.sum::<usize>()
.saturating_sub(1);
if catalog_bytes > MAX_AGENT_CATALOG_BYTES {
bail!("agent catalog exceeds the {MAX_AGENT_CATALOG_BYTES}-byte limit");
}
Ok(Self { workspace, agents })
}
pub(crate) fn names(&self) -> Vec<String> {
self.agents.keys().cloned().collect()
}
pub(crate) fn catalog(&self) -> Vec<Arc<AgentDefinition>> {
self.agents.values().cloned().collect()
}
pub(crate) fn get(&self, name: &str) -> Option<Arc<AgentDefinition>> {
self.agents.get(name).cloned()
}
pub(crate) fn is_empty(&self) -> bool {
self.agents.is_empty()
}
pub(crate) fn workspace(&self) -> &Path {
&self.workspace
}
}
fn read_agent_file(path: &Path) -> Result<String> {
let file = fs::File::open(path)?;
if file.metadata()?.len() > MAX_AGENT_FILE_BYTES as u64 {
bail!("agent file exceeds the 1 MiB limit")
}
let mut bytes = Vec::with_capacity(MAX_AGENT_FILE_BYTES.min(64 * 1024));
file.take((MAX_AGENT_FILE_BYTES + 1) as u64)
.read_to_end(&mut bytes)?;
if bytes.len() > MAX_AGENT_FILE_BYTES {
bail!("agent file exceeds the 1 MiB limit")
}
String::from_utf8(bytes).context("agent file is not valid UTF-8")
}
fn collect(
root: &Path,
workspace: &Path,
markdown: MarkdownFlavor,
canonical_toml: bool,
precedence: u8,
out: &mut Vec<(u8, PathBuf, Option<MarkdownFlavor>)>,
) -> Result<()> {
let root = match fs::canonicalize(root) {
Ok(root) => root,
Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(()),
Err(error) => return Err(error).context("canonicalizing agent root"),
};
if !root.is_dir() || !root.starts_with(workspace) {
return Ok(());
}
let mut visited = BTreeSet::new();
ScanContext {
root: &root,
workspace,
markdown,
canonical_toml,
precedence,
visited: &mut visited,
scanned: 0,
out,
}
.collect_dir(&root, 0)
}
struct ScanContext<'a> {
root: &'a Path,
workspace: &'a Path,
markdown: MarkdownFlavor,
canonical_toml: bool,
precedence: u8,
visited: &'a mut BTreeSet<PathBuf>,
scanned: usize,
out: &'a mut Vec<(u8, PathBuf, Option<MarkdownFlavor>)>,
}
impl ScanContext<'_> {
fn collect_dir(&mut self, dir: &Path, depth: usize) -> Result<()> {
let dir = fs::canonicalize(dir)
.with_context(|| format!("canonicalizing agent directory {}", dir.display()))?;
if !dir.starts_with(self.workspace)
|| !dir.starts_with(self.root)
|| !self.visited.insert(dir.clone())
{
return Ok(());
}
let entries = fs::read_dir(&dir)
.with_context(|| format!("reading agent directory {}", dir.display()))?;
let mut paths = Vec::new();
for entry in entries {
self.scanned = self.scanned.saturating_add(1);
if self.scanned > MAX_SCAN_ENTRIES {
bail!("agent discovery exceeds the {MAX_SCAN_ENTRIES}-entry scan limit")
}
paths.push(
entry
.with_context(|| format!("reading agent directory {}", dir.display()))?
.path(),
);
}
paths.sort();
for path in paths {
let target = match fs::canonicalize(&path) {
Ok(target) => target,
Err(error) if error.kind() == std::io::ErrorKind::NotFound => continue,
Err(error) => {
return Err(error)
.with_context(|| format!("canonicalizing agent path {}", path.display()));
}
};
if !target.starts_with(self.workspace) || !target.starts_with(self.root) {
continue;
}
let metadata = fs::metadata(&target)
.with_context(|| format!("inspecting agent path {}", target.display()))?;
if metadata.is_dir() {
if depth < MAX_SCAN_DEPTH {
self.collect_dir(&target, depth + 1)?;
}
} else if metadata.is_file() {
match target.extension().and_then(|value| value.to_str()) {
Some("toml") if self.canonical_toml => {
if self.out.len() == MAX_DISCOVERED_AGENTS {
bail!(
"agent candidate count exceeds the limit of {MAX_DISCOVERED_AGENTS}"
)
}
self.out.push((self.precedence, target, None));
}
Some("md") => {
if self.out.len() == MAX_DISCOVERED_AGENTS {
bail!(
"agent candidate count exceeds the limit of {MAX_DISCOVERED_AGENTS}"
)
}
self.out
.push((self.precedence, target, Some(self.markdown)));
}
_ => {}
}
}
}
Ok(())
}
}
#[cfg(test)]
mod tests;