1use 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#[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 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
169fn 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#[derive(Debug, Clone)]
199pub struct PinnedSkill {
200 pub name: String,
201 pub version: String,
203 pub file_path: String,
204 pub content: String,
205}
206
207pub 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 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 *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 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 pub fn start(&self) -> Result<(), String> {
343 self.current().map(drop)
344 }
345
346 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 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 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 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 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 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 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}