1use async_trait::async_trait;
2use ml_runtime_common::{CancellationToken, RuntimeError, RuntimeResult};
3use reqwest::Method;
4use serde::{Deserialize, Serialize};
5use serde_json::{json, Value};
6use std::{
7 collections::BTreeMap,
8 fs,
9 path::Path,
10 path::PathBuf,
11 process::Stdio,
12 sync::Arc,
13 time::{SystemTime, UNIX_EPOCH},
14};
15use tokio::{
16 process::Command,
17 time::{timeout, Duration},
18};
19
20#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
21pub struct Capability {
22 pub id: String,
23 pub version: String,
24 pub category: String,
25 pub description: String,
26 pub input_schema: Value,
27 pub output_schema: Value,
28 pub requirements: Vec<String>,
29 pub execution_targets: Vec<String>,
30 pub availability: bool,
31 pub platform: String,
32 pub backend: String,
33 pub local: bool,
34 pub remote: bool,
35 pub resource_requirements: Vec<String>,
36}
37
38#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
39pub struct CapabilityPackageManifest {
40 pub package: PackageManifest,
41 pub provider: ProviderManifest,
42 pub capabilities: Vec<PackageCapability>,
43}
44
45#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
46pub struct PackageManifest {
47 pub id: String,
48 pub version: String,
49 pub runtime: String,
50}
51
52#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
53pub struct ProviderManifest {
54 pub id: String,
55 pub version: String,
56 #[serde(default)]
57 pub execution_targets: Vec<String>,
58 #[serde(default)]
59 pub platforms: Vec<String>,
60 #[serde(default)]
61 pub backends: Vec<String>,
62 #[serde(default)]
63 pub configuration: Vec<String>,
64 #[serde(default)]
65 pub dependencies: Vec<String>,
66}
67
68#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
69pub struct PackageCapability {
70 pub id: String,
71 pub version: String,
72 #[serde(default)]
73 pub execution_targets: Vec<String>,
74 #[serde(default)]
75 pub platforms: Vec<String>,
76 #[serde(default)]
77 pub backends: Vec<String>,
78 #[serde(default)]
79 pub configuration: Vec<String>,
80 #[serde(default)]
81 pub dependencies: Vec<String>,
82}
83
84impl CapabilityPackageManifest {
85 pub fn validate(&self) -> RuntimeResult<()> {
86 if self.package.id.trim().is_empty()
87 || self.package.version.trim().is_empty()
88 || self.package.runtime.trim().is_empty()
89 || self.provider.id.trim().is_empty()
90 || self.provider.version.trim().is_empty()
91 {
92 return Err(RuntimeError::InvalidRequest {
93 reason: "package and provider identity, version, and runtime are required"
94 .to_owned(),
95 });
96 }
97 if self.capabilities.is_empty()
98 || self.capabilities.iter().any(|capability| {
99 capability.id.trim().is_empty() || capability.version.trim().is_empty()
100 })
101 {
102 return Err(RuntimeError::InvalidRequest {
103 reason: "at least one capability with an id and version is required".to_owned(),
104 });
105 }
106 if !Self::runtime_requirement_satisfied(&self.package.runtime, crate::VERSION) {
107 return Err(RuntimeError::InvalidRequest {
108 reason: format!(
109 "provider requires runtime {}, current runtime is {}",
110 self.package.runtime,
111 crate::VERSION
112 ),
113 });
114 }
115 Ok(())
116 }
117
118 pub fn from_path(path: impl AsRef<Path>) -> RuntimeResult<Self> {
119 let path = path.as_ref();
120 let contents = fs::read_to_string(path).map_err(|error| RuntimeError::Execution {
121 operation: "read provider manifest".to_owned(),
122 reason: error.to_string(),
123 })?;
124 let manifest: Self =
125 toml::from_str(&contents).map_err(|error| RuntimeError::InvalidRequest {
126 reason: format!("invalid provider manifest {}: {error}", path.display()),
127 })?;
128 manifest.validate()?;
129 Ok(manifest)
130 }
131
132 fn runtime_requirement_satisfied(requirement: &str, current: &str) -> bool {
133 let Some(required) = requirement.strip_prefix(">=") else {
134 return requirement == current || requirement == "*" || requirement.is_empty();
135 };
136 Self::version_key(current) >= Self::version_key(required)
137 }
138
139 fn version_key(version: &str) -> (u64, u64, u64) {
140 let mut parts = version
141 .trim()
142 .trim_start_matches('v')
143 .split('.')
144 .map(|part| part.parse::<u64>().unwrap_or(0));
145 (
146 parts.next().unwrap_or(0),
147 parts.next().unwrap_or(0),
148 parts.next().unwrap_or(0),
149 )
150 }
151}
152
153#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
154pub struct LocalProviderPackage {
155 pub path: PathBuf,
156 pub manifest: CapabilityPackageManifest,
157 pub binary: Option<PathBuf>,
158}
159
160impl LocalProviderPackage {
161 pub fn load(path: impl Into<PathBuf>) -> RuntimeResult<Self> {
162 let path = path.into();
163 let manifest = CapabilityPackageManifest::from_path(path.join("manifest.toml"))?;
164 let binary = ["provider", "provider.so", "provider.dylib", "provider.dll"]
165 .iter()
166 .map(|name| path.join(name))
167 .find(|candidate| candidate.is_file());
168 Ok(Self {
169 path,
170 manifest,
171 binary,
172 })
173 }
174}
175
176#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
177pub enum AvailabilityState {
178 Registered,
179 Available,
180 Ready,
181 Healthy,
182}
183
184#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
185pub struct CapabilityAvailability {
186 pub state: AvailabilityState,
187 pub reason: String,
188}
189
190#[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq, Eq)]
191pub struct ResolutionConstraints {
192 pub local_only: bool,
193 pub remote_allowed: bool,
194 pub provider: Option<String>,
195 pub backend: Option<String>,
196 pub platform: Option<String>,
197 pub maximum_latency_ms: Option<u64>,
198 pub maximum_memory_bytes: Option<u64>,
199 pub network_required: bool,
200 pub network_forbidden: bool,
201 pub filesystem_scope: Option<PathBuf>,
202}
203
204#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
205pub struct ResolutionCandidate {
206 pub provider: String,
207 pub implementation: String,
208 pub version: String,
209 pub available: bool,
210 pub local: bool,
211 pub requirements_satisfied: Vec<String>,
212 pub requirements_rejected: Vec<String>,
213 pub reason: String,
214}
215
216#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
217pub struct CapabilityResolution {
218 pub capability: String,
219 pub provider: String,
220 pub implementation: String,
221 pub target: String,
222 pub version: String,
223 pub candidates: Vec<ResolutionCandidate>,
224 pub reason: String,
225}
226
227#[async_trait]
228pub trait CapabilityProvider: Send + Sync {
229 fn id(&self) -> &str;
230 fn version(&self) -> &str;
231 fn capabilities(&self) -> Vec<Capability>;
232 fn availability(&self) -> CapabilityAvailability;
233 fn descriptor(&self) -> ProviderDescriptor {
234 ProviderDescriptor {
235 id: self.id().to_owned(),
236 version: self.version().to_owned(),
237 package: None,
238 }
239 }
240 async fn execute(&self, request: ExecutionRequest) -> RuntimeResult<ExecutionResult>;
241}
242
243#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
244pub struct ProviderDescriptor {
245 pub id: String,
246 pub version: String,
247 pub package: Option<String>,
248}
249
250pub struct BuiltinCapabilityProvider;
251
252#[async_trait]
253impl CapabilityProvider for BuiltinCapabilityProvider {
254 fn id(&self) -> &str {
255 "builtin"
256 }
257
258 fn version(&self) -> &str {
259 "1"
260 }
261
262 fn capabilities(&self) -> Vec<Capability> {
263 catalog()
264 }
265
266 fn availability(&self) -> CapabilityAvailability {
267 CapabilityAvailability {
268 state: AvailabilityState::Available,
269 reason: "built-in capability implementation".to_owned(),
270 }
271 }
272
273 async fn execute(&self, request: ExecutionRequest) -> RuntimeResult<ExecutionResult> {
274 execute(request, None).await
275 }
276}
277
278pub struct ManifestCapabilityProvider {
279 package: LocalProviderPackage,
280 capabilities: Vec<Capability>,
281}
282
283impl ManifestCapabilityProvider {
284 pub fn new(package: LocalProviderPackage) -> Self {
285 let manifest = &package.manifest;
286 let capabilities = manifest
287 .capabilities
288 .iter()
289 .map(|capability| Capability {
290 id: capability.id.clone(),
291 version: capability.version.clone(),
292 category: capability
293 .id
294 .split('.')
295 .next()
296 .unwrap_or("runtime")
297 .to_owned(),
298 description: format!("Provided by {}", manifest.provider.id),
299 input_schema: json!({"type": "object"}),
300 output_schema: json!({"type": "object"}),
301 requirements: Vec::new(),
302 execution_targets: if capability.execution_targets.is_empty() {
303 manifest.provider.execution_targets.clone()
304 } else {
305 capability.execution_targets.clone()
306 },
307 availability: true,
308 platform: capability
309 .platforms
310 .first()
311 .or_else(|| manifest.provider.platforms.first())
312 .cloned()
313 .unwrap_or_else(|| "any".to_owned()),
314 backend: capability
315 .backends
316 .first()
317 .or_else(|| manifest.provider.backends.first())
318 .cloned()
319 .unwrap_or_else(|| "external".to_owned()),
320 local: true,
321 remote: false,
322 resource_requirements: capability
323 .configuration
324 .iter()
325 .chain(capability.dependencies.iter())
326 .cloned()
327 .collect(),
328 })
329 .collect();
330 Self {
331 package,
332 capabilities,
333 }
334 }
335
336 pub fn package(&self) -> &LocalProviderPackage {
337 &self.package
338 }
339}
340
341#[async_trait]
342impl CapabilityProvider for ManifestCapabilityProvider {
343 fn id(&self) -> &str {
344 &self.package.manifest.provider.id
345 }
346
347 fn version(&self) -> &str {
348 &self.package.manifest.provider.version
349 }
350
351 fn capabilities(&self) -> Vec<Capability> {
352 self.capabilities.clone()
353 }
354
355 fn availability(&self) -> CapabilityAvailability {
356 CapabilityAvailability {
357 state: AvailabilityState::Available,
358 reason: "manifest validated; provider execution remains explicit".to_owned(),
359 }
360 }
361
362 fn descriptor(&self) -> ProviderDescriptor {
363 ProviderDescriptor {
364 id: self.id().to_owned(),
365 version: self.version().to_owned(),
366 package: Some(self.package.path.display().to_string()),
367 }
368 }
369
370 async fn execute(&self, _request: ExecutionRequest) -> RuntimeResult<ExecutionResult> {
371 Err(RuntimeError::ProviderUnavailable {
372 provider: self.id().to_owned(),
373 reason: ": provider binary loading is not enabled by manifest discovery".to_owned(),
374 })
375 }
376}
377
378#[derive(Clone, Default)]
379pub struct CapabilityRegistry {
380 providers: BTreeMap<String, Arc<dyn CapabilityProvider>>,
381}
382
383impl CapabilityRegistry {
384 pub fn new() -> Self {
385 Self::default()
386 }
387
388 pub fn with_builtins() -> Self {
389 let mut registry = Self::new();
390 registry.register(BuiltinCapabilityProvider);
391 registry
392 }
393
394 pub fn register<P>(&mut self, provider: P)
395 where
396 P: CapabilityProvider + 'static,
397 {
398 self.providers
399 .insert(provider.id().to_owned(), Arc::new(provider));
400 }
401
402 pub fn register_arc(&mut self, provider: Arc<dyn CapabilityProvider>) {
403 self.providers.insert(provider.id().to_owned(), provider);
404 }
405
406 pub fn unregister(&mut self, provider: &str) -> Option<Arc<dyn CapabilityProvider>> {
407 self.providers.remove(provider)
408 }
409
410 pub fn provider(&self, provider: &str) -> Option<&Arc<dyn CapabilityProvider>> {
411 self.providers.get(provider)
412 }
413
414 pub fn providers(&self) -> Vec<Arc<dyn CapabilityProvider>> {
415 self.providers.values().cloned().collect()
416 }
417
418 pub fn discover_local_packages(
419 root: impl AsRef<Path>,
420 ) -> RuntimeResult<Vec<LocalProviderPackage>> {
421 let root = root.as_ref();
422 if !root.is_dir() {
423 return Ok(Vec::new());
424 }
425 let mut packages = Vec::new();
426 for entry in fs::read_dir(root).map_err(|error| RuntimeError::Execution {
427 operation: "discover providers".to_owned(),
428 reason: error.to_string(),
429 })? {
430 let path = entry
431 .map_err(|error| RuntimeError::Execution {
432 operation: "discover providers".to_owned(),
433 reason: error.to_string(),
434 })?
435 .path();
436 if path.is_dir() && path.join("manifest.toml").is_file() {
437 packages.push(LocalProviderPackage::load(path)?);
438 }
439 }
440 packages.sort_by(|left, right| left.manifest.provider.id.cmp(&right.manifest.provider.id));
441 Ok(packages)
442 }
443
444 pub fn load_local_packages(&mut self, root: impl AsRef<Path>) -> RuntimeResult<Vec<String>> {
445 let packages = Self::discover_local_packages(root)?;
446 let ids = packages
447 .iter()
448 .map(|package| package.manifest.provider.id.clone())
449 .collect();
450 for package in packages {
451 self.register(ManifestCapabilityProvider::new(package));
452 }
453 Ok(ids)
454 }
455
456 pub fn get(&self, capability: &str) -> Option<Capability> {
457 self.list().into_iter().find(|item| item.id == capability)
458 }
459
460 pub fn list(&self) -> Vec<Capability> {
461 let mut capabilities = BTreeMap::new();
462 for provider in self.providers.values() {
463 for capability in provider.capabilities() {
464 capabilities
465 .entry(capability.id.clone())
466 .or_insert(capability);
467 }
468 }
469 capabilities.into_values().collect()
470 }
471
472 pub fn find(&self, query: &str) -> Vec<Capability> {
473 self.list()
474 .into_iter()
475 .filter(|capability| {
476 capability.id.contains(query)
477 || capability.category.contains(query)
478 || capability.description.contains(query)
479 })
480 .collect()
481 }
482
483 fn implementations(&self, capability: &str) -> Vec<Arc<dyn CapabilityProvider>> {
484 self.providers
485 .values()
486 .filter(|provider| {
487 provider
488 .capabilities()
489 .iter()
490 .any(|item| item.id == capability)
491 })
492 .cloned()
493 .collect()
494 }
495
496 pub fn resolve(
497 &self,
498 capability: &str,
499 constraints: &ResolutionConstraints,
500 ) -> RuntimeResult<CapabilityResolution> {
501 let mut candidates = Vec::new();
502 for provider in self.implementations(capability) {
503 let metadata = provider
504 .capabilities()
505 .into_iter()
506 .find(|item| item.id == capability)
507 .expect("provider capability disappeared");
508 let availability = provider.availability();
509 let mut satisfied = Vec::new();
510 let mut rejected = Vec::new();
511 if availability.state != AvailabilityState::Registered && metadata.availability {
512 satisfied.push("available".to_owned());
513 } else {
514 rejected.push("provider unavailable".to_owned());
515 }
516 if constraints.local_only && !metadata.local {
517 rejected.push("local_only".to_owned());
518 } else if metadata.local {
519 satisfied.push("local".to_owned());
520 }
521 if !constraints.remote_allowed && !metadata.local {
522 rejected.push("remote forbidden".to_owned());
523 }
524 if constraints.network_required && !metadata.remote {
525 rejected.push("network required".to_owned());
526 }
527 if constraints.network_forbidden && metadata.remote {
528 rejected.push("network forbidden".to_owned());
529 }
530 if constraints.filesystem_scope.is_some() && !metadata.category.eq("filesystem") {
531 rejected
532 .push("filesystem scope applies only to filesystem capabilities".to_owned());
533 }
534 if constraints.maximum_latency_ms.is_some() {
535 rejected.push("latency is not declared by implementation".to_owned());
536 }
537 if constraints.maximum_memory_bytes.is_some() {
538 rejected.push("memory usage is not declared by implementation".to_owned());
539 }
540 if let Some(expected) = &constraints.provider {
541 if provider.id() != expected {
542 rejected.push(format!("provider != {expected}"));
543 }
544 }
545 if let Some(expected) = &constraints.backend {
546 if metadata.backend != *expected {
547 rejected.push(format!("backend != {expected}"));
548 }
549 }
550 if let Some(expected) = &constraints.platform {
551 if metadata.platform != *expected {
552 rejected.push(format!("platform != {expected}"));
553 }
554 }
555 let available = rejected.is_empty();
556 candidates.push(ResolutionCandidate {
557 provider: provider.id().to_owned(),
558 implementation: metadata.backend.clone(),
559 version: provider.version().to_owned(),
560 available,
561 local: metadata.local,
562 requirements_satisfied: satisfied,
563 requirements_rejected: rejected,
564 reason: if available {
565 "satisfies constraints".to_owned()
566 } else {
567 "rejected by constraints".to_owned()
568 },
569 });
570 }
571 let selected = candidates
572 .iter()
573 .find(|candidate| candidate.available)
574 .ok_or_else(|| RuntimeError::CapabilityMismatch {
575 reason: format!("no available provider satisfies constraints for {capability}"),
576 })?;
577 Ok(CapabilityResolution {
578 capability: capability.to_owned(),
579 provider: selected.provider.clone(),
580 implementation: selected.implementation.clone(),
581 target: if selected.local { "local" } else { "remote" }.to_owned(),
582 version: selected.version.clone(),
583 candidates,
584 reason: "selected first available provider in registry order".to_owned(),
585 })
586 }
587}
588
589#[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq, Eq)]
590pub struct CapabilityLimits {
591 pub timeout_ms: Option<u64>,
592 pub max_input_bytes: Option<usize>,
593 pub max_output_bytes: Option<usize>,
594}
595
596#[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq, Eq)]
597pub struct CapabilityPolicy {
598 pub require_authorization: bool,
599 pub filesystem_root: Option<PathBuf>,
600 pub network: bool,
601}
602
603#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
604pub struct ExecutionRequest {
605 pub capability: String,
606 pub input: Value,
607 pub context: Value,
608 pub policy: CapabilityPolicy,
609 pub correlation: String,
610 pub limits: CapabilityLimits,
611 #[serde(skip)]
612 pub cancellation: Option<CancellationToken>,
613}
614
615impl ExecutionRequest {
616 pub fn new(capability: impl Into<String>, input: Value) -> Self {
617 Self {
618 capability: capability.into(),
619 input,
620 context: Value::Null,
621 policy: CapabilityPolicy::default(),
622 correlation: format!("cap-{}", unique_id()),
623 limits: CapabilityLimits::default(),
624 cancellation: None,
625 }
626 }
627}
628
629#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
630pub struct CapabilityExecutionMetadata {
631 pub capability: String,
632 pub version: String,
633 pub target: String,
634 pub correlation: String,
635 pub started_at_ms: u128,
636 pub ended_at_ms: u128,
637 pub duration_ms: u128,
638 pub success: bool,
639}
640
641#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
642pub struct ExecutionResult {
643 pub output: Value,
644 pub evidence: Value,
645 pub execution_metadata: CapabilityExecutionMetadata,
646}
647
648#[async_trait]
649pub trait CapabilityAuthorizer: Send + Sync {
650 async fn authorize(
651 &self,
652 request: &ExecutionRequest,
653 capability: &Capability,
654 ) -> RuntimeResult<()>;
655}
656
657pub fn catalog() -> Vec<Capability> {
658 [
659 ("intelligence.generate", "Intelligence generation"),
660 ("intelligence.embed", "Intelligence embeddings"),
661 ("filesystem.read", "Read a bounded local file"),
662 ("filesystem.list", "List a local directory"),
663 ("filesystem.write", "Write a bounded local file"),
664 ("process.spawn", "Spawn a constrained local process"),
665 ("network.http", "Perform an explicit HTTP request"),
666 ("git.status", "Inspect repository status"),
667 ("git.diff", "Inspect repository diff"),
668 ("data.parse", "Parse structured data"),
669 ]
670 .into_iter()
671 .map(|(id, description)| {
672 let category = id.split('.').next().unwrap_or("runtime").to_owned();
673 let sensitive = matches!(id, "filesystem.write" | "process.spawn" | "network.http");
674 Capability {
675 id: id.to_owned(),
676 version: "1".to_owned(),
677 category,
678 description: description.to_owned(),
679 input_schema: json!({"type": "object"}),
680 output_schema: json!({"type": "object"}),
681 requirements: if sensitive {
682 vec!["authorization".to_owned()]
683 } else {
684 Vec::new()
685 },
686 execution_targets: vec!["local".to_owned()],
687 availability: true,
688 platform: std::env::consts::OS.to_owned(),
689 backend: "builtin".to_owned(),
690 local: true,
691 remote: false,
692 resource_requirements: vec!["explicit limits".to_owned()],
693 }
694 })
695 .collect()
696}
697
698pub fn find(id: &str) -> Option<Capability> {
699 catalog().into_iter().find(|capability| capability.id == id)
700}
701
702pub async fn execute(
703 request: ExecutionRequest,
704 authorizer: Option<&dyn CapabilityAuthorizer>,
705) -> RuntimeResult<ExecutionResult> {
706 let capability = find(&request.capability).ok_or_else(|| RuntimeError::CapabilityMismatch {
707 reason: format!("unknown capability {}", request.capability),
708 })?;
709 if request.policy.require_authorization || !capability.requirements.is_empty() {
710 let authorizer = authorizer.ok_or_else(|| RuntimeError::Execution {
711 operation: request.capability.clone(),
712 reason: "authorization required".to_owned(),
713 })?;
714 authorizer.authorize(&request, &capability).await?;
715 }
716 let started = now_ms();
717 let operation = run(&request, &capability);
718 let result = operation.await;
719 let ended = now_ms();
720 let success = result.is_ok();
721 let output = result?;
722 Ok(ExecutionResult {
723 output,
724 evidence: json!({"capability": capability.id, "target": "local"}),
725 execution_metadata: CapabilityExecutionMetadata {
726 capability: capability.id,
727 version: capability.version,
728 target: "local".to_owned(),
729 correlation: request.correlation,
730 started_at_ms: started,
731 ended_at_ms: ended,
732 duration_ms: ended.saturating_sub(started),
733 success,
734 },
735 })
736}
737
738async fn run(request: &ExecutionRequest, capability: &Capability) -> RuntimeResult<Value> {
739 let timeout_ms = request.limits.timeout_ms;
740 let cancellation = request.cancellation.clone();
741 let operation = async {
742 match capability.id.as_str() {
743 "filesystem.read" => filesystem_read(request),
744 "filesystem.list" => filesystem_list(request),
745 "filesystem.write" => filesystem_write(request),
746 "process.spawn" => process_spawn(request).await,
747 "network.http" => network_http(request).await,
748 "git.status" | "git.diff" => git_command(request, &capability.id).await,
749 "data.parse" => data_parse(request),
750 _ => Err(RuntimeError::CapabilityMismatch {
751 reason: format!("{} requires an ML provider", capability.id),
752 }),
753 }
754 };
755 let result = if let Some(token) = cancellation {
756 tokio::select! {
757 _ = token.cancelled() => Err(RuntimeError::Cancelled),
758 result = operation => result,
759 }
760 } else if let Some(ms) = timeout_ms {
761 timeout(Duration::from_millis(ms), operation)
762 .await
763 .map_err(|_| RuntimeError::Timeout {
764 operation: request.capability.clone(),
765 })?
766 } else {
767 operation.await
768 }?;
769 Ok(result)
770}
771
772fn path(request: &ExecutionRequest) -> RuntimeResult<PathBuf> {
773 let value = request
774 .input
775 .get("path")
776 .and_then(Value::as_str)
777 .ok_or_else(|| RuntimeError::InvalidInput {
778 reason: "path is required".to_owned(),
779 })?;
780 let path = PathBuf::from(value);
781 if let Some(root) = &request.policy.filesystem_root {
782 let candidate = std::fs::canonicalize(&path).map_err(|error| RuntimeError::Execution {
783 operation: "filesystem".to_owned(),
784 reason: error.to_string(),
785 })?;
786 let root = std::fs::canonicalize(root).map_err(|error| RuntimeError::Execution {
787 operation: "filesystem".to_owned(),
788 reason: error.to_string(),
789 })?;
790 if !candidate.starts_with(root) {
791 return Err(RuntimeError::CapabilityMismatch {
792 reason: "filesystem path is outside the configured scope".to_owned(),
793 });
794 }
795 }
796 Ok(path)
797}
798
799fn filesystem_read(request: &ExecutionRequest) -> RuntimeResult<Value> {
800 let path = path(request)?;
801 let data = std::fs::read(&path).map_err(|error| RuntimeError::Execution {
802 operation: "filesystem.read".to_owned(),
803 reason: error.to_string(),
804 })?;
805 if request
806 .limits
807 .max_output_bytes
808 .is_some_and(|limit| data.len() > limit)
809 {
810 return Err(RuntimeError::ResourceLimit {
811 reason: "filesystem output exceeds max_output_bytes".to_owned(),
812 });
813 }
814 Ok(json!({"path": path, "data": String::from_utf8_lossy(&data), "bytes": data.len()}))
815}
816
817fn filesystem_list(request: &ExecutionRequest) -> RuntimeResult<Value> {
818 let path = path(request)?;
819 let entries = std::fs::read_dir(&path)
820 .map_err(|error| RuntimeError::Execution {
821 operation: "filesystem.list".to_owned(),
822 reason: error.to_string(),
823 })?
824 .filter_map(Result::ok)
825 .map(|entry| json!({"path": entry.path(), "name": entry.file_name().to_string_lossy()}))
826 .collect::<Vec<_>>();
827 Ok(json!({"path": path, "entries": entries}))
828}
829
830fn filesystem_write(request: &ExecutionRequest) -> RuntimeResult<Value> {
831 let path = path(request)?;
832 let data = request
833 .input
834 .get("data")
835 .and_then(Value::as_str)
836 .ok_or_else(|| RuntimeError::InvalidInput {
837 reason: "data is required".to_owned(),
838 })?;
839 if request
840 .limits
841 .max_input_bytes
842 .is_some_and(|limit| data.len() > limit)
843 {
844 return Err(RuntimeError::ResourceLimit {
845 reason: "filesystem input exceeds max_input_bytes".to_owned(),
846 });
847 }
848 std::fs::write(&path, data).map_err(|error| RuntimeError::Execution {
849 operation: "filesystem.write".to_owned(),
850 reason: error.to_string(),
851 })?;
852 Ok(json!({"path": path, "bytes": data.len()}))
853}
854
855async fn process_spawn(request: &ExecutionRequest) -> RuntimeResult<Value> {
856 let command = request
857 .input
858 .get("command")
859 .and_then(Value::as_str)
860 .ok_or_else(|| RuntimeError::InvalidInput {
861 reason: "command is required".to_owned(),
862 })?;
863 let args = request
864 .input
865 .get("arguments")
866 .and_then(Value::as_array)
867 .cloned()
868 .unwrap_or_default();
869 let mut child = Command::new(command);
870 child
871 .args(args.iter().filter_map(Value::as_str))
872 .stdout(Stdio::piped())
873 .stderr(Stdio::piped());
874 if let Some(cwd) = request
875 .input
876 .get("working_directory")
877 .and_then(Value::as_str)
878 {
879 child.current_dir(cwd);
880 }
881 let output = timeout(
882 Duration::from_millis(request.limits.timeout_ms.unwrap_or(30_000)),
883 child.output(),
884 )
885 .await
886 .map_err(|_| RuntimeError::Timeout {
887 operation: "process.spawn".to_owned(),
888 })?
889 .map_err(|error| RuntimeError::Execution {
890 operation: "process.spawn".to_owned(),
891 reason: error.to_string(),
892 })?;
893 if request
894 .limits
895 .max_output_bytes
896 .is_some_and(|limit| output.stdout.len() + output.stderr.len() > limit)
897 {
898 return Err(RuntimeError::ResourceLimit {
899 reason: "process output exceeds max_output_bytes".to_owned(),
900 });
901 }
902 Ok(
903 json!({"status": output.status.code(), "stdout": String::from_utf8_lossy(&output.stdout), "stderr": String::from_utf8_lossy(&output.stderr)}),
904 )
905}
906
907async fn network_http(request: &ExecutionRequest) -> RuntimeResult<Value> {
908 if !request.policy.network {
909 return Err(RuntimeError::CapabilityMismatch {
910 reason: "network access is not enabled by policy".to_owned(),
911 });
912 }
913 let method = request
914 .input
915 .get("method")
916 .and_then(Value::as_str)
917 .unwrap_or("GET")
918 .parse::<Method>()
919 .map_err(|_| RuntimeError::InvalidInput {
920 reason: "invalid HTTP method".to_owned(),
921 })?;
922 let url = request
923 .input
924 .get("url")
925 .and_then(Value::as_str)
926 .ok_or_else(|| RuntimeError::InvalidInput {
927 reason: "url is required".to_owned(),
928 })?;
929 let mut builder = reqwest::Client::new().request(method, url);
930 if let Some(headers) = request.input.get("headers").and_then(Value::as_object) {
931 for (name, value) in headers {
932 if let Some(value) = value.as_str() {
933 builder = builder.header(name, value);
934 }
935 }
936 }
937 if let Some(body) = request.input.get("body") {
938 builder = builder.json(body);
939 }
940 let response = builder
941 .send()
942 .await
943 .map_err(|error| RuntimeError::Transport {
944 provider: "http".to_owned(),
945 reason: error.to_string(),
946 })?;
947 let status = response.status().as_u16();
948 let body = response
949 .text()
950 .await
951 .map_err(|error| RuntimeError::Transport {
952 provider: "http".to_owned(),
953 reason: error.to_string(),
954 })?;
955 Ok(json!({"status": status, "body": body}))
956}
957
958async fn git_command(request: &ExecutionRequest, capability: &str) -> RuntimeResult<Value> {
959 let cwd = request
960 .input
961 .get("repository")
962 .and_then(Value::as_str)
963 .unwrap_or(".");
964 let argument = if capability == "git.status" {
965 "status"
966 } else {
967 "diff"
968 };
969 let output = Command::new("git")
970 .args(["-C", cwd, argument])
971 .output()
972 .await
973 .map_err(|error| RuntimeError::Execution {
974 operation: capability.to_owned(),
975 reason: error.to_string(),
976 })?;
977 Ok(
978 json!({"status": output.status.code(), "stdout": String::from_utf8_lossy(&output.stdout), "stderr": String::from_utf8_lossy(&output.stderr)}),
979 )
980}
981
982fn data_parse(request: &ExecutionRequest) -> RuntimeResult<Value> {
983 let format = request
984 .input
985 .get("format")
986 .and_then(Value::as_str)
987 .unwrap_or("json");
988 let data = request
989 .input
990 .get("data")
991 .and_then(Value::as_str)
992 .ok_or_else(|| RuntimeError::InvalidInput {
993 reason: "data is required".to_owned(),
994 })?;
995 match format {
996 "json" => serde_json::from_str(data).map_err(|error| RuntimeError::InvalidInput {
997 reason: error.to_string(),
998 }),
999 "csv" => Ok(Value::Array(
1000 data.lines()
1001 .map(|line| {
1002 Value::Array(
1003 line.split(',')
1004 .map(|value| Value::String(value.trim().to_owned()))
1005 .collect(),
1006 )
1007 })
1008 .collect(),
1009 )),
1010 _ => Err(RuntimeError::CapabilityMismatch {
1011 reason: format!("unsupported data format {format}"),
1012 }),
1013 }
1014}
1015
1016fn now_ms() -> u128 {
1017 SystemTime::now()
1018 .duration_since(UNIX_EPOCH)
1019 .unwrap_or_default()
1020 .as_millis()
1021}
1022fn unique_id() -> u128 {
1023 now_ms()
1024}
1025
1026#[cfg(test)]
1027mod tests {
1028 use super::*;
1029
1030 #[tokio::test]
1031 async fn discovers_and_executes_json_parse() {
1032 assert!(find("filesystem.read").is_some());
1033 let result = execute(
1034 ExecutionRequest::new(
1035 "data.parse",
1036 json!({"format": "json", "data": r#"{"ok":true}"#}),
1037 ),
1038 None,
1039 )
1040 .await
1041 .unwrap();
1042 assert_eq!(result.output["ok"], true);
1043 assert_eq!(result.execution_metadata.capability, "data.parse");
1044 }
1045
1046 #[tokio::test]
1047 async fn sensitive_capabilities_fail_closed_without_authorizer() {
1048 let error = execute(
1049 ExecutionRequest::new("process.spawn", json!({"command": "true"})),
1050 None,
1051 )
1052 .await
1053 .unwrap_err();
1054 assert!(matches!(error, RuntimeError::Execution { .. }));
1055 }
1056
1057 #[test]
1058 fn registry_resolves_and_explains_builtin_capabilities() {
1059 let registry = CapabilityRegistry::with_builtins();
1060 let result = registry
1061 .resolve("data.parse", &ResolutionConstraints::default())
1062 .unwrap();
1063 assert_eq!(result.provider, "builtin");
1064 assert_eq!(result.target, "local");
1065 assert_eq!(result.candidates.len(), 1);
1066 assert!(result.candidates[0]
1067 .requirements_satisfied
1068 .iter()
1069 .any(|requirement| requirement == "available"));
1070 }
1071
1072 #[test]
1073 fn registry_rejects_local_only_for_remote_capabilities() {
1074 let registry = CapabilityRegistry::with_builtins();
1075 let result = registry.resolve(
1076 "data.parse",
1077 &ResolutionConstraints {
1078 provider: Some("remote".to_owned()),
1079 ..ResolutionConstraints::default()
1080 },
1081 );
1082 assert!(matches!(
1083 result,
1084 Err(RuntimeError::CapabilityMismatch { .. })
1085 ));
1086 }
1087
1088 #[test]
1089 fn local_package_manifest_is_validated_and_discovered_without_execution() {
1090 let root = std::env::temp_dir().join(format!("ml-runtime-provider-{}", unique_id()));
1091 let package = root.join("example");
1092 std::fs::create_dir_all(&package).unwrap();
1093 std::fs::write(
1094 package.join("manifest.toml"),
1095 r#"
1096[package]
1097id = "example-capability"
1098version = "0.1.0"
1099runtime = ">=0.1.0"
1100[provider]
1101id = "example"
1102version = "0.1.0"
1103execution_targets = ["local"]
1104platforms = ["linux"]
1105backends = ["cpu"]
1106configuration = ["token"]
1107dependencies = ["network"]
1108[[capabilities]]
1109id = "example.run"
1110version = "1"
1111"#,
1112 )
1113 .unwrap();
1114 std::fs::write(package.join("provider"), b"not executed").unwrap();
1115
1116 let mut registry = CapabilityRegistry::new();
1117 assert_eq!(
1118 registry.load_local_packages(&root).unwrap(),
1119 vec!["example".to_owned()]
1120 );
1121 assert_eq!(registry.get("example.run").unwrap().backend, "cpu");
1122 assert_eq!(
1123 registry.provider("example").unwrap().availability().state,
1124 AvailabilityState::Available
1125 );
1126 let _ = std::fs::remove_dir_all(root);
1127 }
1128}