byob_plugins/
lib.rs

1//! Plugins: a folder with a `byob-plugin.json` that adds any mix of
2//!
3//! - **skills** (`skills/<name>/SKILL.md`, the Agent Skills format) → [`skills`],
4//!   [`UseSkillTool`], [`skills_prompt`];
5//! - **Python tools** (`tools[].run`) → [`python::PythonTool`];
6//! - **subagents** (`agents/*.md`, Claude Code's format) → [`agents`];
7//! - **slash commands** (`commands/*.md`, Claude Code's format) → [`commands`];
8//! - **connectors** (`mcpServers`, MCP) → [`connectors::ConnectorToolAdapter`] over the
9//!   [`connectors::Connector`] trait, which `byob-mcp`'s client implements.
10//!
11//! Typical use by the agent:
12//! 1. [`discover`] the plugin folders; show `errors` and each plugin's `problems`.
13//! 2. Reserve the built-in tool names in a [`ToolNames`], then add each active plugin's
14//!    [`python_tools`] and, per `mcpServers` entry, [`connector_tools`].
15//! 3. Add [`UseSkillTool`] over [`Discovery::skills`] and put [`skills_prompt`] and
16//!    [`Discovery::prompt`] in the system prompt.
17#![cfg_attr(not(test), deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable))]
18
19pub mod agents;
20pub mod authoring;
21pub mod commands;
22pub mod connectors;
23pub mod discover;
24pub mod manifest;
25pub mod mcp;
26pub mod names;
27pub mod python;
28pub mod skills;
29
30use std::collections::BTreeMap;
31use std::fmt;
32use std::path::PathBuf;
33
34pub use agents::{AgentDef, load_agents_dir, merge_agents, parse_agent};
35pub use commands::{Command, load_commands_dir, split_slash};
36pub use connectors::{
37    Connector, ConnectorContent, ConnectorDraft, ConnectorResult, ConnectorTool, ConnectorToolAdapter, connector_tools, connector_tools_from, parse_connector,
38};
39pub use discover::{Discovery, Plugin, PluginSources, discover, load_plugin};
40pub use manifest::{MANIFEST, Manifest, ManifestError, McpServerConfig, OLD_MANIFEST, parse_manifest};
41pub use names::ToolNames;
42pub use python::{PythonTool, default_python, python_tools, python_tools_in, run_script_sandboxed, run_script_unsandboxed};
43pub use skills::{SaveSkillTool, Skill, UseSkillTool, load_skills_dir, skills_prompt};
44
45/// Something that couldn't load, for the user (`path`: the plugin or skill folder).
46#[derive(Debug, Clone, PartialEq, Eq)]
47pub struct LoadError {
48    pub path: PathBuf,
49    pub message: String,
50}
51
52impl fmt::Display for LoadError {
53    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
54        write!(f, "{}: {}", self.path.display(), self.message)
55    }
56}
57
58impl std::error::Error for LoadError {}
59
60/// What a plugin's tools need to know about it.
61#[derive(Debug, Clone, PartialEq, Eq)]
62pub struct PluginRef {
63    pub id: String,
64    pub name: String,
65    pub dir: PathBuf,
66    /// `permissions.network`.
67    pub network: bool,
68    /// Setting values (defaults filled in), passed as environment variables.
69    pub env: BTreeMap<String, String>,
70}
71
72impl PluginRef {
73    /// `settings`: the user's values by key; declared defaults fill the gaps.
74    pub fn new(plugin: &Plugin, settings: &BTreeMap<String, String>) -> Self {
75        let mut env: BTreeMap<String, String> = plugin.manifest.settings.iter().filter_map(|s| Some((s.key.clone(), s.default.clone()?))).collect();
76        for s in &plugin.manifest.settings {
77            if let Some(v) = settings.get(&s.key) {
78                env.insert(s.key.clone(), v.clone());
79            }
80        }
81        Self { id: plugin.manifest.id.clone(), name: plugin.manifest.name.clone(), dir: plugin.dir.clone(), network: plugin.manifest.permissions.network, env }
82    }
83
84    /// Required settings that have no value yet (labels), e.g. to show "Fill in API key".
85    pub fn missing_settings(plugin: &Plugin, settings: &BTreeMap<String, String>) -> Vec<String> {
86        plugin
87            .manifest
88            .settings
89            .iter()
90            .filter(|s| s.required && settings.get(&s.key).or(s.default.as_ref()).is_none_or(|v| v.trim().is_empty()))
91            .map(|s| s.label.clone())
92            .collect()
93    }
94}
byob_plugins/lib.rs

byob_plugins/
lib.rs
