Skip to main content

rigspark_runtime/
library.rs

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}