1#![forbid(unsafe_code)]
2#![cfg_attr(test, allow(clippy::unwrap_used))]
3#![cfg_attr(
4 test,
5 allow(
6 clippy::disallowed_methods,
7 clippy::disallowed_types,
8 reason = "tests spawn, join and drain freely; production sites carry their own expectation"
9 )
10)]
11use std::{
12 collections::BTreeMap,
13 env, fmt, fs, io,
14 path::{Path, PathBuf},
15 str::FromStr,
16};
17
18use dekopon_core::{AgentId, IdentifierError};
19use dekopon_protocol::{Agent, ApiVersion};
20use serde::Deserialize;
21use serde_yaml::Value;
22use thiserror::Error;
23
24mod projection;
25pub mod skill;
26
27pub use projection::{Projection, ProjectionError};
28pub use skill::{Skill, SkillError, SkillResource, load_skill};
29
30pub const CONFIG_ENV: &str = "DEKOPON_CONFIG";
31pub const MAX_INSTRUCTIONS_BYTES: usize = 256 * 1024;
32
33#[derive(Clone, Debug)]
34pub struct LocalCatalog {
35 source: PathBuf,
36 agents: BTreeMap<AgentId, Agent>,
37 skills: BTreeMap<AgentId, Vec<Skill>>,
38 files: Vec<(PathBuf, String)>,
39}
40
41impl LocalCatalog {
42 pub fn load(path: impl AsRef<Path>) -> Result<Self, ConfigError> {
43 let path = path.as_ref();
44 let read = |file: &Path| {
45 fs::read_to_string(file).map_err(|source| ConfigError::Read {
46 path: file.display().to_string(),
47 source,
48 })
49 };
50 if !fs::metadata(path).is_ok_and(|metadata| metadata.is_dir()) {
51 return Self::from_str(path, &read(path)?);
52 }
53 let entries = fs::read_dir(path).map_err(|source| ConfigError::Read {
54 path: path.display().to_string(),
55 source,
56 })?;
57 let mut files = Vec::new();
58 for entry in entries {
59 let entry = entry.map_err(|source| ConfigError::Read {
60 path: path.display().to_string(),
61 source,
62 })?;
63 let file = entry.path();
64 if file
65 .extension()
66 .is_some_and(|extension| extension == "yaml")
67 {
68 files.push(file);
69 }
70 }
71 files.sort();
72 let sources = files
73 .iter()
74 .map(|file| Ok((file.clone(), read(file)?)))
75 .collect::<Result<Vec<_>, ConfigError>>()?;
76 Self::from_sources(path, sources)
77 }
78
79 pub fn from_str(source: impl AsRef<Path>, contents: &str) -> Result<Self, ConfigError> {
80 let source = source.as_ref();
81 Self::from_sources(source, vec![(source.to_path_buf(), contents.to_owned())])
82 }
83
84 #[expect(
85 clippy::wildcard_enum_match_arm,
86 reason = "reshaped by the unit that next rewrites this"
87 )]
88 fn from_sources(source: &Path, files: Vec<(PathBuf, String)>) -> Result<Self, ConfigError> {
89 let source = source.to_path_buf();
90 let source_name = source.display().to_string();
91 let many = files.len() > 1;
92 let mut resources = Vec::new();
93
94 for (file, contents) in &files {
95 let file_name = file
96 .file_name()
97 .map(|name| name.to_string_lossy().into_owned())
98 .unwrap_or_default();
99 let prefix = if many {
100 format!("{file_name} ")
101 } else {
102 String::new()
103 };
104 for (document_index, document) in
105 serde_yaml::Deserializer::from_str(contents).enumerate()
106 {
107 let document_number = document_index + 1;
108 let value = Value::deserialize(document).map_err(|error| {
109 let location = error.location().map_or_else(String::new, |location| {
110 format!(" at line {}, column {}", location.line(), location.column())
111 });
112 ConfigError::Parse {
113 path: file.display().to_string(),
114 origin: format!("document {document_number}{location}"),
115 source: error,
116 }
117 })?;
118
119 match value {
120 Value::Null => {}
121 Value::Sequence(items) => {
122 for (item_index, item) in items.into_iter().enumerate() {
123 resources.push((
124 format!(
125 "{prefix}document {document_number}, item {}",
126 item_index + 1
127 ),
128 item,
129 ));
130 }
131 }
132 other => resources.push((format!("{prefix}document {document_number}"), other)),
133 }
134 }
135 }
136
137 if resources.is_empty() {
138 return Err(ConfigError::Empty { path: source_name });
139 }
140
141 let mut agents = ResourceSet::<Agent>::default();
142 let mut problems = Vec::new();
143
144 for (origin, value) in resources {
145 let outcome = match string_field(&value, "kind").map(str::to_owned) {
146 Some(kind) => match kind.as_str() {
147 Agent::KIND => agents.insert(&origin, value),
148 _ => Err(CatalogProblem::UnsupportedKind { origin, kind }),
149 },
150 None => Err(CatalogProblem::MissingKind { origin }),
151 };
152 if let Err(problem) = outcome {
153 problems.push(problem);
154 }
155 }
156 let base = if many || source.is_dir() {
157 source.clone()
158 } else {
159 source.parent().map(Path::to_path_buf).unwrap_or_default()
160 };
161 let skills = load_agent_skills(&agents, &base, &mut problems);
162 let mut agents = agents.into_map();
163 for (id, agent) in &mut agents {
164 let Some(file) = agent.spec.instructions_file.clone() else {
165 continue;
166 };
167 if agent.spec.instructions.is_some() {
168 problems.push(CatalogProblem::InstructionsTwice {
169 agent: id.to_string(),
170 });
171 continue;
172 }
173 let resolved = if file.is_absolute() {
174 file.clone()
175 } else {
176 base.join(&file)
177 };
178 match fs::read_to_string(&resolved) {
180 Ok(text) if text.len() > MAX_INSTRUCTIONS_BYTES => {
181 problems.push(CatalogProblem::InstructionsTooLarge {
182 agent: id.to_string(),
183 length: text.len(),
184 maximum: MAX_INSTRUCTIONS_BYTES,
185 });
186 }
187 Ok(text) => agent.spec.instructions = Some(text),
188 Err(source) => problems.push(CatalogProblem::Instructions {
189 agent: id.to_string(),
190 path: file.display().to_string(),
191 source,
192 }),
193 }
194 }
195
196 if !problems.is_empty() {
197 return Err(ConfigError::Invalid {
198 path: source_name,
199 problems,
200 });
201 }
202
203 Ok(Self {
204 source,
205 agents,
206 skills,
207 files,
208 })
209 }
210
211 #[must_use]
212 pub fn source(&self) -> &Path {
213 &self.source
214 }
215
216 pub fn agents(&self) -> impl ExactSizeIterator<Item = &Agent> {
217 self.agents.values()
218 }
219
220 #[must_use]
221 pub fn agent(&self, id: &AgentId) -> Option<&Agent> {
222 self.agents.get(id)
223 }
224
225 #[must_use]
226 pub fn agent_skills(&self, id: &AgentId) -> &[Skill] {
227 self.skills.get(id).map_or(&[], Vec::as_slice)
228 }
229
230 #[must_use]
231 pub fn files(&self) -> &[(PathBuf, String)] {
232 &self.files
233 }
234}
235
236fn string_field<'a>(value: &'a Value, field: &str) -> Option<&'a str> {
237 value
238 .as_mapping()?
239 .get(Value::String(field.to_owned()))
240 .and_then(Value::as_str)
241}
242
243trait Resource: Sized + for<'de> Deserialize<'de> {
244 type Id: FromStr<Err = IdentifierError> + Ord + fmt::Display;
245
246 const KIND: &'static str;
247
248 fn name(&self) -> &str;
249}
250
251impl Resource for Agent {
252 type Id = AgentId;
253 const KIND: &'static str = "Agent";
254
255 fn name(&self) -> &str {
256 &self.metadata.name
257 }
258}
259
260struct ResourceSet<T: Resource> {
261 entries: BTreeMap<T::Id, (String, T)>,
262}
263
264impl<T: Resource> Default for ResourceSet<T> {
265 fn default() -> Self {
266 Self {
267 entries: BTreeMap::new(),
268 }
269 }
270}
271
272impl<T: Resource> ResourceSet<T> {
273 fn insert(&mut self, origin: &str, value: Value) -> Result<(), CatalogProblem> {
274 if let Some(version) = string_field(&value, "apiVersion")
275 && version != ApiVersion::V1Alpha1.to_string()
276 {
277 return Err(CatalogProblem::UnsupportedApiVersion {
278 origin: origin.to_owned(),
279 version: version.to_owned(),
280 });
281 }
282
283 let resource =
284 serde_yaml::from_value::<T>(value).map_err(|source| CatalogProblem::Decode {
285 origin: origin.to_owned(),
286 kind: T::KIND,
287 source,
288 })?;
289 let id =
290 resource
291 .name()
292 .parse::<T::Id>()
293 .map_err(|source| CatalogProblem::InvalidName {
294 origin: origin.to_owned(),
295 kind: T::KIND,
296 name: resource.name().to_owned(),
297 source: Box::new(source),
298 })?;
299 if let Some((first, _)) = self.entries.get(&id) {
300 return Err(CatalogProblem::DuplicateResource {
301 kind: T::KIND,
302 name: id.to_string(),
303 first: first.clone(),
304 duplicate: origin.to_owned(),
305 });
306 }
307 self.entries.insert(id, (origin.to_owned(), resource));
308 Ok(())
309 }
310
311 fn iter(&self) -> impl Iterator<Item = (&T::Id, &T)> {
312 self.entries
313 .iter()
314 .map(|(id, (_, resource))| (id, resource))
315 }
316
317 fn into_map(self) -> BTreeMap<T::Id, T> {
318 self.entries
319 .into_iter()
320 .map(|(id, (_, resource))| (id, resource))
321 .collect()
322 }
323}
324
325fn load_agent_skills(
326 agents: &ResourceSet<Agent>,
327 base: &Path,
328 problems: &mut Vec<CatalogProblem>,
329) -> BTreeMap<AgentId, Vec<Skill>> {
330 let mut mounted = BTreeMap::new();
331 for (agent_id, agent) in agents.iter() {
332 if agent.spec.skills.is_empty() {
333 continue;
334 }
335 let mut skills = Vec::with_capacity(agent.spec.skills.len());
336 let mut names = BTreeMap::new();
337 for path in &agent.spec.skills {
338 let resolved = if path.is_absolute() {
339 path.clone()
340 } else {
341 base.join(path)
342 };
343 let skill = match skill::load_skill(&resolved) {
344 Ok(skill) => skill,
345 Err(source) => {
346 problems.push(CatalogProblem::Skill {
347 agent: agent_id.to_string(),
348 path: path.display().to_string(),
349 source: Box::new(source),
350 });
351 continue;
352 }
353 };
354 if let Some(first) = names.insert(skill.name().clone(), path.display().to_string()) {
357 problems.push(CatalogProblem::DuplicateSkill {
358 agent: agent_id.to_string(),
359 name: skill.name().to_string(),
360 first,
361 duplicate: path.display().to_string(),
362 });
363 continue;
364 }
365 skills.push(skill);
366 }
367 mounted.insert(agent_id.clone(), skills);
368 }
369 mounted
370}
371
372#[derive(Clone, Debug, Eq, PartialEq)]
373pub struct DiscoveryContext {
374 explicit: Option<PathBuf>,
375 environment: Option<PathBuf>,
376 xdg_config_home: Option<PathBuf>,
377 home: Option<PathBuf>,
378 current_directory: PathBuf,
379}
380
381impl DiscoveryContext {
382 pub fn from_process(explicit: Option<PathBuf>) -> Result<Self, ConfigError> {
383 Ok(Self {
384 explicit,
385 environment: env::var_os(CONFIG_ENV)
386 .filter(|value| !value.is_empty())
387 .map(PathBuf::from),
388 xdg_config_home: env::var_os("XDG_CONFIG_HOME")
389 .filter(|value| !value.is_empty())
390 .map(PathBuf::from),
391 home: env::var_os("HOME")
392 .filter(|value| !value.is_empty())
393 .map(PathBuf::from),
394 current_directory: env::current_dir().map_err(ConfigError::CurrentDirectory)?,
395 })
396 }
397
398 #[must_use]
399 pub fn new(
400 explicit: Option<PathBuf>,
401 environment: Option<PathBuf>,
402 xdg_config_home: Option<PathBuf>,
403 home: Option<PathBuf>,
404 current_directory: PathBuf,
405 ) -> Self {
406 Self {
407 explicit,
408 environment,
409 xdg_config_home,
410 home,
411 current_directory,
412 }
413 }
414
415 pub fn resolve(&self) -> Result<PathBuf, ConfigError> {
416 if let Some(path) = &self.explicit {
417 return Ok(path.clone());
418 }
419 if let Some(path) = &self.environment {
420 return Ok(path.clone());
421 }
422
423 let mut searched = Vec::new();
424 if let Some(root) = &self.xdg_config_home {
425 searched.push(root.join("dekopon/config.yaml"));
426 }
427 if let Some(home) = &self.home {
428 searched.push(home.join(".config/dekopon/config.yaml"));
429 }
430 searched.push(self.current_directory.join("dekopon.yaml"));
431
432 for path in &searched {
433 match fs::metadata(path) {
434 Ok(metadata) if metadata.is_file() => return Ok(path.clone()),
435 Ok(_) => {}
436 Err(error) if error.kind() == io::ErrorKind::NotFound => {}
437 Err(source) => {
440 return Err(ConfigError::Candidate {
441 path: path.display().to_string(),
442 source,
443 });
444 }
445 }
446 }
447
448 Err(ConfigError::NotFound {
449 searched: searched
450 .iter()
451 .map(|path| path.display().to_string())
452 .collect::<Vec<_>>()
453 .join(", "),
454 })
455 }
456}
457
458pub fn load_discovered(explicit: Option<PathBuf>) -> Result<LocalCatalog, ConfigError> {
459 let path = DiscoveryContext::from_process(explicit)?.resolve()?;
460 LocalCatalog::load(path)
461}
462
463#[derive(Debug, Error)]
464pub enum ConfigError {
465 #[error("failed to read configuration {path}: {source}")]
466 Read {
467 path: String,
468 #[source]
469 source: io::Error,
470 },
471 #[error("{path}: {origin}: invalid YAML or JSON: {source}")]
472 Parse {
473 path: String,
474 origin: String,
475 #[source]
476 source: serde_yaml::Error,
477 },
478 #[error("{path}: {origin}: invalid {kind}: {source}")]
479 Decode {
480 path: String,
481 origin: String,
482 kind: String,
483 #[source]
484 source: serde_yaml::Error,
485 },
486 #[error("{path}: configuration contains no resources")]
487 Empty { path: String },
488 #[error("{path}: {}", render_problems(.problems))]
489 Invalid {
490 path: String,
491 problems: Vec<CatalogProblem>,
492 },
493 #[error("failed to examine configuration candidate {path}: {source}")]
494 Candidate {
495 path: String,
496 #[source]
497 source: io::Error,
498 },
499 #[error("no Dekopon configuration found; searched: {searched}")]
500 NotFound { searched: String },
501 #[error("could not resolve the current directory: {0}")]
502 CurrentDirectory(#[source] io::Error),
503}
504
505fn render_problems(problems: &[CatalogProblem]) -> String {
506 let mut rendered = format!(
507 "{} validation problem{} found:",
508 problems.len(),
509 if problems.len() == 1 { "" } else { "s" }
510 );
511 for problem in problems {
512 rendered.push_str("\n - ");
513 rendered.push_str(&problem.to_string());
514 }
515 rendered
516}
517
518#[derive(Debug, Error)]
519pub enum CatalogProblem {
520 #[error("{origin}: resource is missing string field `kind`")]
521 MissingKind { origin: String },
522 #[error("{origin}: unsupported resource kind {kind:?}")]
523 UnsupportedKind { origin: String, kind: String },
524 #[error("agent {agent} sets both instructions and instructionsFile")]
525 InstructionsTwice { agent: String },
526 #[error("agent {agent} instructionsFile {path}: {source}")]
527 Instructions {
528 agent: String,
529 path: String,
530 #[source]
531 source: io::Error,
532 },
533 #[error("agent {agent} instructionsFile is {length} bytes; maximum is {maximum}")]
534 InstructionsTooLarge {
535 agent: String,
536 length: usize,
537 maximum: usize,
538 },
539 #[error("{origin}: unsupported API version {version:?}")]
540 UnsupportedApiVersion { origin: String, version: String },
541 #[error("{origin}: invalid {kind}: {source}")]
542 Decode {
543 origin: String,
544 kind: &'static str,
545 #[source]
546 source: serde_yaml::Error,
547 },
548 #[error("{origin}: invalid {kind} name {name:?}: {source}")]
549 InvalidName {
550 origin: String,
551 kind: &'static str,
552 name: String,
553 #[source]
554 source: Box<IdentifierError>,
555 },
556 #[error("duplicate {kind} {name:?} at {duplicate}; first declared at {first}")]
557 DuplicateResource {
558 kind: &'static str,
559 name: String,
560 first: String,
561 duplicate: String,
562 },
563 #[error("agent {agent:?} mounts skill {path:?}, which could not be loaded: {source}")]
564 Skill {
565 agent: String,
566 path: String,
567 #[source]
568 source: Box<SkillError>,
569 },
570 #[error(
571 "agent {agent:?} mounts skill {name:?} twice, at {first:?} and {duplicate:?}; a model could not tell them apart"
572 )]
573 DuplicateSkill {
574 agent: String,
575 name: String,
576 first: String,
577 duplicate: String,
578 },
579}
580
581#[cfg(test)]
582mod tests;