everruns_capability/lib.rs
1//! The neutral Everruns capability contract (EVE-873).
2//!
3//! One open identity/configuration contract shared by the `everruns`
4//! Framework, the hosted product composition, and integration crates:
5//!
6//! - [`CapabilityId`]: an open, string-based capability identifier with one
7//! validation rule set (character set, length, reserved namespace).
8//! - [`CapabilityRef`]: a reference to a capability implementation plus its
9//! per-agent JSON object configuration. This is the persisted attachment
10//! representation and the Framework activation value — the same bytes
11//! round-trip through application code, database rows, and worker
12//! resolution.
13//! - [`CapabilitySpec`] and the non-sealed [`IntoCapability`]: the open
14//! conversion seam application values use to become capability
15//! registrations.
16//! - [`Definition`] (feature `definition`): the code-defined capability
17//! authoring surface — typed tool handlers, schema metadata, structured
18//! execution errors — with no engine or host dependency.
19//! - [`CapabilityIdIndex`] and [`ActivationSet`]: canonical-id/alias
20//! bookkeeping and duplicate/collision rejection shared by registries.
21//!
22//! This crate deliberately depends on neither `everruns-core` nor
23//! `everruns-host`, and carries no Tokio, HTTP, SQLx, OpenAPI, inventory, or
24//! platform-record dependency. Third-party capability crates can depend on
25//! this crate alone; application authors normally consume the same types
26//! re-exported from `everruns`. Part of the [Everruns](https://everruns.com)
27//! ecosystem.
28//!
29//! # Example
30//!
31//! ```
32//! use everruns_capability::{CapabilityRef, CapabilitySpec, IntoCapability};
33//! use serde_json::json;
34//!
35//! struct VendorSearch {
36//! index: String,
37//! }
38//!
39//! impl IntoCapability for VendorSearch {
40//! fn into_capability(self) -> CapabilitySpec {
41//! CapabilityRef::new("vendor.search")
42//! .config(json!({ "index": self.index }))
43//! .into()
44//! }
45//! }
46//!
47//! let spec = VendorSearch { index: "prod".into() }.into_capability();
48//! assert_eq!(spec.capability_ref().id(), "vendor.search");
49//! ```
50
51#![deny(missing_docs)]
52
53mod error;
54mod id;
55mod reference;
56mod registry;
57mod spec;
58
59#[cfg(feature = "definition")]
60pub mod definition;
61
62pub use error::CapabilityError;
63pub use id::{
64 CapabilityId, PLUGIN_CAPABILITY_PREFIX, RESERVED_CAPABILITY_ID_NAMESPACE, is_plugin_capability,
65 parse_plugin_capability_id, plugin_capability_id, validate_capability_id,
66};
67pub use reference::{CapabilityRef, validate_capability_config};
68pub use registry::{ActivationSet, CapabilityIdIndex};
69pub use spec::{CapabilitySpec, CapabilitySpecParts, IntoCapability};
70
71#[cfg(feature = "definition")]
72pub use definition::Definition;
73
74// Dependency re-exports so downstream capability crates can align derive
75// macro paths (`#[serde(crate = "...")]`) without adding their own pins.
76pub use serde;
77pub use serde_json;
78
79#[cfg(feature = "definition")]
80pub use async_trait::async_trait;
81#[cfg(feature = "definition")]
82pub use schemars;