1use crate::memory::{MemoryError, owned_directory};
2use serde::{Deserialize, Serialize};
3use std::{
4 collections::BTreeMap,
5 fs,
6 path::{Path, PathBuf},
7 time::Duration,
8};
9#[derive(Debug, Clone, Copy)]
10pub enum Kind {
11 Agent,
12 Skill,
13}
14#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
15#[serde(deny_unknown_fields)]
16pub struct LibraryItem {
17 pub id: String,
18 pub name: String,
19 pub description: String,
20 pub enabled: bool,
21 pub body: String,
22 #[serde(default)]
23 pub skills: Vec<String>,
24}
25#[derive(Default, Deserialize)]
26#[serde(deny_unknown_fields)]
27pub struct LibraryUpdate {
28 pub name: Option<String>,
29 pub description: Option<String>,
30 pub enabled: Option<bool>,
31 pub body: Option<String>,
32 pub skills: Option<Vec<String>>,
33}
34fn id_valid(id: &str) -> bool {
35 !id.is_empty()
36 && id.len() <= 64
37 && id.as_bytes()[0].is_ascii_alphanumeric()
38 && id
39 .bytes()
40 .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'-')
41}
42
43pub fn validate_selection(agent: Option<&str>, skills: &[String]) -> Result<(), MemoryError> {
44 if agent.is_some_and(|id| !id.is_empty() && !id_valid(id))
45 || skills.iter().any(|id| !id_valid(id))
46 {
47 return Err(MemoryError("invalid library id".into()));
48 }
49 if skills.len() > 50 {
50 return Err(MemoryError("skill selection exceeds limit".into()));
51 }
52 Ok(())
53}
54
55impl LibraryItem {
56 fn validate(&self) -> Result<(), MemoryError> {
57 if !id_valid(&self.id)
58 || self.name.is_empty()
59 || self.name.encode_utf16().count() > 120
60 || self.description.encode_utf16().count() > 500
61 || self.body.encode_utf16().count() > 65536
62 || self.skills.len() > 50
63 || self.skills.iter().any(|id| !id_valid(id))
64 {
65 return Err(MemoryError("invalid library item".into()));
66 }
67 Ok(())
68 }
69}
70pub fn parse_document(raw: &str) -> (BTreeMap<String, String>, String) {
71 let raw = raw.strip_prefix('\u{feff}').unwrap_or(raw);
72 let lines: Vec<_> = raw.split('\n').collect();
73 if lines.first().is_none_or(|line| line.trim() != "---") {
74 return (BTreeMap::new(), raw.into());
75 }
76 let Some(close) = lines
77 .iter()
78 .enumerate()
79 .skip(1)
80 .find(|(_, line)| line.trim() == "---")
81 .map(|(index, _)| index)
82 else {
83 return (BTreeMap::new(), raw.into());
84 };
85 let mut fields = BTreeMap::new();
86 for line in &lines[1..close] {
87 if let Some((key, value)) = line.split_once(':') {
88 if key.trim().is_empty()
89 || key.starts_with(char::is_whitespace)
90 || !key
91 .trim()
92 .bytes()
93 .all(|byte| byte.is_ascii_alphanumeric() || b"_-".contains(&byte))
94 {
95 continue;
96 }
97 let value = value.trim();
98 let decoded = if value.len() >= 2 && value.starts_with('"') && value.ends_with('"') {
99 value[1..value.len() - 1]
100 .replace("\\\"", "\"")
101 .replace("\\\\", "\\")
102 } else if value.len() >= 2 && value.starts_with('\'') && value.ends_with('\'') {
103 value[1..value.len() - 1].into()
104 } else {
105 value.into()
106 };
107 fields.insert(key.trim().into(), decoded);
108 }
109 }
110 (
111 fields,
112 lines[close + 1..]
113 .join("\n")
114 .trim_start_matches('\n')
115 .trim_end()
116 .into(),
117 )
118}
119fn scalar(value: &str) -> String {
120 if !value.is_empty()
121 && value.trim() == value
122 && value.as_bytes()[0].is_ascii_alphanumeric()
123 && value
124 .bytes()
125 .all(|byte| byte.is_ascii_alphanumeric() || b" _.-/".contains(&byte))
126 {
127 value.into()
128 } else {
129 format!("\"{}\"", value.replace('\\', "\\\\").replace('"', "\\\""))
130 }
131}
132pub fn compose(agent: Option<&LibraryItem>, skills: &[LibraryItem]) -> Option<String> {
133 let mut parts = Vec::new();
134 if let Some(agent) = agent.filter(|agent| !agent.body.trim().is_empty()) {
135 parts.push(agent.body.trim().to_owned());
136 }
137 let skills: Vec<_> = skills
138 .iter()
139 .filter(|skill| !skill.body.trim().is_empty())
140 .map(|skill| format!("## {}\n{}", skill.name, skill.body.trim()))
141 .collect();
142 if !skills.is_empty() {
143 parts.push(format!(
144 "# Skills\nApply these skills when relevant:\n\n{}",
145 skills.join("\n\n")
146 ));
147 }
148 (!parts.is_empty()).then(|| parts.join("\n\n"))
149}
150pub struct Library {
151 home: PathBuf,
152}
153impl Library {
154 pub fn new(home: &Path) -> Self {
155 Self { home: home.into() }
156 }
157 fn directory(&self, kind: Kind) -> PathBuf {
158 self.home.join(match kind {
159 Kind::Agent => "agents",
160 Kind::Skill => "skills",
161 })
162 }
163 fn path(&self, kind: Kind, id: &str) -> Result<PathBuf, MemoryError> {
164 if !id_valid(id) {
165 return Err(MemoryError("invalid library id".into()));
166 }
167 let directory = self.directory(kind);
168 for path in [&self.home, &directory] {
169 if let Ok(metadata) = fs::symlink_metadata(path)
170 && (!metadata.is_dir() || metadata.file_type().is_symlink())
171 {
172 return Err(MemoryError("unsafe library directory".into()));
173 }
174 }
175 match kind {
176 Kind::Agent => Ok(directory.join(format!("{id}.md"))),
177 Kind::Skill => {
178 let parent = directory.join(id);
179 if let Ok(metadata) = fs::symlink_metadata(&parent)
180 && (!metadata.is_dir() || metadata.file_type().is_symlink())
181 {
182 return Err(MemoryError("unsafe skill directory".into()));
183 }
184 Ok(parent.join("SKILL.md"))
185 }
186 }
187 }
188 pub fn get(&self, kind: Kind, id: &str) -> Result<Option<LibraryItem>, MemoryError> {
189 let path = self.path(kind, id)?;
190 let read = (|| {
191 let directory = crate::secure_fs::Directory::open(&self.home)?;
192 directory.read(
193 path.strip_prefix(&self.home)
194 .map_err(|_| std::io::Error::other("invalid library path"))?,
195 69632,
196 false,
197 )
198 })();
199 let raw = match read {
200 Ok(raw) => {
201 String::from_utf8(raw).map_err(|_| MemoryError("library is not UTF-8".into()))?
202 }
203 Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None),
204 Err(error) => return Err(error.into()),
205 };
206 let (fields, body) = parse_document(&raw);
207 let cap = crate::sessions::cap;
208 let item = LibraryItem {
209 id: id.into(),
210 name: cap(fields.get("name").map(String::as_str).unwrap_or(id), 120),
211 description: cap(
212 fields.get("description").map(String::as_str).unwrap_or(""),
213 500,
214 ),
215 enabled: fields.get("enabled").is_none_or(|value| value != "false"),
216 body: cap(&body, 65536),
217 skills: fields
218 .get("skills")
219 .map(|value| {
220 value
221 .split(',')
222 .map(str::trim)
223 .filter(|id| id_valid(id))
224 .take(50)
225 .map(str::to_owned)
226 .collect()
227 })
228 .unwrap_or_default(),
229 };
230 item.validate()?;
231 Ok(Some(item))
232 }
233 pub fn list(&self, kind: Kind) -> Result<Vec<LibraryItem>, MemoryError> {
234 let directory = self.directory(kind);
235 if !directory.try_exists()? {
236 return Ok(Vec::new());
237 }
238 let mut items = Vec::new();
239 let root = crate::secure_fs::Directory::open(&self.home)?;
240 let directory = root.subdir(
241 directory
242 .strip_prefix(&self.home)
243 .map_err(|_| MemoryError("invalid library directory".into()))?,
244 )?;
245 for (count, entry) in directory.entries()?.enumerate() {
246 if count >= 10000 {
247 return Err(MemoryError("library exceeds entry limit".into()));
248 }
249 let entry = entry?;
250 let name = entry.file_name().to_string_lossy().into_owned();
251 let id = match kind {
252 Kind::Agent => name.strip_suffix(".md"),
253 Kind::Skill => Some(name.as_str()),
254 };
255 if let Some(id) = id
256 && let Ok(Some(item)) = self.get(kind, id)
257 {
258 items.push(item);
259 }
260 }
261 items.sort_by(|left, right| left.id.cmp(&right.id));
262 Ok(items)
263 }
264 fn write_inner(&self, kind: Kind, item: &LibraryItem) -> Result<(), MemoryError> {
265 item.validate()?;
266 if item.name.contains(['\n', '\r']) || item.description.contains(['\n', '\r']) {
267 return Err(MemoryError("multiline frontmatter scalar".into()));
268 }
269 let path = self.path(kind, &item.id)?;
270 owned_directory(&self.home)?;
271 let directory = crate::secure_fs::Directory::open(&self.home)?;
272 let relative = path
273 .strip_prefix(&self.home)
274 .map_err(|_| MemoryError("invalid library path".into()))?;
275 directory.ensure_dir(
276 relative
277 .parent()
278 .ok_or_else(|| MemoryError("missing library parent".into()))?,
279 )?;
280 let mut header = format!("---\nname: {}\n", scalar(&item.name));
281 if !item.description.is_empty() {
282 header.push_str(&format!("description: {}\n", scalar(&item.description)));
283 }
284 header.push_str(&format!("enabled: {}\n", item.enabled));
285 if !item.skills.is_empty() {
286 header.push_str(&format!("skills: {}\n", scalar(&item.skills.join(", "))));
287 }
288 header.push_str(&format!("---\n\n{}\n", item.body.trim_end()));
289 if header.len() > 69632 {
290 return Err(MemoryError("library document exceeds limit".into()));
291 }
292 Ok(directory.write(relative, header.as_bytes(), false, false)?)
293 }
294 fn lock(&self) -> Result<crate::state::LockGuard, MemoryError> {
295 Ok(
296 crate::state::StateStore::new(crate::state::Config::from_home(&self.home)?)
297 .lock(Duration::from_secs(10))?,
298 )
299 }
300 pub fn write(&self, kind: Kind, item: &LibraryItem) -> Result<(), MemoryError> {
301 let guard = self.lock()?;
302 self.write_inner(kind, item)?;
303 guard.release()?;
304 Ok(())
305 }
306 pub fn create(&self, kind: Kind, mut item: LibraryItem) -> Result<LibraryItem, MemoryError> {
307 let guard = self.lock()?;
308 let mut base = String::new();
309 for character in item.name.to_lowercase().chars() {
310 if character.is_ascii_alphanumeric() {
311 base.push(character);
312 } else if !base.ends_with('-') {
313 base.push('-');
314 }
315 }
316 let base = base
317 .trim_matches('-')
318 .chars()
319 .take(64)
320 .collect::<String>()
321 .trim_end_matches('-')
322 .to_owned();
323 let base = if base.is_empty() { "item".into() } else { base };
324 let mut selected = None;
325 for number in 1..1000 {
326 let id = if number == 1 {
327 base.clone()
328 } else {
329 format!("{}-{number}", &base[..base.len().min(59)])
330 };
331 if !self.path(kind, &id)?.try_exists()? {
332 selected = Some(id);
333 break;
334 }
335 }
336 item.id = selected.ok_or_else(|| MemoryError("too many items with this name".into()))?;
337 self.write_inner(kind, &item)?;
338 guard.release()?;
339 Ok(item)
340 }
341 pub fn update(
342 &self,
343 kind: Kind,
344 id: &str,
345 patch: LibraryUpdate,
346 ) -> Result<LibraryItem, MemoryError> {
347 let guard = self.lock()?;
348 let mut item = self
349 .get(kind, id)?
350 .ok_or_else(|| MemoryError("library item not found".into()))?;
351 if let Some(name) = patch.name {
352 item.name = name;
353 }
354 if let Some(description) = patch.description {
355 item.description = description;
356 }
357 if let Some(enabled) = patch.enabled {
358 item.enabled = enabled;
359 }
360 if let Some(body) = patch.body {
361 item.body = body;
362 }
363 if let Some(skills) = patch.skills {
364 item.skills = skills.into_iter().filter(|id| id_valid(id)).collect();
365 }
366 self.write_inner(kind, &item)?;
367 guard.release()?;
368 Ok(item)
369 }
370 pub fn remove(&self, kind: Kind, id: &str) -> Result<(), MemoryError> {
371 let guard = self.lock()?;
372 let path = self.path(kind, id)?;
373 if self.get(kind, id)?.is_none() {
374 return Err(MemoryError("library item not found".into()));
375 }
376 let directory = crate::secure_fs::Directory::open(&self.home)?;
377 let relative = path
378 .strip_prefix(&self.home)
379 .map_err(|_| MemoryError("invalid library path".into()))?;
380 match kind {
381 Kind::Agent => directory.remove(relative)?,
382 Kind::Skill => directory.dir()?.remove_dir_all(
383 relative
384 .parent()
385 .ok_or_else(|| MemoryError("missing skill parent".into()))?,
386 )?,
387 }
388 guard.release()?;
389 Ok(())
390 }
391 pub fn compose(
392 &self,
393 agent: Option<&str>,
394 skills: &[String],
395 ) -> Result<Option<String>, MemoryError> {
396 validate_selection(agent, skills)?;
397 let agent = agent
398 .filter(|id| !id.is_empty())
399 .map(|id| self.get(Kind::Agent, id))
400 .transpose()?
401 .flatten()
402 .filter(|item| item.enabled);
403 let mut selected = Vec::new();
404 let mut seen = std::collections::HashSet::new();
405 for id in agent.iter().flat_map(|item| &item.skills).chain(skills) {
406 if seen.insert(id)
407 && let Some(skill) = self.get(Kind::Skill, id)?.filter(|skill| skill.enabled)
408 {
409 selected.push(skill);
410 }
411 }
412 Ok(compose(agent.as_ref(), &selected))
413 }
414}