Skip to main content

kernel_apis/
skills.rs

1//! `skills.*` requests (port of `ultron/skills.ts`): the version-pinned, explainable skill catalog and the code-skill
2//! requests, journaled in the module document. Selection never grants capabilities: frontmatter keys that would
3//! grant tools, models, budgets or permissions are reported and ignored.
4
5use crate::TaskHost;
6use crate::code_skills::{CodeSkillKind, CodeSkills};
7use crate::store::read_versioned;
8use crate::util::{Clock, object};
9use kernel::Signal;
10use kernel::store::DocumentStore;
11use serde_json::{Map, Value, json};
12use std::collections::HashSet;
13use std::sync::{Arc, Mutex};
14use yaml_rust2::Yaml;
15
16/// A skill as Pi's loader discovered it; this module never discovers skills itself.
17#[derive(Debug, Clone)]
18pub struct SkillSource {
19    pub name: String,
20    pub description: String,
21    pub file_path: String,
22    pub content: String,
23    pub disable_model_invocation: bool,
24}
25
26pub type SkillLoader = Arc<dyn Fn() -> Result<Vec<SkillSource>, String> + Send + Sync>;
27
28const CAPABILITY_KEYS: &[&str] = &[
29    "allowed-tools",
30    "allowed_tools",
31    "allowedTools",
32    "tools",
33    "grants",
34    "permissions",
35    "capabilities",
36    "model",
37    "budget",
38    "timeout",
39];
40const STOPWORDS: &[&str] = &[
41    "a", "an", "and", "are", "for", "how", "i", "in", "is", "it", "me", "my", "of", "on", "or", "the", "this", "to",
42    "with",
43];
44const EXACT_NAME_BONUS: i64 = 5;
45const MAX_RECORDS: usize = 2000;
46const MAX_QUERY_CHARS: usize = 4000;
47
48struct Skill {
49    name: String,
50    description: String,
51    file_path: String,
52    version: String,
53    invocable: bool,
54    content: String,
55    body: String,
56    ignored: Map<String, Value>,
57}
58
59fn parse_skill(source: &SkillSource) -> Skill {
60    let (frontmatter, body) = match resources::frontmatter::parse(&source.content) {
61        Ok(parsed) => (parsed.frontmatter, parsed.body),
62        // Pi's loader already rejected unparseable skills; tolerate them here as plain bodies.
63        Err(_) => (Yaml::Null, source.content.clone()),
64    };
65    let mut ignored = Map::new();
66    if let Yaml::Hash(map) = &frontmatter {
67        for key in CAPABILITY_KEYS {
68            if let Some(value) = map.get(&Yaml::String((*key).to_string())) {
69                ignored.insert((*key).to_string(), resources::frontmatter::to_json(value));
70            }
71        }
72    }
73    Skill {
74        name: source.name.clone(),
75        description: source.description.clone(),
76        file_path: source.file_path.clone(),
77        version: jsrt::hash::sha256_hex(source.content.as_bytes()),
78        invocable: !source.disable_model_invocation,
79        content: source.content.clone(),
80        body,
81        ignored,
82    }
83}
84
85fn tokens(text: &str) -> Vec<String> {
86    let lower = text.to_lowercase();
87    lower
88        .split(|c: char| !(c.is_ascii_lowercase() || c.is_ascii_digit()))
89        .filter(|token| !token.is_empty())
90        .map(str::to_string)
91        .collect()
92}
93
94fn query_terms(query: &str) -> Vec<String> {
95    let mut seen = HashSet::new();
96    tokens(query)
97        .into_iter()
98        .filter(|term| term.len() > 1 && !STOPWORDS.contains(&term.as_str()) && seen.insert(term.clone()))
99        .collect()
100}
101
102fn score(skill: &Skill, terms: &[String], query: &str) -> Option<Value> {
103    let set = |text: &str| -> HashSet<String> { tokens(text).into_iter().collect() };
104    let (name, description, body) = (set(&skill.name), set(&skill.description), set(&skill.body));
105    let mut matches = Vec::new();
106    let mut total = 0;
107    for term in terms {
108        let mut matched = Vec::new();
109        for (field, tokens, weight) in [("name", &name, 3), ("description", &description, 2), ("body", &body, 1)] {
110            if tokens.contains(term) {
111                matched.push(field);
112                total += weight;
113            }
114        }
115        if !matched.is_empty() {
116            matches.push(json!({"term": term, "fields": matched}));
117        }
118    }
119    if skill.name.to_lowercase() == query.trim().to_lowercase() {
120        total += EXACT_NAME_BONUS;
121    }
122    (total > 0).then(|| json!({"name": skill.name, "version": skill.version, "score": total, "matches": matches}))
123}
124
125fn version_string(value: Option<&Value>) -> Result<String, String> {
126    match value.and_then(Value::as_str) {
127        Some(text) if text.len() == 64 && text.bytes().all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b)) => {
128            Ok(text.to_string())
129        }
130        _ => Err("version must be a lowercase sha256 hex digest".into()),
131    }
132}
133
134fn empty_document() -> Value {
135    json!({"format": 1, "generation": 0, "catalog": [], "changes": [], "decisions": [], "loads": [], "invocations": []})
136}
137
138fn read_document(saved: Option<Value>) -> Result<Value, String> {
139    let Some(document) = read_versioned("ultron.module/skills", saved, "format")? else {
140        return Ok(empty_document());
141    };
142    let valid = document["format"] == 1
143        && document
144            .get("generation")
145            .and_then(jsrt::number::safe_integer)
146            .is_some()
147        && ["catalog", "changes", "decisions", "loads", "invocations"]
148            .iter()
149            .all(|key| document[key].is_array());
150    if !valid {
151        return Err("Skill module document is invalid".into());
152    }
153    Ok(document)
154}
155
156fn append(document: &mut Value, key: &str, record: Value) {
157    if document.get(key).is_none() {
158        document[key] = json!([]);
159    }
160    if let Some(Value::Array(records)) = document.get_mut(key) {
161        records.push(record);
162        if records.len() > MAX_RECORDS {
163            let excess = records.len() - MAX_RECORDS;
164            records.drain(..excess);
165        }
166    }
167}
168
169/// `invocationPrompt`: the skill block of Pi's `/skill` expansion, its version and the input as JSON.
170fn invocation_prompt(skill: &Skill, input: &Value) -> String {
171    let dir = match skill.file_path.rfind('/') {
172        Some(0) => "/",
173        Some(at) => &skill.file_path[..at],
174        None => ".",
175    };
176    format!(
177        "<skill name=\"{}\" location=\"{}\">\nReferences are relative to {dir}.\n\n{}\n</skill>\n\nSkill version: {}\n\nInput (JSON):\n{}",
178        skill.name,
179        skill.file_path,
180        skill.body,
181        skill.version,
182        jsrt::json::stringify(input)
183    )
184}
185
186struct Snapshot {
187    generation: i64,
188    skills: Vec<Skill>,
189}
190
191impl Snapshot {
192    fn get(&self, name: &str) -> Option<&Skill> {
193        self.skills.iter().find(|skill| skill.name == name)
194    }
195}
196
197/// One catalog skill as pinned for a caller outside this module (skill procedures, `delegation::skill_runs`).
198#[derive(Debug, Clone)]
199pub struct PinnedSkill {
200    pub name: String,
201    /// sha256 of the file content.
202    pub version: String,
203    pub file_path: String,
204    pub content: String,
205}
206
207/// Serves `skills.*`. Durable mutations and snapshot installation run one at a time.
208pub struct SkillsModule {
209    store: Arc<dyn DocumentStore>,
210    load_skills: SkillLoader,
211    now: Clock,
212    code: Option<CodeSkills>,
213    snapshot: Mutex<Option<Arc<Snapshot>>>,
214    exclusive: Mutex<()>,
215}
216
217impl SkillsModule {
218    pub fn new(store: Arc<dyn DocumentStore>, load_skills: SkillLoader, now: Clock, code: Option<CodeSkills>) -> Self {
219        Self {
220            store,
221            load_skills,
222            now,
223            code,
224            snapshot: Mutex::new(None),
225            exclusive: Mutex::new(()),
226        }
227    }
228
229    pub fn code(&self) -> Option<&CodeSkills> {
230        self.code.as_ref()
231    }
232
233    fn mutate<T>(&self, change: impl FnOnce(&mut Value) -> T) -> Result<T, String> {
234        let mut document = read_document(self.store.read()?)?;
235        let result = change(&mut document);
236        self.store.write(&document)?;
237        Ok(result)
238    }
239
240    /// Caller holds `exclusive`.
241    fn refresh_locked(&self) -> Result<Value, String> {
242        let sources = (self.load_skills)()?;
243        let mut seen = HashSet::new();
244        for source in &sources {
245            if source.name.is_empty() {
246                return Err("loadSkills returned an invalid skill".into());
247            }
248            if !seen.insert(source.name.clone()) {
249                return Err(format!("Duplicate skill name: {}", source.name));
250            }
251        }
252        let skills: Vec<Skill> = sources.iter().map(parse_skill).collect();
253        let at = (self.now)();
254        let outcome = self.mutate(|document| {
255            let previous: Vec<(String, String)> = document["catalog"]
256                .as_array()
257                .map(|entries| {
258                    entries
259                        .iter()
260                        .map(|entry| {
261                            let text = |key: &str| entry[key].as_str().unwrap_or_default().to_string();
262                            (text("name"), text("version"))
263                        })
264                        .collect()
265                })
266                .unwrap_or_default();
267            let generation = document["generation"].as_i64().unwrap_or(0) + 1;
268            let lookup = |list: &[(String, String)], name: &str| {
269                list.iter()
270                    .find(|(key, _)| key == name)
271                    .map(|(_, version)| version.clone())
272            };
273            let next: Vec<(String, String)> = skills.iter().map(|s| (s.name.clone(), s.version.clone())).collect();
274            let mut names: Vec<String> = previous
275                .iter()
276                .chain(next.iter())
277                .map(|(name, _)| name.clone())
278                .collect();
279            names.sort();
280            names.dedup();
281            let mut changes = Vec::new();
282            for name in names {
283                let (from, to) = (lookup(&previous, &name), lookup(&next, &name));
284                if from != to {
285                    changes.push(json!({"at": at, "generation": generation, "name": name, "from": from, "to": to}));
286                }
287            }
288            document["generation"] = generation.into();
289            document["catalog"] = skills
290                .iter()
291                .map(|skill| {
292                    json!({"name": skill.name, "description": skill.description, "file_path": skill.file_path,
293                        "version": skill.version, "invocable": skill.invocable})
294                })
295                .collect();
296            for change in &changes {
297                append(document, "changes", change.clone());
298            }
299            json!({"generation": generation, "changes": changes})
300        })?;
301        // Install only after the catalog record is durable.
302        *jsrt::sync::lock(&self.snapshot) = Some(Arc::new(Snapshot {
303            generation: outcome["generation"].as_i64().unwrap_or(0),
304            skills,
305        }));
306        Ok(outcome)
307    }
308
309    /// One consistent catalog for the whole request, loaded on first use.
310    fn current(&self) -> Result<Arc<Snapshot>, String> {
311        if let Some(snapshot) = jsrt::sync::lock(&self.snapshot).clone() {
312            return Ok(snapshot);
313        }
314        let _exclusive = jsrt::sync::lock(&self.exclusive);
315        if jsrt::sync::lock(&self.snapshot).is_none() {
316            self.refresh_locked()?;
317        }
318        Ok(jsrt::sync::lock(&self.snapshot).clone().expect("installed by refresh"))
319    }
320
321    fn pinned<'a>(snapshot: &'a Snapshot, name: &str, version: Option<&str>) -> Result<&'a Skill, String> {
322        let Some(skill) = snapshot.get(name) else {
323            return Err(match version {
324                Some(version) => {
325                    format!("Stale skill version: {name}@{version} is no longer in the catalog (skill removed)")
326                }
327                None => format!("Unknown skill: {name}"),
328            });
329        };
330        if let Some(version) = version
331            && skill.version != version
332        {
333            return Err(format!(
334                "Stale skill version: {name}@{version} was requested but the catalog has {name}@{}; select or load again",
335                skill.version
336            ));
337        }
338        Ok(skill)
339    }
340
341    /// Module start: loads the catalog.
342    pub fn start(&self) -> Result<(), String> {
343        self.current().map(drop)
344    }
345
346    /// A request without a task runtime (`skills.invoke` is refused: nothing can spawn the skill's task).
347    pub fn handle(
348        &self,
349        kind: &str,
350        payload: &Map<String, Value>,
351        caller: Option<&str>,
352        signal: &Signal,
353    ) -> Result<Value, String> {
354        let host = crate::RootOnly {
355            now: crate::util::system_clock(),
356        };
357        self.handle_with_host(kind, payload, caller, &host, signal)
358    }
359
360    /// A request whose `skills.invoke` spawns through `host`.
361    pub fn handle_with_host(
362        &self,
363        kind: &str,
364        payload: &Map<String, Value>,
365        caller: Option<&str>,
366        host: &dyn TaskHost,
367        signal: &Signal,
368    ) -> Result<Value, String> {
369        match kind {
370            "skills.refresh" => {
371                kernel::ops::fields("skills.refresh", payload)?;
372                let _exclusive = jsrt::sync::lock(&self.exclusive);
373                self.refresh_locked()
374            }
375            "skills.list" => {
376                kernel::ops::fields("skills.list", payload)?;
377                let snapshot = self.current()?;
378                let skills: Vec<Value> = snapshot
379                    .skills
380                    .iter()
381                    .map(|s| json!({"name": s.name, "description": s.description, "version": s.version, "invocable": s.invocable}))
382                    .collect();
383                Ok(json!({"generation": snapshot.generation, "skills": skills}))
384            }
385            "skills.select" => self.select(payload, caller),
386            "skills.load" => self.load(payload, caller),
387            "skills.why" => {
388                kernel::ops::fields("skills.why", payload)?;
389                let id = jsrt::payload::nonempty_string(payload.get("decision_id"), "decision_id")?;
390                let document = read_document(self.store.read()?)?;
391                document["decisions"]
392                    .as_array()
393                    .and_then(|decisions| decisions.iter().find(|decision| decision["id"] == id.as_str()))
394                    .cloned()
395                    .ok_or_else(|| format!("Unknown skill decision: {id}"))
396            }
397            "skills.invoke" => self.invoke(payload, caller, host),
398            "skills.propose_code" | "skills.propose_policy" | "skills.rollback" => {
399                self.change_code(kind, payload, caller, signal)
400            }
401            "skills.code_list" => {
402                kernel::ops::fields("skills.code_list", payload)?;
403                let filter_kind = match payload.get("kind") {
404                    None => None,
405                    Some(Value::String(kind)) if kind == "code" || kind == "policy" => Some(kind.as_str()),
406                    Some(_) => return Err("kind must be \"code\" or \"policy\"".into()),
407                };
408                let family = match payload.get("family") {
409                    None => None,
410                    value => Some(jsrt::payload::nonempty_string(value, "family")?),
411                };
412                Ok(Value::Array(self.code_skills()?.list(filter_kind, family.as_deref())))
413            }
414            "skills.code_history" => {
415                kernel::ops::fields("skills.code_history", payload)?;
416                self.code_skills()?.history(payload.get("name"))
417            }
418            _ => Err(format!("Unsupported skills request: {kind}")),
419        }
420    }
421
422    /// `invoke`: the pinned skill as an `rlm-child@1` task of the caller. Only definition, input and key reach the
423    /// host: frontmatter never changes the child's model, tools or budget. Each invocation is journaled
424    /// (`admitting`, then `spawned` with its task, or `failed` with the error).
425    fn invoke(&self, payload: &Map<String, Value>, caller: Option<&str>, host: &dyn TaskHost) -> Result<Value, String> {
426        kernel::ops::fields("skills.invoke", payload)?;
427        let name = jsrt::payload::nonempty_string(payload.get("name"), "name")?;
428        let version = version_string(payload.get("version"))?;
429        let Some(input) = payload.get("input") else {
430            return Err("input must be JSON".into());
431        };
432        let snapshot = self.current()?;
433        let skill = Self::pinned(&snapshot, &name, Some(&version))?;
434        if !skill.invocable {
435            return Err(format!("Skill {name} disables model invocation"));
436        }
437        let invocation = json!({
438            "id": jsrt::random::uuid_v4(),
439            "at": (self.now)(),
440            "name": name,
441            "version": skill.version,
442            "caller_task_id": caller,
443            "state": "admitting",
444        });
445        let id = invocation["id"].as_str().unwrap_or_default().to_string();
446        let record = |change: Value| self.upsert("invocations", &invocation, &change);
447        record(json!({}))?;
448        let request = json!({
449            "definition": "rlm-child@1",
450            "input": {"prompt": invocation_prompt(skill, input)},
451            "key": format!("skills.invoke:{id}"),
452        });
453        let task_id = match host.spawn(&request, caller) {
454            Ok(task) => task["id"].as_str().unwrap_or_default().to_string(),
455            Err(error) => {
456                record(json!({"state": "failed", "error": error}))?;
457                return Err(error);
458            }
459        };
460        record(json!({"state": "spawned", "task_id": task_id}))?;
461        Ok(json!({
462            "invocation_id": id,
463            "task_id": task_id,
464            "name": name,
465            "version": skill.version,
466            "ignored_capability_requests": skill.ignored,
467        }))
468    }
469
470    /// Merge `change` into the record of `key` (a journal list of the module document) whose `id` is `base`'s, or
471    /// append `base` with `change` merged when there is none.
472    pub fn upsert(&self, key: &str, base: &Value, change: &Value) -> Result<(), String> {
473        let _exclusive = jsrt::sync::lock(&self.exclusive);
474        self.mutate(|document| {
475            let id = &base["id"];
476            let existing = document
477                .get_mut(key)
478                .and_then(Value::as_array_mut)
479                .and_then(|items| items.iter_mut().find(|item| &item["id"] == id));
480            let merge = |target: &mut Value| {
481                for (field, value) in change.as_object().into_iter().flatten() {
482                    target[field] = value.clone();
483                }
484            };
485            match existing {
486                Some(existing) => merge(existing),
487                None => {
488                    let mut next = base.clone();
489                    merge(&mut next);
490                    append(document, key, next);
491                }
492            }
493        })
494    }
495
496    /// The records of `key` (a journal list of the module document), oldest first.
497    pub fn records(&self, key: &str) -> Result<Vec<Value>, String> {
498        let document = read_document(self.store.read()?)?;
499        Ok(document[key].as_array().cloned().unwrap_or_default())
500    }
501
502    /// The catalog's `name` (at `version`, when given: an older version is refused as stale).
503    pub fn pinned_skill(&self, name: &str, version: Option<&str>) -> Result<PinnedSkill, String> {
504        let snapshot = self.current()?;
505        let skill = Self::pinned(&snapshot, name, version)?;
506        Ok(PinnedSkill {
507            name: skill.name.clone(),
508            version: skill.version.clone(),
509            file_path: skill.file_path.clone(),
510            content: skill.content.clone(),
511        })
512    }
513
514    fn code_skills(&self) -> Result<&CodeSkills, String> {
515        self.code
516            .as_ref()
517            .ok_or_else(|| "Code skills are not configured in this worker".to_string())
518    }
519
520    /// Proposals and rollbacks, recorded in this module's journal whatever their outcome.
521    fn change_code(
522        &self,
523        kind: &str,
524        payload: &Map<String, Value>,
525        caller: Option<&str>,
526        signal: &Signal,
527    ) -> Result<Value, String> {
528        let code = self.code_skills()?;
529        let action = &kind["skills.".len()..];
530        let name = payload
531            .get("name")
532            .and_then(Value::as_str)
533            .map(|name| jsrt::utf16::head(name, 64).to_string())
534            .unwrap_or_default();
535        let base = vec![
536            ("id", Value::from(jsrt::random::uuid_v4())),
537            ("at", Value::from((self.now)())),
538            ("action", Value::from(action)),
539            ("name", Value::from(name)),
540            ("caller_task_id", caller.into()),
541        ];
542        let outcome = if kind == "skills.rollback" {
543            code.rollback(payload).map(|result| {
544                let mut record = base.clone();
545                record.extend([
546                    ("version", result["rolledBack"].clone()),
547                    ("status", "rolled_back".into()),
548                    ("active", result["active"].clone()),
549                ]);
550                (object(record), result)
551            })
552        } else {
553            let kind = if kind == "skills.propose_policy" {
554                CodeSkillKind::Policy
555            } else {
556                CodeSkillKind::Code
557            };
558            code.propose(kind, payload, signal).map(|result| {
559                let mut record = base.clone();
560                record.extend([
561                    ("version", result["version"].clone()),
562                    ("status", result["status"].clone()),
563                    ("secretCheck", result["secretCheck"].clone()),
564                ]);
565                if let Some(test) = result["test"].as_object() {
566                    let tests = test.get("tests").and_then(Value::as_array).cloned().unwrap_or_default();
567                    let failed: Vec<Value> = tests
568                        .iter()
569                        .filter(|item| item["ok"] != true)
570                        .map(|item| item["name"].clone())
571                        .collect();
572                    let mut summary = vec![
573                        ("passed", test.get("passed").cloned().unwrap_or(Value::Null)),
574                        ("tests", tests.len().into()),
575                        ("failed", failed.into()),
576                    ];
577                    if let Some(error) = test.get("error").and_then(Value::as_str).filter(|e| !e.is_empty()) {
578                        summary.push(("error", jsrt::utf16::head(error, 500).into()));
579                    }
580                    record.push(("test", object(summary)));
581                }
582                (object(record), result)
583            })
584        };
585        let (record, result) = match outcome {
586            Ok(done) => (done.0, Ok(done.1)),
587            Err(error) => {
588                let mut record = base;
589                record.extend([
590                    ("version", Value::Null),
591                    ("status", "failed".into()),
592                    ("error", jsrt::utf16::head(&error, 500).into()),
593                ]);
594                (object(record), Err(error))
595            }
596        };
597        {
598            let _exclusive = jsrt::sync::lock(&self.exclusive);
599            self.mutate(|document| append(document, "code", record))?;
600        }
601        result
602    }
603
604    fn select(&self, payload: &Map<String, Value>, caller: Option<&str>) -> Result<Value, String> {
605        kernel::ops::fields("skills.select", payload)?;
606        let query = jsrt::payload::nonempty_string(payload.get("query"), "query")?;
607        if jsrt::utf16::len(&query) > MAX_QUERY_CHARS {
608            return Err(format!("query must be at most {MAX_QUERY_CHARS} characters"));
609        }
610        let limit = match payload.get("limit") {
611            None => 5,
612            Some(value) => jsrt::number::safe_integer(value)
613                .filter(|limit| (1..=50).contains(limit) && value.is_number())
614                .ok_or("limit must be an integer between 1 and 50")?,
615        };
616        let snapshot = self.current()?;
617        let terms = query_terms(&query);
618        let mut considered = Map::new();
619        let mut excluded = Vec::new();
620        let mut scored = Vec::new();
621        let mut ordered: Vec<&Skill> = snapshot.skills.iter().collect();
622        ordered.sort_by(|a, b| jsrt::collate::locale_compare(&a.name, &b.name));
623        for skill in ordered {
624            considered.insert(skill.name.clone(), skill.version.clone().into());
625            if !skill.invocable {
626                excluded.push(json!({"name": skill.name, "version": skill.version, "reason": "not_invocable"}));
627                continue;
628            }
629            if let Some(candidate) = score(skill, &terms, &query) {
630                scored.push(candidate);
631            }
632        }
633        scored.sort_by(|a, b| {
634            b["score"]
635                .as_i64()
636                .cmp(&a["score"].as_i64())
637                .then_with(|| a["name"].as_str().cmp(&b["name"].as_str()))
638        });
639        scored.truncate(limit as usize);
640        let chosen: Vec<Value> = scored
641            .iter()
642            .map(|candidate| json!({"name": candidate["name"], "version": candidate["version"]}))
643            .collect();
644        let decision = json!({
645            "id": jsrt::random::uuid_v4(),
646            "at": (self.now)(),
647            "query": query,
648            "terms": terms,
649            "caller_task_id": caller,
650            "catalog_generation": snapshot.generation,
651            "considered": considered,
652            "excluded": excluded,
653            "candidates": scored,
654            "chosen": chosen,
655        });
656        let _exclusive = jsrt::sync::lock(&self.exclusive);
657        self.mutate(|document| append(document, "decisions", decision.clone()))?;
658        Ok(decision)
659    }
660
661    fn load(&self, payload: &Map<String, Value>, caller: Option<&str>) -> Result<Value, String> {
662        kernel::ops::fields("skills.load", payload)?;
663        let name = jsrt::payload::nonempty_string(payload.get("name"), "name")?;
664        let version = match payload.get("version") {
665            None => None,
666            value => Some(version_string(value)?),
667        };
668        let snapshot = self.current()?;
669        let skill = Self::pinned(&snapshot, &name, version.as_deref())?;
670        let id = jsrt::random::uuid_v4();
671        let context_chars = jsrt::utf16::len(&skill.content);
672        let record = json!({"id": id, "at": (self.now)(), "name": name, "version": skill.version,
673            "caller_task_id": caller, "context_chars": context_chars});
674        {
675            let _exclusive = jsrt::sync::lock(&self.exclusive);
676            self.mutate(|document| append(document, "loads", record))?;
677        }
678        Ok(json!({
679            "load_id": id,
680            "name": name,
681            "version": skill.version,
682            "description": skill.description,
683            "invocable": skill.invocable,
684            "content": skill.content,
685            "context_chars": context_chars,
686            "ignored_capability_requests": skill.ignored,
687        }))
688    }
689}
690
691impl crate::ApiModule for SkillsModule {
692    fn prefixes(&self) -> &[&str] {
693        &["skills."]
694    }
695
696    fn start(&self, _host: &dyn crate::TaskHost) -> Result<(), String> {
697        SkillsModule::start(self)
698    }
699
700    fn handle(&self, request: &crate::Request<'_>) -> Result<Value, String> {
701        SkillsModule::handle_with_host(
702            self,
703            request.kind,
704            request.payload,
705            request.caller_task,
706            request.host,
707            request.signal,
708        )
709    }
710}