Skip to main content

rust_ml_runtime/
capability.rs

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}