Skip to content

armgit / dbx

Public Imported from GitHub
0

25 MB lightweight cross-platform database client for 100+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具,支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 100+ 数据库,提供桌面端、Docker、CLI、内置 AI 助手和 MCP。

36.4 KB
Raw Blame
//! The on-demand skill tools: `use_skill` and `read_skill_file`.
//!
//! The system prompt carries only a listing — name, source and description per
//! skill. The body of a skill is fetched by the model through `use_skill` when it
//! decides the skill is relevant, and the files a skill ships are fetched one by
//! one through `read_skill_file` (prd 09-30-skill-listing-use-skill,
//! Requirements 8-11b). The previous behaviour — injecting every selected body
//! into the prompt — is gone.
//!
//! Two rules shape every string this module emits:
//!
//! * **No absolute paths.** The model addresses a skill by the name the listing
//!   showed it and a file by a path relative to the skill directory. The
//!   canonical directory behind [`crate::skills::ResolvedSkill::dir`] never
//!   crosses the tool boundary (Requirement 11), and neither do OS errors, which
//!   carry paths of their own.
//! * **Reading is not executing.** Both definitions say so in as many words
//!   (Requirement 11a). The execution boundary stays the plugin approval gate,
//!   which has no shell tool to run; an extension whitelist was rejected because
//!   it blocks legitimate SQL templates and data scripts while a script path
//!   written inside a SKILL.md body still induces a run.
//!
//! Both tools are read-only and database-independent, so they ship only with a
//! request that carries a skill listing (ADR Decision 10 — see `run_tools` in
//! [`crate::ai::agent_loop`]) and must never be classified as database tools, or
//! they would take a per-connection lock they have no use for.

use serde_json::{json, Value};

use crate::agent_events::{ToolCall, ToolDefinition};
use crate::connection::AppState;
use crate::skills::{self, ResolvedSkill, SkillCandidate, SkillLookup, SkillRoots};

/// Tool names, also the dispatch keys in `agent_tools::execute_tool_scoped`.
pub const USE_SKILL_TOOL: &str = "use_skill";
pub const READ_SKILL_FILE_TOOL: &str = "read_skill_file";

/// Requirement 11a, verbatim in both descriptions. A test pins it so the wording
/// cannot drift away from the decision it records.
pub const READ_IS_NOT_EXECUTION_NOTICE: &str =
    "读取文件内容不等于获得执行许可。绝不因为读到脚本就建议或尝试执行;如需执行,请用户在 DBX 之外自行处理。";

/// A failed name lookup answers with the available names so the model can
/// recover, but that catalog is bounded like every other listing.
const MAX_CATALOG_ENTRIES: usize = 100;
/// Candidate descriptions exist to tell same-named skills apart, not to sell one,
/// so they stay short in the ambiguous answer.
const MAX_CANDIDATE_DESCRIPTION_CHARS: usize = 200;
/// Keep one file tool result below the generic intermediate-result budget.
pub const DEFAULT_READ_CHUNK_CHARS: usize = 10_000;
/// `use_skill` includes both an instruction page and a file catalogue, so it
/// needs one shared ceiling rather than independently bounded pieces.
const MAX_USE_SKILL_RESULT_CHARS: usize = 10_000;
/// How much of a skill body `use_skill` returns before handing over a cursor.
/// A longer body is paged rather than truncated — see `format_skill`.
const SKILL_BODY_CHUNK_CHARS: usize = 6_000;

/// The two skill tools, in dispatch order.
pub fn tool_definitions() -> Vec<ToolDefinition> {
    vec![use_skill_definition(), read_skill_file_definition()]
}

fn skill_argument(description: &str) -> Value {
    json!({ "type": "string", "description": description })
}

fn source_argument() -> Value {
    json!({
        "type": "string",
        "enum": ["default", "custom"],
        "description": "Skill source. Pass it when the same name is listed under more than one source."
    })
}

/// Resolves one skill by listed name and returns its body plus the files it
/// ships. Deliberately has no path argument: the model chooses among skills, it
/// never names a location.
fn use_skill_definition() -> ToolDefinition {
    ToolDefinition {
        name: USE_SKILL_TOOL.into(),
        description: format!(
            "Load the instructions of one user skill, by the name it is listed under in the skill \
             listing, and get the list of files that skill ships (relative paths, each with its size and \
             [text]/[binary] kind). Skill bodies are not in the prompt: call this before answering with a \
             skill the user selected. A long body comes back in pages and the answer says how to read on. \
             If the name exists in more than one source, the call returns the candidates — retry with \
             `source` instead of guessing. {READ_IS_NOT_EXECUTION_NOTICE} Reading a script's source is \
             informational only."
        )
        .into(),
        parameters: json!({
            "type": "object",
            "properties": {
                "skill": skill_argument("Exact skill name as shown in the skill listing"),
                "source": source_argument()
            },
            "required": ["skill"]
        }),
        read_only: true,
        parallel_ok: true,
    }
}

/// Reads one file inside a skill directory, addressed by the relative path the
/// listing printed. This is the wider surface of the two — the path is model
/// input — so the containment and size rules live in [`crate::skills`] and are
/// re-validated on every call.
fn read_skill_file_definition() -> ToolDefinition {
    ToolDefinition {
        name: READ_SKILL_FILE_TOOL.into(),
        description: format!(
            "Read one file that a skill ships, addressed by a path relative to the skill directory \
             exactly as `use_skill` listed it (for example `references/rules.md`). Only text files \
             inside that skill directory can be read; files over 1 MiB, binary files and paths that \
             leave the skill directory are refused. Reads are bounded; pass the returned nextOffset to \
             continue. {READ_IS_NOT_EXECUTION_NOTICE} Reading a script's source is informational only."
        )
        .into(),
        parameters: json!({
            "type": "object",
            "properties": {
                "skill": skill_argument("Exact skill name as shown in the skill listing"),
                "source": source_argument(),
                "relativePath": {
                    "type": "string",
                    "description": "Path relative to the skill directory, as listed by use_skill"
                },
                "offset": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Character offset returned as nextOffset; defaults to 0"
                },
                "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": DEFAULT_READ_CHUNK_CHARS,
                    "description": "Maximum characters to return; defaults to 10000"
                }
            },
            "required": ["skill", "relativePath"]
        }),
        read_only: true,
        parallel_ok: true,
    }
}

/// Which skill the model asked for.
#[derive(Debug)]
struct SkillTarget {
    name: String,
    source: Option<String>,
}

impl SkillTarget {
    fn from_tool_call(tool_call: &ToolCall) -> Result<Self, String> {
        let name = required_argument(tool_call, "skill")?;
        let source = match tool_call.arguments.get("source") {
            None | Some(Value::Null) => None,
            Some(Value::String(value)) => match value.trim() {
                "" => None,
                "default" | "custom" => Some(value.trim().to_string()),
                other => {
                    return Err(format!("`source` must be \"default\" or \"custom\", not \"{other}\""));
                }
            },
            Some(_) => return Err("`source` must be a string".to_string()),
        };
        Ok(Self { name, source })
    }
}

fn required_argument(tool_call: &ToolCall, key: &str) -> Result<String, String> {
    tool_call
        .arguments
        .get(key)
        .and_then(Value::as_str)
        .map(str::trim)
        .filter(|value| !value.is_empty())
        .map(str::to_string)
        .ok_or_else(|| format!("`{key}` is required"))
}

fn optional_u64_argument(tool_call: &ToolCall, key: &str) -> Result<Option<u64>, String> {
    match tool_call.arguments.get(key) {
        None | Some(Value::Null) => Ok(None),
        Some(Value::Number(value)) => {
            value.as_u64().map(Some).ok_or_else(|| format!("`{key}` must be a non-negative integer"))
        }
        Some(_) => Err(format!("`{key}` must be a non-negative integer")),
    }
}

/// What `use_skill` resolved: the text the model reads, plus the identity the
/// backend actually loaded.
///
/// `loaded_skill_id` exists so a caller never has to re-derive "which skill was
/// loaded" from the call arguments. The arguments say what the model *asked*
/// for, and an ambiguous or missing name loads nothing at all — re-deriving an
/// id from them lights a chip, and later injects a body, for a skill that was
/// never loaded.
#[derive(Debug)]
pub struct UseSkillOutcome {
    pub text: String,
    pub loaded_skill_id: Option<String>,
}

pub async fn execute_use_skill(tool_call: &ToolCall, state: &AppState) -> Result<UseSkillOutcome, String> {
    let target = SkillTarget::from_tool_call(tool_call)?;
    let roots = load_skill_roots(state).await;
    run_blocking(move || use_skill_answer(&target, &roots)).await
}

pub async fn execute_read_skill_file(tool_call: &ToolCall, state: &AppState) -> Result<String, String> {
    let target = SkillTarget::from_tool_call(tool_call)?;
    let relative = required_argument(tool_call, "relativePath")?;
    let offset = optional_u64_argument(tool_call, "offset")?.unwrap_or(0) as usize;
    let limit =
        optional_u64_argument(tool_call, "limit")?.map(|value| value as usize).unwrap_or(DEFAULT_READ_CHUNK_CHARS);
    if limit == 0 || limit > DEFAULT_READ_CHUNK_CHARS {
        return Err(format!("`limit` must be between 1 and {DEFAULT_READ_CHUNK_CHARS}"));
    }
    let roots = load_skill_roots(state).await;
    run_blocking(move || read_skill_file_answer(&target, &relative, offset, limit, &roots)).await
}

/// Reading a skill scans directories and reads files up to 1 MiB, so it must not
/// run on the async runtime. Both callers are inside a Tokio runtime (the Tauri
/// command and the web server's per-run runtime).
async fn run_blocking<T: Send + 'static>(
    work: impl FnOnce() -> Result<T, String> + Send + 'static,
) -> Result<T, String> {
    tokio::task::spawn_blocking(work).await.map_err(|error| format!("Skill tool task failed: {error}"))?
}

/// Roots come from the persisted settings, not from the request: the model (or a
/// stale request) cannot widen which roots are scanned, and the custom root stays
/// inert while its Settings switch is off. A failed settings read degrades to the
/// default root only.
async fn load_skill_roots(state: &AppState) -> SkillRoots {
    let (custom_root_enabled, custom_root) = match state.storage.load_desktop_settings().await {
        Ok(settings) => (settings.custom_ai_skill_root_enabled, settings.custom_ai_skill_root),
        Err(error) => {
            log::warn!("[agent][skills] cannot read the skill root settings; using the default root only: {error}");
            (false, None)
        }
    };
    match tokio::task::spawn_blocking(move || SkillRoots::resolve(custom_root_enabled, custom_root.as_deref())).await {
        Ok(roots) => roots,
        Err(error) => {
            log::warn!("[agent][skills] skill root resolution failed: {error}");
            SkillRoots { default: None, custom: None }
        }
    }
}

fn use_skill_answer(target: &SkillTarget, roots: &SkillRoots) -> Result<UseSkillOutcome, String> {
    match skills::read_skill_by_name(&target.name, target.source.as_deref(), roots) {
        SkillLookup::Found(skill) => {
            let text = format_skill(&skill);
            Ok(UseSkillOutcome { text, loaded_skill_id: Some(skill.id) })
        }
        // Err rather than a text answer: `is_error` on the tool result is the
        // only thing that says "nothing was loaded". `read_skill_file` answers
        // these two cases the same way, so one recovery instruction serves both.
        SkillLookup::Ambiguous(candidates) => Err(ambiguous_answer(&target.name, &candidates)),
        SkillLookup::NotFound => Err(not_found_answer(&target.name, roots)),
    }
}

fn read_skill_file_answer(
    target: &SkillTarget,
    relative: &str,
    offset: usize,
    limit: usize,
    roots: &SkillRoots,
) -> Result<String, String> {
    let skill = match skills::read_skill_by_name(&target.name, target.source.as_deref(), roots) {
        SkillLookup::Found(skill) => skill,
        // Retrying with the right skill is the model's job; a wrong or missing
        // skill is answered exactly like `use_skill` would, so one recovery
        // instruction serves both tools.
        SkillLookup::Ambiguous(candidates) => return Err(ambiguous_answer(&target.name, &candidates)),
        SkillLookup::NotFound => return Err(not_found_answer(&target.name, roots)),
    };
    let chunk = skills::read_skill_file_relative_chunk(&skill.dir, relative, offset, limit).map_err(|reason| {
        // The reason is a frozen word from `skills`; the OS detail behind it is
        // discarded there because it carries paths.
        log::debug!("[agent][skills] read_skill_file refused for skill '{}': {reason}", skill.name);
        read_failure_message(&reason)
    })?;
    let next_offset = chunk.next_offset.map_or_else(|| "none".to_string(), |value| value.to_string());
    Ok(format!(
        "[SKILL FILE CHUNK] path={relative} offset={offset} chars={}/{} nextOffset={next_offset}\n\n{}",
        chunk.content.chars().count(),
        chunk.total_chars,
        chunk.content
    ))
}

fn format_skill(skill: &ResolvedSkill) -> String {
    let listing = skills::list_skill_files(&skill.dir);
    let body = skill.content.trim_end();
    let body_chars = body.chars().count();
    let mut output = format!("# Skill: {} [{}]\n\n", skill.name, skill.source);
    if body_chars <= SKILL_BODY_CHUNK_CHARS {
        output.push_str(body);
        output.push('\n');
    } else {
        // Page the body instead of letting it be truncated downstream. The generic
        // intermediate-result compactor keeps only the head and the tail of an
        // oversized tool result, and for an instructions file the head and the tail
        // are the least useful parts — the operational steps sit in the middle that
        // gets dropped. A bounded first page plus an explicit cursor keeps every
        // character reachable, through the same `offset` the file reader already
        // takes.
        let page: String = body.chars().take(SKILL_BODY_CHUNK_CHARS).collect();
        output.push_str(&page);
        output.push_str(&format!(
            "\n\n(this skill's body is {body_chars} characters; the first {SKILL_BODY_CHUNK_CHARS} are shown \
             above. Read the rest with `read_skill_file`, passing `relativePath` \"{}\" and `offset` \
             {SKILL_BODY_CHUNK_CHARS}; keep passing the returned nextOffset until it is absent.)\n",
            skills::SKILL_FILE_NAME
        ));
    }
    output.push_str("\n## Files in this skill\n");
    if listing.entries.is_empty() {
        output.push_str("(this skill ships no extra files)\n");
    }
    let mut catalogue_omitted_for_budget = false;
    for entry in &listing.entries {
        let kind = if entry.text { "[text]" } else { "[binary]" };
        let rendered = format!("- {} ({} bytes) {kind}\n", entry.relative_path, entry.bytes);
        // Reserve room for the continuation instructions below. Never let a
        // long filename turn a bounded first page back into a generic tool
        // result that the agent loop has to compact.
        if output.chars().count() + rendered.chars().count() + 400 > MAX_USE_SKILL_RESULT_CHARS {
            catalogue_omitted_for_budget = true;
            break;
        }
        output.push_str(&rendered);
    }
    if listing.truncated || catalogue_omitted_for_budget {
        // A capped listing must say so, or the model reads a partial file list
        // as the whole skill.
        output.push_str(
            "(the file list is truncated; use `read_skill_file` only for paths referenced by the instructions)\n",
        );
    }
    output.push_str(
        "\nFollow this skill's instructions. Use `read_skill_file` with one of these relative paths when \
         you need a file the skill references.\n",
    );
    output
}

/// The ambiguous-name answer lists the candidates and stops there: picking one
/// would be a silent wrong-skill answer, and skill names genuinely do live in
/// both roots.
fn ambiguous_answer(name: &str, candidates: &[SkillCandidate]) -> String {
    // Two skills in the *same* source cannot be told apart by `source`, so the
    // usual "retry with a source" recovery would be impossible to follow. That
    // collision is the user's to fix, so say what is true instead of sending the
    // model in a circle. The `len() > 1` guard is not cosmetic: a lone candidate
    // has nothing to be told apart from, and the wording below would be false.
    let same_source = candidates.len() > 1
        && candidates.first().is_some_and(|first| candidates.iter().all(|candidate| candidate.source == first.source));
    let mut output = format!("Several skills are named \"{name}\":\n");
    for candidate in candidates {
        output.push_str(&format!(
            "- {} [{}]: {}\n",
            candidate.name,
            candidate.source,
            truncate_chars(&candidate.description, MAX_CANDIDATE_DESCRIPTION_CHARS)
        ));
    }
    output.push_str(if same_source {
        "\nThey all live in the same source, so `source` cannot tell them apart. Continue without this skill, or tell \
         the user that two skills share this name.\n"
    } else {
        "\nCall this tool again with `source` set to one of the values above.\n"
    });
    output
}

fn not_found_answer(name: &str, roots: &SkillRoots) -> String {
    let catalog = skills::list_skill_candidates(roots);
    if catalog.is_empty() {
        return format!(
            "No skill is named \"{name}\", and no skills are available right now. Continue without a skill."
        );
    }
    // Names and sources only: the model already has the descriptions in the
    // listing, and this answer must stay cheap and path-free.
    let mut output = format!("No skill is named \"{name}\". Available skills:\n");
    for candidate in catalog.iter().take(MAX_CATALOG_ENTRIES) {
        output.push_str(&format!("- {} [{}]\n", candidate.name, candidate.source));
    }
    if catalog.len() > MAX_CATALOG_ENTRIES {
        output.push_str("(the list is truncated)\n");
    }
    output.push_str(
        "\nCall this tool again with one of those names, and pass `source` when the name is listed under both sources.",
    );
    output
}

/// Turns a frozen reason into something the model can act on. No OS text and no
/// path: every branch is a fixed string.
fn read_failure_message(reason: &str) -> String {
    let detail = match reason {
        "oversized" => "it is larger than the 1 MiB limit for skill files",
        "not_utf8" => "it is not valid UTF-8 text",
        "not_text" => "it looks binary (it contains a NUL byte), so only text files can be read",
        "unreadable" => "it could not be read",
        "root_unavailable" => "the skill root is not available",
        _ => "no such file exists in this skill directory",
    };
    format!("The skill file could not be read: {detail}.")
}

fn truncate_chars(value: &str, limit: usize) -> String {
    if value.chars().count() <= limit {
        return value.to_string();
    }
    let mut truncated: String = value.chars().take(limit).collect();
    truncated.push('…');
    truncated
}

#[cfg(test)]
mod tests {
    use super::*;

    use std::path::{Path, PathBuf};

    const SKILL_BODY: &str = "---\nname: %NAME%\ndescription: %DESC%\n---\n\nFollow these rules.\n";

    fn temp_root(tag: &str) -> PathBuf {
        let root = std::env::temp_dir().join(format!("dbx-skill-tools-{tag}-{}", uuid::Uuid::new_v4()));
        std::fs::create_dir_all(&root).unwrap();
        root
    }

    fn write_skill(root: &Path, dir: &str, name: &str, description: &str) -> PathBuf {
        let dir = root.join(dir);
        std::fs::create_dir_all(&dir).unwrap();
        let body = SKILL_BODY.replace("%NAME%", name).replace("%DESC%", description);
        std::fs::write(dir.join(skills::SKILL_FILE_NAME), body).unwrap();
        dir
    }

    fn roots_of(default: &Path, custom: Option<&Path>) -> SkillRoots {
        SkillRoots {
            default: Some(std::fs::canonicalize(default).unwrap()),
            custom: custom.map(|path| std::fs::canonicalize(path).unwrap()),
        }
    }

    fn call(name: &str, arguments: Value) -> ToolCall {
        ToolCall { id: "call-1".to_string(), name: name.to_string(), arguments, provider_payload: None }
    }

    fn target(name: &str, source: Option<&str>) -> SkillTarget {
        SkillTarget { name: name.to_string(), source: source.map(str::to_string) }
    }

    /// Requirement 11: no tool result may carry a filesystem path. Both spellings
    /// are checked because the canonical form embeds the plain one as a substring,
    /// so a naive containment check against the canonical path alone would miss a
    /// leak of the plain path. On Windows a leaked absolute path always brings a
    /// backslash, and relative paths are normalized to `/`.
    fn assert_no_path_leak(text: &str, roots: &[&Path]) {
        assert!(!text.contains('\\'), "a backslash can only come from a real path: {text}");
        for root in roots {
            let plain = root.to_string_lossy().to_string();
            assert!(!text.contains(&plain), "the skill root leaked: {text}");
            let canonical = std::fs::canonicalize(root).unwrap().to_string_lossy().to_string();
            assert!(!text.contains(&canonical), "the canonical skill root leaked: {text}");
        }
    }

    #[test]
    fn tool_definitions_are_read_only_parallel_and_state_the_execution_boundary() {
        let definitions = tool_definitions();
        let names: Vec<&str> = definitions.iter().map(|definition| definition.name.as_ref()).collect();
        assert_eq!(names, [USE_SKILL_TOOL, READ_SKILL_FILE_TOOL]);
        for definition in &definitions {
            assert!(definition.read_only, "{} must be read-only", definition.name);
            assert!(definition.parallel_ok, "{} must stay parallel-safe", definition.name);
            assert!(
                definition.description.contains(READ_IS_NOT_EXECUTION_NOTICE),
                "{} must carry the no-execution notice verbatim",
                definition.name
            );
            assert!(definition.description.contains("informational only"), "{}", definition.name);
            // The schema is the only place the model learns how to address a
            // skill, and it must never invite a path.
            assert!(definition.parameters.pointer("/properties/skill").is_some());
            assert!(definition.parameters["required"].as_array().unwrap().contains(&json!("skill")));
        }
        let read = definitions.iter().find(|definition| definition.name == READ_SKILL_FILE_TOOL).unwrap();
        assert_eq!(read.parameters["properties"]["source"]["enum"], json!(["default", "custom"]));
        assert!(read.parameters["required"].as_array().unwrap().contains(&json!("relativePath")));
    }

    #[test]
    fn use_skill_reads_a_unique_name_and_lists_referencing_files_by_relative_path() {
        let root = temp_root("use");
        let dir = write_skill(&root, "alpha", "sql-review", "review rules");
        std::fs::create_dir_all(dir.join("references")).unwrap();
        std::fs::write(dir.join("references").join("one.md"), "one").unwrap();
        std::fs::write(dir.join("script.py"), "print(1)").unwrap();
        std::fs::write(dir.join("logo.png"), [0x89u8, b'P', 0, 1]).unwrap();
        let roots = roots_of(&root, None);

        let outcome = use_skill_answer(&target("sql-review", None), &roots).unwrap();
        let answer = &outcome.text;
        assert!(answer.contains("Follow these rules."), "the body must be returned: {answer}");
        assert!(answer.contains("references/one.md (3 bytes) [text]"), "{answer}");
        assert!(answer.contains("script.py (8 bytes) [text]"), "{answer}");
        assert!(answer.contains("logo.png (4 bytes) [binary]"), "{answer}");
        assert!(answer.contains("read_skill_file"), "the answer must say how to read them");
        // The load names the skill it resolved; that id is what a caller records.
        assert!(
            outcome.loaded_skill_id.as_deref().is_some_and(|id| id.starts_with("d-")),
            "{:?}",
            outcome.loaded_skill_id
        );
        assert_no_path_leak(answer, &[&root]);
    }

    #[test]
    fn use_skill_says_when_the_file_listing_is_truncated() {
        let root = temp_root("truncated");
        let dir = write_skill(&root, "many", "many-files", "d");
        for index in 0..skills::SKILL_LISTING_MAX_ENTRIES + 3 {
            std::fs::write(dir.join(format!("file-{index:03}.md")), "x").unwrap();
        }
        let roots = roots_of(&root, None);

        let answer = use_skill_answer(&target("many-files", None), &roots).unwrap().text;
        assert!(answer.contains("truncated"), "{answer}");
        // SKILL.md is one of the capped entries; every listed file here is text.
        assert_eq!(answer.matches(" bytes) [text]").count(), skills::SKILL_LISTING_MAX_ENTRIES, "{answer}");
    }

    /// A body longer than one answer must come back paged, not truncated: the
    /// generic intermediate-result compactor keeps only the head and the tail of an
    /// oversized result, and for an instructions file the middle it drops is the
    /// part that says what to do.
    #[test]
    fn use_skill_pages_a_body_that_does_not_fit_one_answer() {
        let root = temp_root("paged-body");
        let dir = root.join("big");
        std::fs::create_dir_all(&dir).unwrap();
        // A marker at the very end: it is only reachable through the cursor, so it
        // also proves the continuation lands in the region the first page omitted.
        let filler = "x".repeat(SKILL_BODY_CHUNK_CHARS + 5_000);
        let body = format!("---\nname: big-skill\ndescription: long\n---\n\n{filler}\nEND-OF-BODY\n");
        std::fs::write(dir.join(skills::SKILL_FILE_NAME), &body).unwrap();
        let roots = roots_of(&root, None);

        let answer = use_skill_answer(&target("big-skill", None), &roots).unwrap().text;
        assert!(!answer.contains("END-OF-BODY"), "an oversized body must not come back whole: {answer}");
        assert!(answer.contains("Read the rest with `read_skill_file`"), "{answer}");
        assert!(answer.chars().count() <= MAX_USE_SKILL_RESULT_CHARS, "{answer}");
        assert!(answer.contains("nextOffset"), "{answer}");
        assert!(
            answer.contains(&format!("`offset` {SKILL_BODY_CHUNK_CHARS}")),
            "the answer must name the cursor to continue from: {answer}"
        );
        assert_no_path_leak(&answer, &[&root]);

        // The cursor is in the same coordinates the file reader uses, so following it
        // really does reach the tail.
        let rest = read_skill_file_answer(
            &target("big-skill", None),
            skills::SKILL_FILE_NAME,
            SKILL_BODY_CHUNK_CHARS,
            DEFAULT_READ_CHUNK_CHARS,
            &roots,
        )
        .unwrap();
        assert!(rest.contains("END-OF-BODY"), "the cursor must reach the tail: {rest}");
        assert_no_path_leak(&rest, &[&root]);
    }

    #[test]
    fn use_skill_returns_candidates_instead_of_guessing_between_sources() {
        let root = temp_root("ambiguous");
        write_skill(&root, "one", "shared", "first description");
        let custom = temp_root("ambiguous-custom");
        write_skill(&custom, "two", "shared", "second description");
        let roots = roots_of(&root, Some(&custom));

        let answer = use_skill_answer(&target("shared", None), &roots).unwrap_err();
        assert!(answer.contains("shared [default]: first description"), "{answer}");
        assert!(answer.contains("shared [custom]: second description"), "{answer}");
        assert!(answer.contains("`source`"), "the model must be told how to disambiguate: {answer}");
        assert!(!answer.contains("Follow these rules."), "an ambiguous name must not return a body: {answer}");
        assert_no_path_leak(&answer, &[&root, &custom]);

        // The retry with a source resolves it.
        let chosen = use_skill_answer(&target("shared", Some("custom")), &roots).unwrap().text;
        assert!(chosen.contains("# Skill: shared [custom]"), "{chosen}");
    }

    /// Two skills in ONE source are a dead end for this tool: `source` is the
    /// documented discriminator and here both candidates carry the same one. The
    /// answer must say that instead of telling the model to retry with a value
    /// that cannot separate them.
    #[test]
    fn ambiguous_skills_in_one_source_do_not_pretend_source_can_separate_them() {
        let root = temp_root("collision");
        write_skill(&root, "one", "shared", "first description");
        write_skill(&root, "two", "shared", "second description");
        let roots = roots_of(&root, None);

        let answer = use_skill_answer(&target("shared", None), &roots).unwrap_err();
        assert!(answer.contains("shared [default]: first description"), "{answer}");
        assert!(answer.contains("shared [default]: second description"), "{answer}");
        assert!(!answer.contains("again with `source`"), "source cannot separate two entries in one root: {answer}");
        assert!(answer.contains("cannot tell them apart"), "{answer}");
        assert_no_path_leak(&answer, &[&root]);
    }

    #[test]
    fn use_skill_answers_a_missing_name_with_the_catalog() {
        let root = temp_root("missing");
        write_skill(&root, "alpha", "sql-review", "rules");
        let custom = temp_root("missing-custom");
        write_skill(&custom, "beta", "team-rules", "team");
        let roots = roots_of(&root, Some(&custom));

        let answer = use_skill_answer(&target("sql-reveiw", None), &roots).unwrap_err();
        assert!(answer.contains("- sql-review [default]"), "{answer}");
        assert!(answer.contains("- team-rules [custom]"), "{answer}");
        assert_no_path_leak(&answer, &[&root, &custom]);

        // No roots at all (default root missing, custom root disabled) is an
        // empty catalog, not a failure.
        let empty = SkillRoots { default: None, custom: None };
        let answer = use_skill_answer(&target("sql-review", None), &empty).unwrap_err();
        assert!(answer.contains("no skills are available"), "{answer}");
    }

    #[test]
    fn read_skill_file_returns_a_file_inside_the_skill_directory() {
        let root = temp_root("read");
        let dir = write_skill(&root, "alpha", "sql-review", "rules");
        std::fs::create_dir_all(dir.join("references")).unwrap();
        std::fs::write(dir.join("references").join("one.md"), "reference body").unwrap();
        let roots = roots_of(&root, None);

        let content = read_skill_file_answer(
            &target("sql-review", None),
            "references/one.md",
            0,
            DEFAULT_READ_CHUNK_CHARS,
            &roots,
        )
        .unwrap();
        assert!(content.contains("reference body"));
        assert!(read_skill_file_answer(&target("sql-review", None), "SKILL.md", 0, DEFAULT_READ_CHUNK_CHARS, &roots)
            .unwrap()
            .contains("name: sql-review"));
    }

    #[test]
    fn read_skill_file_refuses_escapes_absolutes_and_unreadable_files() {
        let root = temp_root("reject");
        let dir = write_skill(&root, "alpha", "sql-review", "rules");
        std::fs::write(root.join("outside.md"), "outside body").unwrap();
        let roots = roots_of(&root, None);
        let skill = target("sql-review", None);

        for escape in
            ["../outside.md", "references/../../outside.md", "..\\outside.md", "/etc/hosts", "C:\\Windows\\win.ini"]
        {
            let error = read_skill_file_answer(&skill, escape, 0, DEFAULT_READ_CHUNK_CHARS, &roots).unwrap_err();
            assert!(error.contains("no such file"), "{escape:?} must be refused: {error}");
            assert!(!error.contains(escape), "an error must not echo the requested path: {error}");
        }
        assert!(
            read_skill_file_answer(&skill, "references", 0, DEFAULT_READ_CHUNK_CHARS, &roots).is_err(),
            "a directory is not a file"
        );

        std::fs::write(dir.join("with-nul.md"), b"text\0more").unwrap();
        let error = read_skill_file_answer(&skill, "with-nul.md", 0, DEFAULT_READ_CHUNK_CHARS, &roots).unwrap_err();
        assert!(error.contains("binary"), "{error}");

        // No NUL byte here, so this must reach the encoding check instead of
        // being mistaken for binary.
        std::fs::write(dir.join("broken.md"), [0xFFu8, 0xFE]).unwrap();
        assert!(read_skill_file_answer(&skill, "broken.md", 0, DEFAULT_READ_CHUNK_CHARS, &roots)
            .unwrap_err()
            .contains("UTF-8"));

        let big = dir.join("big.md");
        std::fs::write(&big, "x").unwrap();
        std::fs::OpenOptions::new().write(true).open(&big).unwrap().set_len(skills::MAX_SKILL_FILE_BYTES + 1).unwrap();
        assert!(read_skill_file_answer(&skill, "big.md", 0, DEFAULT_READ_CHUNK_CHARS, &roots)
            .unwrap_err()
            .contains("1 MiB"));
    }

    /// The tool layer must hand the *canonical skill directory* to the
    /// containment check — a root-prefix check would accept this junction, since
    /// both directories do live under the root. Windows equivalent of the unix
    /// `symlink` test in `skills::tests`; see the note there for what a junction
    /// cannot cover.
    #[cfg(windows)]
    #[test]
    fn read_skill_file_cannot_follow_a_junction_out_of_the_skill_directory() {
        let root = temp_root("junction");
        let dir = write_skill(&root, "alpha", "sql-review", "rules");
        let outside = temp_root("junction-outside");
        std::fs::write(outside.join("secret.md"), "secret").unwrap();
        let output = std::process::Command::new("cmd")
            .args(["/C", "mklink", "/J"])
            .arg(dir.join("linkdir"))
            .arg(&outside)
            .output()
            .expect("cmd must be runnable to create a junction");
        assert!(output.status.success(), "{}", String::from_utf8_lossy(&output.stderr));

        let roots = roots_of(&root, None);
        let error = read_skill_file_answer(
            &target("sql-review", None),
            "linkdir/secret.md",
            0,
            DEFAULT_READ_CHUNK_CHARS,
            &roots,
        )
        .unwrap_err();
        assert!(error.contains("no such file"), "{error}");

        let answer = use_skill_answer(&target("sql-review", None), &roots).unwrap().text;
        assert!(!answer.contains("linkdir"), "the listing must not advertise a link that leaves the skill: {answer}");
    }

    #[test]
    fn arguments_are_validated_before_any_filesystem_work() {
        assert_eq!(SkillTarget::from_tool_call(&call(USE_SKILL_TOOL, json!({}))).unwrap_err(), "`skill` is required");
        assert_eq!(
            SkillTarget::from_tool_call(&call(USE_SKILL_TOOL, json!({ "skill": "   " }))).unwrap_err(),
            "`skill` is required"
        );
        assert_eq!(
            SkillTarget::from_tool_call(&call(USE_SKILL_TOOL, json!({ "skill": "a", "source": "bogus" }))).unwrap_err(),
            "`source` must be \"default\" or \"custom\", not \"bogus\""
        );
        assert_eq!(
            SkillTarget::from_tool_call(&call(USE_SKILL_TOOL, json!({ "skill": "a", "source": 7 }))).unwrap_err(),
            "`source` must be a string"
        );
        // An empty or absent source means "no filter", not "no source matches".
        let target =
            SkillTarget::from_tool_call(&call(USE_SKILL_TOOL, json!({ "skill": "a", "source": "  " }))).unwrap();
        assert_eq!(target.name, "a");
        assert!(target.source.is_none());
        assert_eq!(
            required_argument(&call(READ_SKILL_FILE_TOOL, json!({ "skill": "a" })), "relativePath").unwrap_err(),
            "`relativePath` is required"
        );
    }

    #[test]
    fn candidate_descriptions_are_trimmed_to_a_hint() {
        let long = "x".repeat(MAX_CANDIDATE_DESCRIPTION_CHARS + 50);
        let candidates = vec![SkillCandidate { name: "shared".to_string(), source: "default", description: long }];
        let answer = ambiguous_answer("shared", &candidates);
        assert!(answer.contains('…'), "{answer}");
        assert!(answer.len() < MAX_CANDIDATE_DESCRIPTION_CHARS + 200, "{answer}");
    }
}