use std::sync::{Arc, OnceLock};
use rmcp::model::{Prompt, Tool, ToolAnnotations};
use schemars::schema_for;
use serde_json::Value;
use super::outcomes::{CodeMapToolResultEnvelope, ToolResultEnvelope};
use crate::tool_policy::ToolPolicy;
use crate::tool_registry::{ToolAccess, ToolKind, ToolOutputContract, ToolWorld};
use crate::tools::edit_files::EditFilesWire;
use crate::types::{
ApplyPatch, BashCommand, CodeMap, ContextSave, FileWriteOrEdit, Initialize, MultiFileEdit,
ReadFiles, ReadImage, UndoEdit, VerifyEdit,
};
/// Convert a schemars schema into the MCP tool input-schema representation.
pub(super) fn schema_to_input_schema<T: schemars::JsonSchema>(
) -> Arc<serde_json::Map<String, Value>> {
let schema = schema_for!(T);
let mut value = serde_json::to_value(schema).unwrap_or(Value::Object(serde_json::Map::new()));
// schemars stamps a redundant `title` (usually just the type/field name) on
// every schema node; the LLM pays tokens for it on every tool call for zero
// signal. Strip it — context-aware, so a user data field literally named
// "title" is never touched.
strip_schema_titles(&mut value);
strip_unsupported_schema_formats(&mut value);
match value {
Value::Object(map) => Arc::new(map),
_ => Arc::new(serde_json::Map::new()),
}
}
/// Remove integer formats that are valid JSON Schema annotations but rejected
/// by some MCP clients (notably Claude Code's schema compiler).
fn strip_unsupported_schema_formats(value: &mut Value) {
match value {
Value::Object(map) => {
let unsupported_integer_format =
map.get("format").and_then(Value::as_str).is_some_and(|format| {
format.starts_with("uint")
|| matches!(
format,
"int8" | "int16" | "int32" | "int64" | "isize" | "usize"
)
});
if unsupported_integer_format {
map.remove("format");
}
for child in map.values_mut() {
strip_unsupported_schema_formats(child);
}
}
Value::Array(items) => {
for item in items {
strip_unsupported_schema_formats(item);
}
}
_ => {}
}
}
/// Recursively remove `title` keys from JSON-Schema nodes only.
///
/// A dict is treated as a schema node when it carries a schema-shaped key
/// (`type`/`$ref`/`properties`/`items`/`enum`/`const`/`anyOf`/`allOf`/`oneOf`/
/// `additionalProperties`). This mirrors wcgw's `recursive_purge_dict_key` so a
/// property whose *name* is "title" keeps its value.
pub(super) fn strip_schema_titles(value: &mut Value) {
match value {
Value::Object(map) => {
const SCHEMA_KEYS: &[&str] = &[
"type",
"$ref",
"properties",
"items",
"additionalProperties",
"enum",
"const",
"anyOf",
"allOf",
"oneOf",
];
if SCHEMA_KEYS.iter().any(|key| map.contains_key(*key)) {
map.remove("title");
}
for child in map.values_mut() {
strip_schema_titles(child);
}
}
Value::Array(items) => {
for item in items {
strip_schema_titles(item);
}
}
_ => {}
}
}
fn mcp_tool<T: schemars::JsonSchema>(
name: &'static str,
description: &'static str,
annotations: ToolAnnotations,
) -> Tool {
Tool::new(name, description, schema_to_input_schema::<T>()).with_annotations(annotations)
}
const WORKSPACE_ROOT_DESCRIPTION: &str =
"Exact workspace_root returned by the same Initialize call as thread_id. It names the project session, not a path sandbox; never infer it from a target path. If unsure it is the user's current project, Initialize that project.";
fn with_workspace_binding(
schema: Arc<serde_json::Map<String, Value>>,
) -> Arc<serde_json::Map<String, Value>> {
let mut schema = Arc::unwrap_or_clone(schema);
let properties = schema
.entry("properties".to_string())
.or_insert_with(|| Value::Object(serde_json::Map::new()));
if let Value::Object(properties) = properties {
properties.insert(
"workspace_root".to_string(),
serde_json::json!({
"type": "string",
"minLength": 1,
"description": WORKSPACE_ROOT_DESCRIPTION,
}),
);
if let Some(Value::Object(thread_id)) = properties.get_mut("thread_id") {
thread_id.insert(
"description".to_string(),
Value::String(
"Exact thread_id returned by the same Initialize call as workspace_root. Never borrow one from another chat or project."
.to_string(),
),
);
}
}
let required = schema.entry("required".to_string()).or_insert_with(|| Value::Array(Vec::new()));
if let Value::Array(required) = required {
for field in ["thread_id", "workspace_root"] {
if !required.iter().any(|item| item.as_str() == Some(field)) {
required.push(Value::String(field.to_string()));
}
}
}
Arc::new(schema)
}
fn mcp_session_tool<T: schemars::JsonSchema>(
name: &'static str,
description: &'static str,
annotations: ToolAnnotations,
) -> Tool {
Tool::new(name, description, with_workspace_binding(schema_to_input_schema::<T>()))
.with_annotations(annotations)
}
/// `wait_policy` belongs to the MCP adapter rather than the stable public
/// `BashCommand` Rust struct. Inject it only into the advertised wire schema so
/// existing library callers do not acquire a new required struct field.
fn bash_command_input_schema() -> Arc<serde_json::Map<String, Value>> {
let mut schema = (*schema_to_input_schema::<BashCommand>()).clone();
let properties = schema
.entry("properties".to_string())
.or_insert_with(|| Value::Object(serde_json::Map::new()));
if let Value::Object(properties) = properties {
if let Some(Value::Object(wait)) = properties.get_mut("wait_for_seconds") {
wait.insert(
"description".to_string(),
Value::String(
"Observation allowance in seconds, not process lifetime. Omitted/null selects a policy default; explicit finite nonnegative values, including zero, are never increased. return_early defaults to 0.25 s and caps at 5 s. Synchronous adaptive defaults: 15 s local/unknown or Claude HTTP, 50 s ChatGPT/Codex HTTP. Synchronous ceilings: 60 s local/unknown, 50 s ChatGPT/Codex HTTP, 90 s Claude HTTP. Negotiated Tasks use a short inline promotion window."
.to_string(),
),
);
}
properties.insert(
"wait_policy".to_string(),
serde_json::json!({
"type": "string",
"enum": ["adaptive", "return_early", "until_complete"],
"default": "adaptive",
"description": "Execution delivery policy. adaptive uses a bounded inline allowance and may promote a running foreground Command to a negotiated MCP Task. return_early never creates a Task or changes policy; its cap is 5 seconds. until_complete is valid only for a finite foreground Command: use a Task when supported, otherwise the policy/client synchronous ceiling. Expiring an observation wait does not cancel the process."
}),
);
}
with_workspace_binding(Arc::new(schema))
}
/// Optional edit verification is implemented by the MCP adapter so the stable
/// public Rust edit structs remain source-compatible for library callers.
fn edit_input_schema<T: schemars::JsonSchema>() -> Arc<serde_json::Map<String, Value>> {
let mut schema = (*schema_to_input_schema::<T>()).clone();
let properties = schema
.entry("properties".to_string())
.or_insert_with(|| Value::Object(serde_json::Map::new()));
if let Value::Object(properties) = properties {
properties.insert(
"verify_command".to_string(),
serde_json::json!({
"type": "string",
"minLength": 1,
"description": "Optional finite foreground shell command to run immediately after a successful edit. Compose related fail-fast checks with &&. The edit remains applied if verification exits non-zero. Uses the same mode command policy as BashCommand."
}),
);
properties.insert(
"verify_wait_for_seconds".to_string(),
serde_json::json!({
"type": "number",
"minimum": 0,
"maximum": 60,
"default": 15,
"description": "Inline wait for verify_command. If it is still running, the result supplies a BashCommand status_check next action."
}),
);
}
with_workspace_binding(Arc::new(schema))
}
fn edit_files_input_schema() -> Arc<serde_json::Map<String, Value>> {
let mut schema = Arc::unwrap_or_clone(schema_to_input_schema::<EditFilesWire>());
if let Some(Value::Object(properties)) = schema.get_mut("properties") {
if let Some(Value::Object(files)) = properties.get_mut("files") {
files.insert("minItems".to_string(), Value::from(1));
files.insert("maxItems".to_string(), Value::from(100));
}
if let Some(Value::Object(command)) = properties.get_mut("verify_command") {
command.insert("minLength".to_string(), Value::from(1));
}
if let Some(Value::Object(wait)) = properties.get_mut("verify_wait_for_seconds") {
wait.insert("minimum".to_string(), Value::from(0));
wait.insert("maximum".to_string(), Value::from(60));
wait.insert("default".to_string(), Value::from(15));
}
}
if let Some(properties) = schema
.get_mut("$defs")
.and_then(Value::as_object_mut)
.and_then(|definitions| definitions.get_mut("EditFileWire"))
.and_then(|entry| entry.get_mut("properties"))
.and_then(Value::as_object_mut)
{
if let Some(Value::Object(path)) = properties.get_mut("file_path") {
path.insert("minLength".to_string(), Value::from(1));
}
if let Some(Value::Object(revision)) = properties.get_mut("expected_revision") {
revision.insert("pattern".to_string(), Value::String("^sha256:[0-9a-f]{64}$".into()));
}
if let Some(Value::Object(patches)) = properties.get_mut("patches") {
patches.insert("minItems".to_string(), Value::from(1));
patches.insert("maxItems".to_string(), Value::from(256));
}
if let Some(Value::Object(undo_id)) = properties.get_mut("undo_id") {
undo_id.insert("minLength".to_string(), Value::from(1));
}
}
with_workspace_binding(Arc::new(schema))
}
fn apply_patch_input_schema() -> Arc<serde_json::Map<String, Value>> {
let mut schema = Arc::unwrap_or_clone(edit_input_schema::<ApplyPatch>());
if let Some(Value::Object(properties)) = schema.get_mut("properties") {
if let Some(Value::Object(revision)) = properties.get_mut("expected_revision") {
revision
.insert("pattern".to_string(), Value::String("^sha256:[0-9a-f]{64}$".to_string()));
}
if let Some(Value::Object(patches)) = properties.get_mut("patches") {
patches.insert("minItems".to_string(), Value::from(1));
patches.insert("maxItems".to_string(), Value::from(256));
}
}
Arc::new(schema)
}
fn verify_edit_input_schema() -> Arc<serde_json::Map<String, Value>> {
let mut schema = (*schema_to_input_schema::<VerifyEdit>()).clone();
let properties = schema
.entry("properties".to_string())
.or_insert_with(|| Value::Object(serde_json::Map::new()));
if let Value::Object(properties) = properties {
if let Some(Value::Object(command)) = properties.get_mut("command") {
command.insert("minLength".to_string(), Value::from(1));
}
if let Some(Value::Object(receipt)) = properties.get_mut("verification_id") {
receipt.insert("pattern".to_string(), Value::String("^verify_[0-9a-f]{24}$".into()));
}
if let Some(Value::Object(wait)) = properties.get_mut("wait_for_seconds") {
wait.insert("minimum".to_string(), Value::from(0));
wait.insert("maximum".to_string(), Value::from(60));
}
}
with_workspace_binding(Arc::new(schema))
}
fn with_output_schema<T: schemars::JsonSchema>(mut tool: Tool) -> Tool {
tool.output_schema = Some(schema_to_input_schema::<T>());
tool
}
const INITIALIZE_DESCRIPTION: &str =
"Open one project before stateful tools unless MCP Roots did. Use first_call + wcgw with the user's project/file and preserve the returned thread_id/workspace_root pair; workspace_root is identity, not a path sandbox. Never reinitialize a valid pair. Use user_asked_mode_change only when asked. Use reset_shell only after BashCommand reports a shell-runtime failure; a redundant reset within the cooldown preserves the healthy PTY. State loss safely recreates the intended session; another project needs a new conversation. Put derived helpers only in temporary_artifact_dir.";
const BASH_COMMAND_DESCRIPTION: &str =
"Run commands, tests, builds, servers, formatters, generators, and TUIs after Initialize. Combine finite checks with &&. adaptive is default; until_complete is for finite foreground commands, return_early gives prompt control. For running results, wait retry_after_ms and execute next_action/status_check; never resubmit the command. Use background/interactive actions for long-lived work. Use ReadFiles/EditFiles, not shell/sed/Python, for ordinary canonical source reads and edits. Keep helpers under $WINX_TEMP_DIR, reuse names, never create CodeMap-only carriers, and clean obsolete helpers when directed; Winx may reclaim TTL-expired helpers near quota.";
const READ_FILES_DESCRIPTION: &str =
"Read exact canonical text and record visible edit coverage. Prefer this over cat/head/tail. Use :start-end targeted ranges; bounds may be omitted. Each file returns path, revision, and visibleRanges; default existing-file edits to EditFiles line_patch with that receipt. Truncation never records unseen lines. Use ReadImage for images.";
const EDIT_FILES_DESCRIPTION: &str =
"Create, change, or undo one or many files. Provide one unique files entry per target: line_patch is the default for an existing file after ReadFiles (copy its revision and visible coordinates); reserve search_replace for intentional text anchoring copied exactly from the current read; use replace for new files or deliberate whole-file rewrites. Omit operation for normal edits; exactly one mode=undo entry with its exact undo_id infers undo. Every existing target must be freshly read and every apply entry validates before writing. On SEARCH conflict, run the exact ReadFiles nextAction and switch the corrected retry to line_patch, never shell editing. verify_command runs once after commit; if it fails, keep the edit and follow nextAction instead of repeating it.";
const FILE_WRITE_OR_EDIT_DESCRIPTION: &str =
"Edit one read file; use MultiFileEdit for batches. For <=50%, use exact SEARCH/REPLACE blocks (optional @line); otherwise read and send the complete file. A SEARCH conflict revokes the read permit: execute its ReadFiles next_action (shell reads do not count), rebuild SEARCH, and retry once. Put helpers in temporary_artifact_dir. verify_command is post-commit; completed_with_issues means the edit remains applied - diagnose it, never repeat it.";
const MULTI_FILE_EDIT_DESCRIPTION: &str =
"Edit 2+ read, unique files in one validated batch; each file is replaced atomically and a commit-time failure reports which files were written. Validation failure writes nothing and revokes only the conflicting target's permit; execute its ReadFiles next_action before one corrected retry. Uses FileWriteOrEdit semantics. verify_command is post-commit; completed_with_issues means edits remain applied - never repeat them.";
const APPLY_PATCH_DESCRIPTION: &str =
"Patch one exact ReadFiles revision with ordered non-overlapping 1-based ranges. Copy path/revision; delete_lines=0 inserts and totalLines+1 appends. Only visible lines may change. On revision_mismatch execute the exact ReadFiles nextAction; never retry stale input. Prefer this over SEARCH when coordinates are known.";
const VERIFY_EDIT_DESCRIPTION: &str =
"Rerun a post-edit check without repeating the committed edit. Use the exact nextAction receipt after completed_with_issues, correct the code first, and never retry a failing check unchanged.";
const UNDO_EDIT_DESCRIPTION: &str =
"Restore one file to its previous Winx edit checkpoint in this session. Repeated calls walk backward per file. Undo is refused after an external change and cannot remove a newly created file.";
const CONTEXT_SAVE_DESCRIPTION: &str =
"Save a concise description and selected file/glob contents as one context artifact. Use the user's id when provided, otherwise a short unique id.";
const CODE_MAP_DESCRIPTION: &str =
"Navigate syntax-aware code structure in 13 languages. outline on a file returns definitions; on a directory it returns a query/activity-ranked, byte-budgeted page. Pass a concise query and continue truncated maps with next_cursor using the same path/query. references requires an exact name and returns definitions before uses. Results are gitignore-aware and contain symbols, not source. For exact text or unsupported languages, use the structured fallback to ReadFiles; plain-text search belongs to rg via BashCommand; never transform source solely to make CodeMap parse it or turn command output into a carrier. A genuinely useful derived helper must be one existing file in temporary_artifact_dir returned by Initialize; reuse stable names because helper maps have smaller per-response, unique-file, and aggregate-call budgets while canonical maps remain unrestricted.";
const EXECUTION_DESCRIPTION: &str =
"History: list/get/read/observe/explain/wait. Observe batches state/output; check item errors. Keep cursors; honor gap/resync. Preserves BashCommand output. Never replay; unknown is not success.";
const AGENT_DESCRIPTION: &str =
"Observe/prompt explicit native or configured Herdr targets. Native: target, prompt_id, text; same ID/payload returns receipt without resending. Delivery is not completion; never auto-resend uncertain input. Prompts need BashCommand + wcgw. Herdr rejects prompt_id.";
/// Every tool in `ToolKind::ALL` order. Descriptions and schemas depend only
/// on the build, so the catalog is generated once per process; per-principal
/// policies only filter it.
static WINX_TOOLS: OnceLock<Vec<Tool>> = OnceLock::new();
static WINX_PROMPTS: OnceLock<Vec<Prompt>> = OnceLock::new();
#[cfg(test)]
static CATALOG_BUILDS: std::sync::atomic::AtomicUsize = std::sync::atomic::AtomicUsize::new(0);
fn catalog() -> &'static [Tool] {
WINX_TOOLS.get_or_init(build_winx_tools)
}
pub(super) fn winx_tools() -> Vec<Tool> {
winx_tools_for_policy(ToolPolicy::default())
}
pub(super) fn winx_tools_for_policy(policy: ToolPolicy) -> Vec<Tool> {
ToolKind::ALL
.iter()
.zip(catalog())
.filter(|(kind, _)| policy.allows_kind(**kind))
.map(|(_, tool)| tool.clone())
.collect()
}
/// Borrow one advertised tool without cloning the catalog. Used on every
/// HTTP `tools/call` for header/schema validation.
pub(super) fn winx_tool(name: &str, policy: ToolPolicy) -> Option<&'static Tool> {
let kind = ToolKind::parse(name).filter(|kind| policy.allows_kind(*kind))?;
let index = ToolKind::ALL.iter().position(|candidate| *candidate == kind)?;
catalog().get(index)
}
#[cfg(test)]
pub(super) fn catalog_builds() -> usize {
CATALOG_BUILDS.load(std::sync::atomic::Ordering::SeqCst)
}
fn build_winx_tools() -> Vec<Tool> {
#[cfg(test)]
CATALOG_BUILDS.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
ToolKind::ALL.into_iter().map(build_winx_tool).collect()
}
/// Uncached catalog generation for benchmarks; production code uses `catalog`.
#[doc(hidden)]
pub fn build_tool_catalog_uncached() -> Vec<Tool> {
ToolKind::ALL.into_iter().map(build_winx_tool).collect()
}
fn annotations(kind: ToolKind) -> ToolAnnotations {
let descriptor = kind.descriptor();
let annotations = ToolAnnotations::new().open_world(descriptor.world == ToolWorld::Open);
match descriptor.access {
ToolAccess::ReadOnly => annotations.read_only(true),
ToolAccess::Neutral => annotations.destructive(false),
ToolAccess::Destructive => annotations.destructive(true),
}
}
fn build_winx_tool(kind: ToolKind) -> Tool {
let tool = match kind {
ToolKind::Initialize => mcp_tool::<Initialize>(
kind.as_str(),
INITIALIZE_DESCRIPTION,
annotations(kind),
),
ToolKind::BashCommand => Tool::new(
kind.as_str(),
BASH_COMMAND_DESCRIPTION,
bash_command_input_schema(),
)
.with_annotations(annotations(kind)),
ToolKind::ReadFiles => mcp_session_tool::<ReadFiles>(
kind.as_str(),
READ_FILES_DESCRIPTION,
annotations(kind),
),
ToolKind::FileWriteOrEdit => Tool::new(
kind.as_str(),
FILE_WRITE_OR_EDIT_DESCRIPTION,
edit_input_schema::<FileWriteOrEdit>(),
)
.with_annotations(annotations(kind)),
ToolKind::MultiFileEdit => Tool::new(
kind.as_str(),
MULTI_FILE_EDIT_DESCRIPTION,
edit_input_schema::<MultiFileEdit>(),
)
.with_annotations(annotations(kind)),
ToolKind::VerifyEdit => {
Tool::new(kind.as_str(), VERIFY_EDIT_DESCRIPTION, verify_edit_input_schema())
.with_annotations(annotations(kind))
}
ToolKind::UndoEdit => mcp_session_tool::<UndoEdit>(
kind.as_str(),
UNDO_EDIT_DESCRIPTION,
annotations(kind),
),
ToolKind::ContextSave => mcp_session_tool::<ContextSave>(
kind.as_str(),
CONTEXT_SAVE_DESCRIPTION,
annotations(kind),
),
ToolKind::ReadImage => mcp_session_tool::<ReadImage>(
kind.as_str(),
"Read validated JPEG/PNG/GIF/WebP as native MCP image content. Large images are bounded; unchanged session repeats return a compact reference. Set force=true only for an intentional resend.",
annotations(kind),
),
ToolKind::CodeMap => mcp_session_tool::<CodeMap>(
kind.as_str(),
CODE_MAP_DESCRIPTION,
annotations(kind),
),
ToolKind::ApplyPatch => Tool::new(
kind.as_str(),
APPLY_PATCH_DESCRIPTION,
apply_patch_input_schema(),
)
.with_annotations(annotations(kind)),
ToolKind::EditFiles => Tool::new(
kind.as_str(),
EDIT_FILES_DESCRIPTION,
edit_files_input_schema(),
)
.with_annotations(annotations(kind)),
ToolKind::Execution => mcp_session_tool::<super::workflow_types::ExecutionRequest>(
kind.as_str(),
EXECUTION_DESCRIPTION,
annotations(kind),
),
ToolKind::Agent => mcp_session_tool::<super::workflow_types::AgentRequest>(
kind.as_str(),
AGENT_DESCRIPTION,
annotations(kind),
),
};
match kind.descriptor().output_contract {
ToolOutputContract::Shared => with_output_schema::<ToolResultEnvelope>(tool),
ToolOutputContract::CodeMap => with_output_schema::<CodeMapToolResultEnvelope>(tool),
}
}
pub(super) fn winx_prompts() -> Vec<Prompt> {
WINX_PROMPTS
.get_or_init(|| {
vec![Prompt::new(
"KnowledgeTransfer",
Some("Summarize current Winx state, workspace context, and handoff notes."),
None,
)]
})
.clone()
}
/// Server icon (96x96 PNG) as a self-contained data URI, per MCP 2026-07-28.
/// A data URI works over stdio and HTTP alike — no extra endpoint or auth
/// exemption is needed for clients to fetch it.
pub(super) fn server_icon_data_uri() -> &'static str {
static URI: OnceLock<String> = OnceLock::new();
URI.get_or_init(|| {
use base64::Engine as _;
let png = include_bytes!("../../.github/assets/icon-96.png");
format!("data:image/png;base64,{}", base64::engine::general_purpose::STANDARD.encode(png))
})
}
#[cfg(test)]
mod cache_tests {
use super::*;
use crate::tool_policy::ToolProfile;
#[test]
fn catalog_is_built_once_and_lookup_respects_policy() {
for _ in 0..3 {
assert!(winx_tool("BashCommand", ToolPolicy::default()).is_some());
let _ = winx_tools();
}
assert_eq!(catalog_builds(), 1, "catalog must be generated once per process");
let read_only = ToolPolicy::from_profile(ToolProfile::ReadOnly);
assert!(winx_tool("BashCommand", read_only).is_none());
assert!(winx_tool("NoSuchTool", ToolPolicy::default()).is_none());
for tool in winx_tools_for_policy(read_only) {
let borrowed = winx_tool(tool.name.as_ref(), read_only).map(|tool| tool.name.clone());
assert_eq!(borrowed, Some(tool.name));
}
assert_eq!(catalog_builds(), 1);
}
}