From 898094d0279c7e7e90612ee208bc9994af7f80c1 Mon Sep 17 00:00:00 2001 From: blockmandev <194144408+blockmandev@users.noreply.github.com> Date: Sun, 15 Nov 2026 14:03:47 -0600 Subject: [PATCH 1/2] plugins: the memory engine's plugin tool servers offered as PluginTools and PluginCall The second half of the Claude-plugins work (the first, reading plugins in the .claude-plugin layout, is #83). The owner's decision of 2026-10-30: build the incode side now, tested against a fake engine, and say plainly when a plugin's server answers 401 (blocked on sign-in) instead of failing silently. - The memory engine runs plugin MCP servers for the owner. A session asks it once for the index (incord_describe) and offers two tools: PluginTools (one line per server; a server's tools on request) and PluginCall (run one). An index, not every tool, per the engine owner's decision: every plugin's tools in the context cost 8,029 tokens more. - Both are Reach::Run, like every MCP tool: refused read-only, asked under prompt, refused when the engine cannot decide. - A server a local plugin already runs is left out of the index, so no server is started twice. Plugin skills are read from the engine too. - Not offered when the engine names no servers or does not answer. This was left uncommitted on 2026-10-30 in the claude-plugins worktree; it is ported onto current main (the one conflict was the module list in toolbox/mod.rs after #96). cargo clippy --all-targets: clean. cargo test --lib: 2290 passed, 0 failed, including the 5 engine_plugins tests against a fake engine. The ignored live test against the real engine passed here: it described the inbrowse server's 43 tools. --- src/cli/mod.rs | 1 + src/plugins.rs | 61 +++++ src/skills.rs | 59 ++++- src/task_run.rs | 1 + src/toolbox/engine_plugins.rs | 378 ++++++++++++++++++++++++++++ src/toolbox/engine_plugins_tests.rs | 265 +++++++++++++++++++ src/toolbox/mod.rs | 51 ++++ 7 files changed, 811 insertions(+), 5 deletions(-) create mode 100644 src/toolbox/engine_plugins.rs create mode 100644 src/toolbox/engine_plugins_tests.rs diff --git a/src/cli/mod.rs b/src/cli/mod.rs index 75409be..f1deb16 100644 --- a/src/cli/mod.rs +++ b/src/cli/mod.rs @@ -131,6 +131,7 @@ fn connect_ext_tools(prepared: &Prepared) { for line in said { render::print_info(&line); } + crate::plugins::offer_engine_plugins(&prepared.workspace, &prepared.session.session_tools()); let on_connected: crate::toolbox::OnConnected = std::sync::Arc::new(|line| crate::trace!("tool", "{line}")); for line in prepared.session.session_tools().connect_client_servers( diff --git a/src/plugins.rs b/src/plugins.rs index 76cd15a..fa42a64 100644 --- a/src/plugins.rs +++ b/src/plugins.rs @@ -554,6 +554,46 @@ fn hooks_of(plugins: &[Plugin]) -> crate::hooks::HookConfig { all } +/// Offer the memory engine's plugin tool servers through `tools` +/// ([`crate::toolbox::engine_plugins`]), leaving out each one a usable local +/// plugin already runs ([`local_server_keys`]) — the local one is started by +/// [`session_servers`], with its hooks and its own keys, so none runs twice. +/// Only for a session that has the engine, as every memory request is. +/// +/// Called beside [`session_servers`] by `cli::connect_ext_tools` (REPL) and +/// `task_run::connect_ext_tools` (`-t`). +pub(crate) fn offer_engine_plugins(workspace: &Path, tools: &crate::toolbox::SessionTools) { + if crate::hooks::engine::Engine::locate().is_none() { + return; + } + let local = local_server_keys(workspace); + if let Some(index) = crate::toolbox::engine_plugins::fetch_index(&local) { + tools.set_engine_plugins(index); + } +} + +/// The server names, as each plugin's own file writes them, of every usable +/// plugin's MCP servers for `workspace`: `db` for the server `web_db`. +#[must_use] +pub(crate) fn local_server_keys(workspace: &Path) -> Vec { + server_keys(&discover_usable(workspace).plugins) +} + +/// [`local_server_keys`] of these plugins. +fn server_keys(plugins: &[Plugin]) -> Vec { + plugins + .iter() + .flat_map(|plugin| { + let prefix = format!("{}_", plugin.manifest.name); + plugin + .servers() + .unwrap_or_default() + .into_iter() + .filter_map(move |spec| spec.name.strip_prefix(&prefix).map(str::to_string)) + }) + .collect() +} + /// Every plugin's MCP servers for `workspace`, and a line for each that could /// not be read. #[must_use] @@ -1210,6 +1250,27 @@ mod tests { assert!(shown.contains("4 hook(s)"), "{shown}"); } + /// **A LOCAL PLUGIN'S SERVERS ARE NAMED AS ITS OWN FILE NAMES THEM**, so + /// the memory engine's copy of the same server is left out of its index + /// (`offer_engine_plugins`) and not run twice. + #[test] + fn a_local_plugins_servers_are_named_as_its_file_names_them() { + let dir = tempfile::tempdir().expect("dir"); + let root = plugin(dir.path(), "review-kit", "Reviews"); + write( + &root.join(".mcp.json"), + r#"{"mcpServers": {"greptile": {"command": "g"}, "db": {"url": "http://x/mcp"}}}"#, + ); + let bare = plugin(dir.path(), "bare", "No servers"); + let plugins = [ + load_one(&root, Scope::User).expect("loads"), + load_one(&bare, Scope::User).expect("loads"), + ]; + let mut keys = server_keys(&plugins); + keys.sort(); + assert_eq!(keys, ["db", "greptile"]); + } + #[test] fn skills_hooks_and_servers_are_read_from_the_folder() { let dir = tempfile::tempdir().expect("dir"); diff --git a/src/skills.rs b/src/skills.rs index 2181d6e..8782926 100644 --- a/src/skills.rs +++ b/src/skills.rs @@ -135,12 +135,24 @@ pub fn skills_url() -> String { pub fn parse(body: &str) -> Result { let value: serde_json::Value = serde_json::from_str(body) .map_err(|e| format!("the skill store's answer did not parse: {e}"))?; + let mut discovered: Vec = value + .get("discovered") + .map(discovered_from) + .unwrap_or_default(); + // Installed plugins' skills, which the store lists only in its `catalog`: + // named `:`, on while their plugin is. + for skill in value + .get("catalog") + .map(discovered_from) + .unwrap_or_default() + { + if skill.name.contains(':') && !discovered.iter().any(|s| s.name == skill.name) { + discovered.push(skill); + } + } Ok(Skillset { managed: value.get("managed").map(managed_from).unwrap_or_default(), - discovered: value - .get("discovered") - .map(discovered_from) - .unwrap_or_default(), + discovered, }) } @@ -192,7 +204,12 @@ pub fn load(root: &Path) -> (Skillset, Source) { let (mut set, source) = choose(fetched, root); // Plugins' skills are folders like any installed one, read from disk // rather than the store, so they are added after the cache is written. - set.discovered.extend(crate::plugins::session_skills()); + // A plugin installed in incode wins over the store's copy of the same + // skill, as its servers win over the engine's (`plugins::offer_engine_plugins`). + let local = crate::plugins::session_skills(); + set.discovered + .retain(|skill| !local.iter().any(|own| own.name == skill.name)); + set.discovered.extend(local); (set, source) } @@ -490,6 +507,38 @@ mod tests { ); } + /// **AN INSTALLED PLUGIN'S SKILLS COME FROM THE STORE'S CATALOG** — + /// named `:`, while their plugin is on — and nothing else + /// in the catalog is added, nor a skill already listed. + #[test] + fn plugin_skills_are_taken_from_the_catalog_while_their_plugin_is_on() { + let answer = r#"{ + "managed": [], + "discovered": [{"name": "kit:shared", "description": "listed already", "path": "/a"}], + "catalog": [ + {"name": "kit:review", "description": "Review a change", "enabled": true, + "path": "/plugins/kit/1.0.0/skills/review/SKILL.md", "source": "claude"}, + {"name": "off:design", "description": "Its plugin is off", "enabled": false, + "path": "/plugins/off/skills/design/SKILL.md", "source": "claude"}, + {"name": "aframe", "description": "Not a plugin's", "enabled": true, + "path": "/agents/skills/aframe/SKILL.md", "source": "agents"}, + {"name": "kit:shared", "description": "listed twice", "enabled": true, + "path": "/b", "source": "claude"} + ]}"#; + let set = parse(answer).expect("parses"); + let names: Vec<&str> = set.discovered.iter().map(|s| s.name.as_str()).collect(); + assert_eq!(names, ["kit:shared", "kit:review"]); + assert_eq!(set.discovered[0].path, "/a"); + assert_eq!( + set.discovered[1].path, + "/plugins/kit/1.0.0/skills/review/SKILL.md" + ); + assert!( + set.discovered[1].body.is_empty(), + "read only when asked for" + ); + } + fn managed(surfaces: &str, enabled: &str) -> String { format!( r#"{{"managed":[{{"name":"S","body":"do the thing"{surfaces}{enabled}}}],"discovered":[]}}"# diff --git a/src/task_run.rs b/src/task_run.rs index 21d390a..f1ecc04 100644 --- a/src/task_run.rs +++ b/src/task_run.rs @@ -616,6 +616,7 @@ fn connect_ext_tools(workspace: &Path) -> std::sync::Arc", "category", "description"}`. +//! - `incord_describe {"name": "plugin:"}` — that server's tools, +//! named `.` ([`describe`]). +//! - `POST /v1/memory/tools/incord_call {"name": ".", +//! "arguments"}` — the tool's own MCP result ([`call`]). +//! +//! A refusal is a 400 whose body is `{"error": "…"}`. When the server the +//! engine reached answered 401, the call is BLOCKED ON SIGN-IN, and said so +//! ([`explain`]): the engine reads a plugin's keys only from its own +//! environment and does no OAuth login, so retrying cannot help. +//! +//! # Through incode's gate +//! +//! Both are [`super::Reach::Run`], like every MCP tool: refused in a read-only +//! session, asked about in a prompting one, refused when the memory engine +//! cannot decide. What a server's tool touches cannot be known from here. +//! +//! # Wired to +//! +//! - The index is fetched where a session's servers are gathered — +//! `cli::connect_ext_tools` (REPL) and `task_run::connect_ext_tools` (`-t`) +//! — and kept in `SessionTools`, so every toolbox of the session, a +//! sub-agent's included, offers the same two tools. +//! - A server a local plugin already runs (`plugins::local_server_keys`, +//! started by `plugins::session_servers`) is left out of the index, so no +//! server is started twice. +//! - Sibling: [`super::client_servers`] runs MCP servers incode starts +//! itself, each tool offered by name. + +use std::time::Duration; + +use serde_json::{json, Value}; + +use super::image::ToolOutput; + +/// What one server offers. +pub const PLUGIN_TOOLS: &str = "PluginTools"; + +/// Run one of a server's tools. +pub const PLUGIN_CALL: &str = "PluginCall"; + +const DESCRIBE_PATH: &str = "/v1/memory/tools/incord_describe"; +const CALL_PATH: &str = "/v1/memory/tools/incord_call"; + +/// What names a server in the engine's index: `plugin:github`. +const DESCRIBE_PREFIX: &str = "plugin:"; + +/// Between a server and its tool: `github.create_issue`. +const SEPARATOR: char = '.'; + +/// How long a session's start waits for the index: measured at 0.85 s. +pub(crate) const INDEX_TIMEOUT: Duration = Duration::from_secs(4); + +/// How long describing a server may take: the engine may start its program. +const DESCRIBE_TIMEOUT: Duration = Duration::from_secs(60); + +/// How long one call may take, as for an MCP server incode runs itself. +const CALL_TIMEOUT: Duration = super::client_servers::CALL_BOUND; + +/// The most servers named in the index; the rest are counted. +const MAX_INDEXED: usize = 32; + +/// The longest a server's description runs in the index. +const INDEX_DESCRIPTION: usize = 160; + +/// One server in the engine's index. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Server { + pub name: String, + pub category: String, + pub description: String, +} + +/// The servers the engine runs for this session. +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct Index { + pub servers: Vec, +} + +impl Index { + /// Whether `server` is one of these. + #[must_use] + pub fn has(&self, server: &str) -> bool { + self.servers.iter().any(|s| s.name == server) + } + + /// [`PLUGIN_TOOLS`]'s description: what it does, then a line per server. + #[must_use] + pub fn description(&self) -> String { + let mut text = format!( + "{} The plugin tool servers the memory engine runs:", + describe_definition_text() + ); + for server in self.servers.iter().take(MAX_INDEXED) { + text.push_str(&format!( + "\n- {} [{}]: {}", + server.name, + server.category, + crate::text::truncate(&server.description, INDEX_DESCRIPTION) + )); + } + if self.servers.len() > MAX_INDEXED { + text.push_str(&format!( + "\n- and {} more, not named here", + self.servers.len() - MAX_INDEXED + )); + } + text + } +} + +fn describe_definition_text() -> &'static str { + "List the tools of one plugin tool server the memory engine runs: each \ + tool's name (`.`), what it does and its input schema. Call \ + this before PluginCall." +} + +/// The two tools as the toolbox's catalogue holds them; [`PLUGIN_TOOLS`]'s +/// description is replaced by [`Index::description`] where it is offered. +#[must_use] +pub fn definitions() -> Vec { + vec![ + json!({ + "name": PLUGIN_TOOLS, + "description": describe_definition_text(), + "input_schema": { + "type": "object", + "properties": { + "server": {"type": "string", "description": "A server named in this tool's description."} + }, + "required": ["server"], + "additionalProperties": false + } + }), + json!({ + "name": PLUGIN_CALL, + "description": "Run one tool of a plugin tool server the memory engine runs, by the \ + name PluginTools gave it (`.`), with the arguments its \ + input schema asks for. Returns the tool's own answer.", + "input_schema": { + "type": "object", + "properties": { + "tool": {"type": "string", "description": "`.`, as PluginTools lists it."}, + "arguments": {"type": "object", "description": "The tool's arguments."} + }, + "required": ["tool"], + "additionalProperties": false + } + }), + ] +} + +/// The engine's index from its answer, leaving out each server in `local` +/// (already run by a local plugin) and any name that is not a plain word. +/// +/// # Errors +/// +/// The answer is not the index's shape. +pub fn parse_index(answer: &str, local: &[String]) -> Result { + let value: Value = + serde_json::from_str(answer).map_err(|e| format!("the index did not parse: {e}"))?; + let listed = value + .get("plugin_tools") + .and_then(Value::as_array) + .ok_or("the engine's answer has no `plugin_tools`")?; + let text = |item: &Value, key: &str| { + item.get(key) + .and_then(Value::as_str) + .unwrap_or_default() + .trim() + .to_string() + }; + let mut index = Index::default(); + for item in listed { + let Some(name) = text(item, "name") + .strip_prefix(DESCRIBE_PREFIX) + .map(str::to_string) + else { + continue; + }; + let plain = !name.is_empty() + && name + .chars() + .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_'); + if !plain || local.contains(&name) || index.has(&name) { + continue; + } + index.servers.push(Server { + name, + category: text(item, "category"), + description: text(item, "description"), + }); + } + Ok(index) +} + +/// The engine's index for this session, without the servers in `local`. +/// `None` when the engine has no plugin servers to offer or did not answer +/// within [`INDEX_TIMEOUT`] — traced, never fatal. +#[must_use] +pub fn fetch_index(local: &[String]) -> Option { + let answered = post(DESCRIBE_PATH, &json!({}), INDEX_TIMEOUT) + .and_then(|answer| parse_index(&answer, local)); + match answered { + Ok(index) if index.servers.is_empty() => None, + Ok(index) => { + crate::trace!( + "tool", + "plugin tools: {} server(s) from the memory engine", + index.servers.len() + ); + Some(index) + } + Err(why) => { + crate::trace!("tool", "plugin tools: none from the memory engine: {why}"); + None + } + } +} + +/// [`PLUGIN_TOOLS`]: the tools of the server `input` names. +/// +/// # Errors +/// +/// The server is not in the index, or the engine could not reach it. +pub fn describe(index: &Index, input: &Value) -> Result { + let server = input + .get("server") + .and_then(Value::as_str) + .map(str::trim) + .map(|s| s.strip_prefix(DESCRIBE_PREFIX).unwrap_or(s)) + .unwrap_or_default(); + known(index, server)?; + let answer = post( + DESCRIBE_PATH, + &json!({"name": format!("{DESCRIBE_PREFIX}{server}")}), + DESCRIBE_TIMEOUT, + ) + .map_err(|why| explain(server, &why))?; + let value: Value = serde_json::from_str(&answer) + .map_err(|e| format!("the engine's answer did not parse: {e}"))?; + let tools = value + .get("tools") + .and_then(Value::as_array) + .ok_or_else(|| explain(server, &answer))?; + let mut lines = vec![format!( + "{} tool(s) of `{server}` — run one with PluginCall {{\"tool\": \"\", \ + \"arguments\": {{…}}}}:", + tools.len() + )]; + for tool in tools { + let name = tool.get("name").and_then(Value::as_str).unwrap_or("?"); + let said = tool + .get("description") + .and_then(Value::as_str) + .unwrap_or("") + .trim(); + let schema = tool.get("inputSchema").cloned().unwrap_or(json!({})); + lines.push(format!("\n## {name}\n{said}\ninput schema: {schema}")); + } + Ok(lines.concat()) +} + +/// [`PLUGIN_CALL`]: run the tool `input` names, with its arguments. A tool's +/// own refusal (`isError`) is an `Err` with its words. +/// +/// # Errors +/// +/// The tool is not of a server in the index, the engine could not reach the +/// server, or the tool refused. +pub fn call(index: &Index, input: &Value) -> Result { + let tool = input + .get("tool") + .and_then(Value::as_str) + .map(str::trim) + .unwrap_or_default(); + let Some((server, name)) = tool.split_once(SEPARATOR) else { + return Err(format!( + "`{tool}` is not `.`: use the name PluginTools gave it" + )); + }; + known(index, server)?; + if name.is_empty() { + return Err(format!("`{tool}` names no tool of `{server}`")); + } + let arguments = input.get("arguments").cloned().unwrap_or_else(|| json!({})); + let answer = post( + CALL_PATH, + &json!({"name": tool, "arguments": arguments}), + CALL_TIMEOUT, + ) + .map_err(|why| explain(server, &why))?; + output_of(server, &answer) +} + +/// A call's answer as the model is given it: the MCP result's content, or +/// the text itself when it is not one. +fn output_of(server: &str, answer: &str) -> Result { + let Ok(value) = serde_json::from_str::(answer) else { + return Ok(ToolOutput::from(answer.to_string())); + }; + if let Some(error) = value.get("error").and_then(Value::as_str) { + return Err(explain(server, error)); + } + let Some(blocks) = value.get("content").and_then(Value::as_array) else { + return Ok(ToolOutput::from(answer.to_string())); + }; + let output = ToolOutput::from_mcp_content(blocks); + if value.get("isError").and_then(Value::as_bool) == Some(true) { + return Err(output.text); + } + Ok(output) +} + +/// `server` is one the index names, or why not. +fn known(index: &Index, server: &str) -> Result<(), String> { + if index.has(server) { + return Ok(()); + } + let names: Vec<&str> = index.servers.iter().map(|s| s.name.as_str()).collect(); + Err(format!( + "there is no plugin tool server `{server}`; the memory engine runs: {}", + names.join(", ") + )) +} + +/// What a refusal from the engine about `server` means. A 401 from the +/// server it reached is not the call's fault and cannot be retried away. +#[must_use] +pub fn explain(server: &str, why: &str) -> String { + if why.contains("answered 401") || why.contains("Unauthorized") { + return format!( + "BLOCKED ON SIGN-IN: the memory engine could not sign in to the plugin tool server \ + `{server}`, so none of its tools can run through it — retrying will not help. The \ + engine reads a plugin's keys only from its own environment and does no OAuth login \ + yet; until that changes there, tell the person `{server}` needs signing in. (What \ + the engine said: {why})" + ); + } + format!("the memory engine could not run `{server}`: {why}") +} + +/// One POST to the engine, a refusal carrying what it said. +fn post(path: &str, body: &Value, timeout: Duration) -> Result { + let url = format!("{}{path}", crate::brief::memory_url().trim_end_matches('/')); + let body = body.to_string(); + crate::runtime::http::request_text_explained( + move |client| { + client + .post(&url) + .header("content-type", "application/json") + .body(body) + .timeout(timeout) + }, + "memory engine", + ) +} + +#[cfg(test)] +#[path = "engine_plugins_tests.rs"] +mod tests; diff --git a/src/toolbox/engine_plugins_tests.rs b/src/toolbox/engine_plugins_tests.rs new file mode 100644 index 0000000..34fdf72 --- /dev/null +++ b/src/toolbox/engine_plugins_tests.rs @@ -0,0 +1,265 @@ +//! The memory engine's plugin tool servers, through the toolbox, against a +//! stand-in engine that answers the way the real one was measured to +//! (2026-10-30): the index from `incord_describe {}`, a server's tools from +//! `incord_describe {"name": "plugin:"}`, a call's MCP result from +//! `incord_call`, and a refusal as a 400 with `{"error": …}`. + +use super::*; +use crate::toolbox::{SessionTools, Toolbox}; +use std::io::{BufRead as _, BufReader, Read as _, Write as _}; +use std::sync::{Arc, Mutex}; + +const INDEX: &str = r#"{"tools": [], "plugin_tools": [ + {"name": "plugin:greptile", "category": "coding", "description": "Code review"}, + {"name": "plugin:github", "category": "coding", "description": "Repositories"}, + {"name": "plugin:web", "category": "testing", "description": "Kept by a local plugin"}, + {"name": "plugin:bad name", "category": "x", "description": "Not a plain word"}, + {"name": "plugin:greptile", "category": "coding", "description": "Listed twice"}, + {"name": "memory_search", "description": "A memory tool, not a server"}]}"#; + +const GREPTILE_TOOLS: &str = r#"{"tools": [{"name": "greptile.get_me", + "description": "Who is calling", "inputSchema": {"type": "object", "properties": {}}}]}"#; + +const UNAUTHORIZED: &str = r#"{"error": "https://api.github.example/mcp answered 401 Unauthorized: missing required Authorization header"}"#; + +/// Every request the stand-in engine was sent: its path and its body. +type Seen = Arc>>; + +/// A stand-in engine on a free port: every request's path and body are kept, +/// and each is answered by `answer`. It serves until the test ends. +fn engine(answer: fn(&str, &Value) -> (u16, String)) -> (String, Seen) { + let listener = std::net::TcpListener::bind("127.0.0.1:0").expect("bind"); + let addr = listener.local_addr().expect("addr"); + let seen = Arc::new(Mutex::new(Vec::new())); + let kept = Arc::clone(&seen); + std::thread::spawn(move || { + for incoming in listener.incoming() { + let Ok(mut socket) = incoming else { break }; + let mut reader = BufReader::new(socket.try_clone().expect("clone")); + let mut first = String::new(); + let _ = reader.read_line(&mut first); + let path = first.split_whitespace().nth(1).unwrap_or("").to_string(); + let mut length = 0usize; + loop { + let mut line = String::new(); + if reader.read_line(&mut line).unwrap_or(0) == 0 || line.trim().is_empty() { + break; + } + if let Some((name, value)) = line.split_once(':') { + if name.eq_ignore_ascii_case("content-length") { + length = value.trim().parse().unwrap_or(0); + } + } + } + let mut body = vec![0u8; length]; + let _ = reader.read_exact(&mut body); + let body: Value = serde_json::from_slice(&body).unwrap_or(Value::Null); + let (status, reply) = answer(&path, &body); + kept.lock().expect("seen").push((path, body)); + let _ = write!( + socket, + "HTTP/1.1 {status} X\r\nContent-Type: application/json\r\nContent-Length: {}\r\n\ + Connection: close\r\n\r\n{reply}", + reply.len() + ); + let _ = socket.flush(); + } + }); + (format!("http://{addr}"), seen) +} + +/// The stand-in's answers: greptile describes and runs, github is not signed in. +fn measured(path: &str, body: &Value) -> (u16, String) { + let name = body.get("name").and_then(Value::as_str); + match (path, name) { + ("/v1/memory/tools/incord_describe", None) => (200, INDEX.to_string()), + ("/v1/memory/tools/incord_describe", Some("plugin:greptile")) => { + (200, GREPTILE_TOOLS.to_string()) + } + ("/v1/memory/tools/incord_call", Some("greptile.get_me")) => ( + 200, + r#"{"content": [{"type": "text", "text": "you are the owner"}], "isError": false}"# + .to_string(), + ), + ("/v1/memory/tools/incord_call", Some("greptile.refuses")) => ( + 200, + r#"{"content": [{"type": "text", "text": "no such repository"}], "isError": true}"# + .to_string(), + ), + _ => (400, UNAUTHORIZED.to_string()), + } +} + +/// A toolbox whose session was offered `index`. +fn toolbox(ws: &std::path::Path, index: Option) -> Toolbox { + let state = SessionTools::new(true); + if let Some(index) = index { + state.set_engine_plugins(index); + } + let mut tools = Toolbox::new(ws, true); + tools.share_session(state); + tools +} + +/// **THE ENGINE'S PLUGIN SERVERS REACH THE MODEL AS TWO TOOLS, THROUGH THE +/// GATE**: the index names each server once — not one a local plugin runs, +/// not a name that is not a plain word — `PluginTools` lists a server's +/// tools, `PluginCall` runs one with its arguments and hands back its +/// answer, a tool's own refusal is an error with its words, and a server the +/// engine cannot sign in to is said to be BLOCKED ON SIGN-IN. +#[test] +fn the_engines_plugin_servers_are_offered_and_run_through_the_toolbox() { + let (url, seen) = engine(measured); + let ws = tempfile::tempdir().expect("ws"); + let _guard = crate::brief::ENV_LOCK + .lock() + .unwrap_or_else(|e| e.into_inner()); + std::env::set_var(crate::brief::MEMORY_URL_ENV, &url); + + let index = fetch_index(&["web".to_string()]).expect("an index"); + let names: Vec<&str> = index.servers.iter().map(|s| s.name.as_str()).collect(); + assert_eq!(names, ["greptile", "github"]); + + let tools = toolbox(ws.path(), Some(index)); + let offered = tools.names(); + assert!(offered.iter().any(|n| n == PLUGIN_TOOLS), "{offered:?}"); + assert!(offered.iter().any(|n| n == PLUGIN_CALL), "{offered:?}"); + let described = tools + .definitions() + .into_iter() + .find(|d| d["name"] == PLUGIN_TOOLS) + .expect("PluginTools"); + let text = described["description"].as_str().unwrap_or_default(); + assert!(text.contains("- greptile [coding]: Code review"), "{text}"); + assert!(!text.contains("- web"), "{text}"); + + let listed = tools + .run(PLUGIN_TOOLS, &json!({"server": "greptile"})) + .expect("listed"); + assert!(listed.contains("## greptile.get_me"), "{listed}"); + assert!(listed.contains("Who is calling"), "{listed}"); + + let ran = tools + .run( + PLUGIN_CALL, + &json!({"tool": "greptile.get_me", "arguments": {"org": "x"}}), + ) + .expect("ran"); + assert_eq!(ran, "you are the owner"); + + let refused = tools + .run(PLUGIN_CALL, &json!({"tool": "greptile.refuses"})) + .expect_err("the tool refused"); + assert!(refused.contains("no such repository"), "{refused}"); + + let blocked = tools + .run(PLUGIN_CALL, &json!({"tool": "github.get_me"})) + .expect_err("not signed in"); + assert!(blocked.starts_with("BLOCKED ON SIGN-IN"), "{blocked}"); + assert!(blocked.contains("`github`"), "{blocked}"); + + let unknown = tools + .run(PLUGIN_CALL, &json!({"tool": "web.anything"})) + .expect_err("not in the index"); + assert!(unknown.contains("no plugin tool server `web`"), "{unknown}"); + + std::env::remove_var(crate::brief::MEMORY_URL_ENV); + + let seen = seen.lock().expect("seen"); + let call = seen + .iter() + .find(|(path, body)| path.ends_with("incord_call") && body["name"] == "greptile.get_me") + .expect("the call reached the engine"); + assert_eq!(call.1["arguments"], json!({"org": "x"})); + assert!( + !seen.iter().any(|(_, body)| body["name"] == "web.anything"), + "a server outside the index was asked for" + ); +} + +/// **WITHOUT THE ENGINE'S INDEX THE TWO TOOLS ARE NOT OFFERED**, and a model +/// that calls one anyway is told why. +#[test] +fn without_an_index_the_plugin_tools_are_not_offered() { + let ws = tempfile::tempdir().expect("ws"); + let tools = toolbox(ws.path(), None); + let offered = tools.names(); + assert!( + !offered + .iter() + .any(|n| n == PLUGIN_TOOLS || n == PLUGIN_CALL), + "{offered:?}" + ); + let refused = tools + .run(PLUGIN_TOOLS, &json!({"server": "greptile"})) + .expect_err("not offered"); + assert!(refused.contains("not available"), "{refused}"); +} + +/// **AN ENGINE WITH NO PLUGIN SERVERS, OR NONE AT ALL, OFFERS NOTHING** — +/// and an answer without the index's shape is an error, not an empty index. +#[test] +fn no_servers_or_no_engine_means_no_index() { + let _guard = crate::brief::ENV_LOCK + .lock() + .unwrap_or_else(|e| e.into_inner()); + std::env::set_var(crate::brief::MEMORY_URL_ENV, "http://127.0.0.1:1"); + assert_eq!(fetch_index(&[]), None); + std::env::remove_var(crate::brief::MEMORY_URL_ENV); + + assert_eq!( + parse_index(r#"{"tools": [], "plugin_tools": []}"#, &[]).expect("parses"), + Index::default() + ); + assert!(parse_index(r#"{"tools": []}"#, &[]).is_err()); +} + +/// The index in the description is bounded, and what it leaves out is +/// counted. +#[test] +fn the_index_is_bounded_and_counts_the_rest() { + let index = Index { + servers: (0..MAX_INDEXED + 3) + .map(|i| Server { + name: format!("s{i}"), + category: "c".to_string(), + description: "d".repeat(400), + }) + .collect(), + }; + let text = index.description(); + assert_eq!(text.matches("\n- s").count(), MAX_INDEXED); + assert!(text.ends_with("- and 3 more, not named here"), "{text}"); + assert!( + !text.contains(&"d".repeat(INDEX_DESCRIPTION + 1)), + "a description ran long" + ); +} + +/// The real engine on this machine (`INCORD_MEMORY_URL`, else the default +/// address): its index parses, a server it lists is described or said to be +/// blocked, and a call is answered or said to be blocked — never a bare +/// status. Run by hand with `--ignored`; it asks the engine to reach the +/// plugin's real server, and changes nothing there. +#[test] +#[ignore = "talks to the real memory engine and the plugin servers it reaches"] +fn the_real_engines_plugin_servers_answer_or_say_why_not() { + let index = fetch_index(&[]).expect("the engine named plugin servers"); + eprintln!("index: {:?}", index.servers.iter().map(|s| &s.name).collect::>()); + let server = index.servers[0].name.clone(); + match describe(&index, &json!({"server": server})) { + Ok(listed) => eprintln!("described `{server}`: {}", listed.lines().next().unwrap_or("")), + Err(why) => { + eprintln!("describe `{server}`: {why}"); + assert!(why.starts_with("BLOCKED ON SIGN-IN") || why.contains("could not run")); + } + } + let ran = call(&index, &json!({"tool": format!("{server}.get_me")})); + match ran { + Ok(out) => eprintln!("call answered: {}", crate::text::truncate(&out.text, 200)), + Err(why) => { + eprintln!("call: {}", crate::text::truncate(&why, 300)); + assert!(why.starts_with("BLOCKED ON SIGN-IN") || why.contains("could not run")); + } + } +} diff --git a/src/toolbox/mod.rs b/src/toolbox/mod.rs index f529950..cc9177e 100644 --- a/src/toolbox/mod.rs +++ b/src/toolbox/mod.rs @@ -60,6 +60,7 @@ mod convert; mod desktop; mod dispatch; mod edits; +pub(crate) mod engine_plugins; mod gates; mod image; mod listing; @@ -209,6 +210,9 @@ pub fn reach_of(name: &str) -> Option { // Each writes a PDF into the workspace. CONVERT_DOCUMENT | RENDER_PDF => Reach::Change, BASH | KILL_SHELL | DIAGNOSTICS | AGENT | crate::verify::VERIFY_TOOL => Reach::Run, + // What a plugin's server or tool touches cannot be known from here, + // and describing one may start its program: as every MCP tool. + engine_plugins::PLUGIN_TOOLS | engine_plugins::PLUGIN_CALL => Reach::Run, // The desktop: looking at the screen observes; everything that moves // the mouse or types acts on a machine signed into real accounts. other if desktop::OBSERVING.contains(&other) => Reach::Observe, @@ -247,6 +251,10 @@ pub struct SessionTools { /// `allowed-tools` narrowed it; `None` the rest of the time. Set and /// lifted by the session around one turn ([`TurnRestriction`]). turn_allow: Mutex>>, + /// The plugin tool servers the memory engine runs for this session, when + /// it named any at the start ([`engine_plugins`]); `None` otherwise, and + /// then `PluginTools` and `PluginCall` are not offered. + engine_plugins: RwLock>>, } /// A turn's narrowing of the session's tools, in force until this is @@ -348,9 +356,28 @@ impl SessionTools { filter_env, allowed: Arc::default(), turn_allow: Mutex::new(None), + engine_plugins: RwLock::new(None), }) } + /// Offer the memory engine's plugin tool servers in `index` through every + /// toolbox sharing this state. Set where the session's servers are + /// gathered (`cli::connect_ext_tools`, `task_run::connect_ext_tools`). + pub(crate) fn set_engine_plugins(&self, index: engine_plugins::Index) { + *self + .engine_plugins + .write() + .unwrap_or_else(PoisonError::into_inner) = Some(Arc::new(index)); + } + + /// The memory engine's plugin tool servers, when there are any. + fn engine_plugins(&self) -> Option> { + self.engine_plugins + .read() + .unwrap_or_else(PoisonError::into_inner) + .clone() + } + /// Hold every toolbox sharing this state to `list` until the returned /// guard is dropped: a call it does not cover is refused. pub fn restrict_turn( @@ -856,6 +883,9 @@ impl Toolbox { CONVERT_DOCUMENT => self.soffice().is_some(), SCREENSHOT => self.browser().is_some(), RENDER_PDF => self.printer().is_some(), + engine_plugins::PLUGIN_TOOLS | engine_plugins::PLUGIN_CALL => { + self.state.engine_plugins().is_some() + } other if desktop::is_desktop(other) => self.desktop.is_some(), _ => true, } @@ -881,6 +911,10 @@ impl Toolbox { install the headless browser)", pdf::PDF_BROWSER_ENV ), + engine_plugins::PLUGIN_TOOLS | engine_plugins::PLUGIN_CALL => format!( + "{name} is not available: the memory engine runs no plugin tool servers for \ + this session, or did not answer when it started" + ), other => { format!("{other} is not available: the desktop is not switched on for this session") } @@ -1444,6 +1478,13 @@ impl Toolbox { def["description"] = json!(format!("{text} {shell}")); } } + // The memory engine's plugin servers, one line each, where the + // model decides whether one of them has the tool it needs. + if def.get("name").and_then(Value::as_str) == Some(engine_plugins::PLUGIN_TOOLS) { + if let Some(index) = self.state.engine_plugins() { + def["description"] = json!(index.description()); + } + } if !browser && def.get("name").and_then(Value::as_str) == Some(crate::web::FETCH_TOOL) { @@ -1704,6 +1745,7 @@ fn catalogue() -> Vec { all.push(pdf::definition()); all.extend(team::definitions()); all.extend(desktop::definitions()); + all.extend(engine_plugins::definitions()); all } @@ -2260,6 +2302,15 @@ impl Toolbox { }, other if desktop::is_desktop(other) => self.run_desktop(other, input), other if self.state.is_client_tool(other) => self.run_client_tool(other, input), + // A ToolOutput, so a plugin tool's pictures reach the model. + engine_plugins::PLUGIN_CALL => match self.state.engine_plugins() { + Some(index) => engine_plugins::call(&index, input), + None => Err(Self::unavailable(name)), + }, + engine_plugins::PLUGIN_TOOLS => match self.state.engine_plugins() { + Some(index) => engine_plugins::describe(&index, input).map(ToolOutput::from), + None => Err(Self::unavailable(name)), + }, other => self .dispatch_text(call_id, other, input) .map(ToolOutput::from), From 69db7ffce5aff7aa6fbf499f3f66cfc4657283c5 Mon Sep 17 00:00:00 2001 From: blockmandev <194144408+blockmandev@users.noreply.github.com> Date: Sun, 15 Nov 2026 14:14:17 -0600 Subject: [PATCH 2/2] plugins: engine_plugins_tests formatted with rustfmt --- src/toolbox/engine_plugins_tests.rs | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/src/toolbox/engine_plugins_tests.rs b/src/toolbox/engine_plugins_tests.rs index 34fdf72..b99a4f3 100644 --- a/src/toolbox/engine_plugins_tests.rs +++ b/src/toolbox/engine_plugins_tests.rs @@ -245,10 +245,16 @@ fn the_index_is_bounded_and_counts_the_rest() { #[ignore = "talks to the real memory engine and the plugin servers it reaches"] fn the_real_engines_plugin_servers_answer_or_say_why_not() { let index = fetch_index(&[]).expect("the engine named plugin servers"); - eprintln!("index: {:?}", index.servers.iter().map(|s| &s.name).collect::>()); + eprintln!( + "index: {:?}", + index.servers.iter().map(|s| &s.name).collect::>() + ); let server = index.servers[0].name.clone(); match describe(&index, &json!({"server": server})) { - Ok(listed) => eprintln!("described `{server}`: {}", listed.lines().next().unwrap_or("")), + Ok(listed) => eprintln!( + "described `{server}`: {}", + listed.lines().next().unwrap_or("") + ), Err(why) => { eprintln!("describe `{server}`: {why}"); assert!(why.starts_with("BLOCKED ON SIGN-IN") || why.contains("could not run"));