car-ir 0.50.0

//! Built-in tool schemas for common agent tools.
//!
//! These are schemas only — the runtime doesn't implement the tools.
//! Callers provide the `ToolExecutor` implementation; these schemas give
//! parameter validation, caching hints, and rate limit suggestions.
//!
//! ```rust,ignore
//! use car_ir::builtins;
//!
//! // Register all common schemas
//! for schema in builtins::all() {
//!     runtime.register_tool_schema(schema).await;
//! }
//!
//! // Or pick specific ones
//! runtime.register_tool_schema(builtins::shell()).await;
//! runtime.register_tool_schema(builtins::read_file()).await;
//! ```

use crate::{ToolRateLimit, ToolSchema};
use serde_json::json;

/// Shell command execution.
pub fn shell() -> ToolSchema {
    ToolSchema {
        name: "shell".to_string(),
        description: "Execute a shell command and return stdout/stderr.".to_string(),
        parameters: json!({
            "type": "object",
            "properties": {
                "command": {
                    "type": "string",
                    "description": "The shell command to execute"
                },
                "cwd": {
                    "type": "string",
                    "description": "Working directory (optional)"
                },
                "timeout_ms": {
                    "type": "integer",
                    "description": "Timeout in milliseconds (optional)"
                }
            },
            "required": ["command"]
        }),
        returns: Some(json!({
            "type": "object",
            "properties": {
                "stdout": { "type": "string" },
                "stderr": { "type": "string" },
                "exit_code": { "type": "integer" }
            }
        })),
        idempotent: false,
        cache_ttl_secs: None,
        rate_limit: None,
    }
}

/// Read a file's contents.
pub fn read_file() -> ToolSchema {
    ToolSchema {
        name: "read_file".to_string(),
        description: "Read a UTF-8 text file and return its contents. The returned \
                      `content` is LINE-NUMBERED in `cat -n` style: every line is \
                      prefixed with its 1-based line number, right-aligned in 6 columns, \
                      then a tab (e.g. `     1\\tfn main() {`). Those prefixes are a \
                      display aid so you can cite exact line numbers (they line up with \
                      grep_files' `line`) — they are NOT part of the file. NEVER copy a \
                      prefix into edit_file's `old_text`/`new_text` or write_file's \
                      `content`; use only the raw text after the tab. Use `offset` \
                      (0-based line) and `limit` to page through a large file; numbering \
                      then starts at `offset + 1`, while `size_bytes` and `total_lines` \
                      always describe the FULL file. Reading a file also lets you edit it \
                      afterward: the runtime requires you to read an existing file before \
                      editing or overwriting it. A paged read can license one unique \
                      targeted edit, but use an unpaged read before replace_all, appending \
                      to, or overwriting an existing file."
            .to_string(),
        parameters: json!({
            "type": "object",
            "properties": {
                "path": {
                    "type": "string",
                    "description": "Absolute or relative file path"
                },
                "offset": {
                    "type": "integer",
                    "description": "0-based starting line offset (optional). Line numbering in the output starts at offset + 1."
                },
                "limit": {
                    "type": "integer",
                    "description": "Maximum number of lines to return (optional)"
                }
            },
            "required": ["path"]
        }),
        returns: Some(json!({
            "type": "object",
            "properties": {
                "content": { "type": "string", "description": "File text, line-numbered `cat -n` style (strip the `%6d\\t` prefix before reusing any line)" },
                "size_bytes": { "type": "integer", "description": "Byte length of the FULL file" },
                "total_lines": { "type": "integer", "description": "Line count of the FULL file" }
            }
        })),
        idempotent: true,
        // Deliberately NOT cached: the Runtime result cache is keyed only by
        // tool+params, so a cached read could serve pre-edit content after the
        // agent's own write_file/edit_file, defeating the read-before-edit
        // staleness guard. (H1/F4-remainder, audit 2026-07-06.)
        cache_ttl_secs: None,
        rate_limit: None,
    }
}

/// Replace a unique text span within a file.
pub fn edit_file() -> ToolSchema {
    ToolSchema {
        name: "edit_file".to_string(),
        description: "Make a targeted edit to an existing file by replacing `old_text` \
                      with `new_text`. Prefer this over write_file for changing part of \
                      a file — it never risks clobbering the rest. `old_text` and \
                      `new_text` must be the EXACT raw file text: do NOT include the \
                      line-number prefixes that read_file displays (the `%6d\\t` before \
                      each line are display-only — copy only the text after the tab). By \
                      default `old_text` must match EXACTLY ONE place in the file; if it \
                      matches several, add surrounding lines to make it unique, or set \
                      `replace_all: true` to replace every occurrence. You must read the \
                      file (read_file) earlier in this session before editing it, and \
                      re-read it if it changed on disk since — the runtime rejects an \
                      edit to a file you have not read (or that is stale). A paged read is \
                      sufficient only for one unique targeted replacement; replace_all \
                      requires a fresh unpaged read."
            .to_string(),
        parameters: json!({
            "type": "object",
            "properties": {
                "path": {
                    "type": "string",
                    "description": "Absolute or relative file path"
                },
                "old_text": {
                    "type": "string",
                    "description": "Existing text to replace, verbatim (no read_file line-number prefixes). Must match uniquely unless `replace_all` is true."
                },
                "new_text": {
                    "type": "string",
                    "description": "Replacement text (no read_file line-number prefixes)"
                },
                "replace_all": {
                    "type": "boolean",
                    "description": "Replace every occurrence of `old_text` instead of requiring a unique match (default: false)"
                }
            },
            "required": ["path", "old_text", "new_text"]
        }),
        returns: Some(json!({
            "type": "object",
            "properties": {
                "edited": { "type": "string" },
                "diff_summary": { "type": "string" },
                "replacements": { "type": "integer", "description": "Number of occurrences replaced" }
            }
        })),
        idempotent: false,
        cache_ttl_secs: None,
        rate_limit: None,
    }
}

/// Write content to a file.
pub fn write_file() -> ToolSchema {
    ToolSchema {
        name: "write_file".to_string(),
        description: "Write `content` to a file, creating it if it does not exist. Use \
                      this to CREATE a new file or fully replace one; to change part of \
                      an existing file, prefer edit_file (a whole-file overwrite is \
                      easy to get wrong). Overwriting an existing file requires you to \
                      have read its FULL current content with an unpaged read_file earlier \
                      in this session — the runtime rejects a blind overwrite of a file \
                      you have not read; creating a NEW file needs no prior read. Appending \
                      to an existing file has the same full-read requirement. Set \
                      `append: true` to append instead of overwrite. `content` is written \
                      verbatim — do NOT include the \
                      line-number prefixes read_file displays."
            .to_string(),
        parameters: json!({
            "type": "object",
            "properties": {
                "path": {
                    "type": "string",
                    "description": "Absolute or relative file path"
                },
                "content": {
                    "type": "string",
                    "description": "Content to write, verbatim (no read_file line-number prefixes)"
                },
                "append": {
                    "type": "boolean",
                    "description": "Append instead of overwrite (default: false)"
                }
            },
            "required": ["path", "content"]
        }),
        returns: Some(json!({
            "type": "object",
            "properties": {
                "bytes_written": { "type": "integer" }
            }
        })),
        idempotent: false,
        cache_ttl_secs: None,
        rate_limit: None,
    }
}

/// Find files by name or simple glob pattern.
pub fn find_files() -> ToolSchema {
    ToolSchema {
        name: "find_files".to_string(),
        description: "Find files by name or glob pattern within a directory tree. \
                      A bare pattern (no '/') matches file names at any depth \
                      (e.g. `*.rs` finds every Rust file); a pattern with '/' \
                      matches the path relative to the search root, and `**` \
                      spans directories (e.g. `src/**/*.rs`)."
            .to_string(),
        parameters: json!({
            "type": "object",
            "properties": {
                "pattern": {
                    "type": "string",
                    "description": "File name or glob pattern. Supports `*` (within a path segment), `**` (across directories), and `?`. A pattern containing `/` is matched against the path relative to the search root; a bare pattern is matched against the file name at any depth."
                },
                "path": {
                    "type": "string",
                    "description": "Root search path (default: .)"
                },
                "max_results": {
                    "type": "integer",
                    "description": "Maximum number of matching files to return (default: 1000)"
                }
            },
            "required": ["pattern"]
        }),
        returns: Some(json!({
            "type": "object",
            "properties": {
                "files": {
                    "type": "array",
                    "items": { "type": "string" }
                },
                "count": { "type": "integer" },
                "truncated": { "type": "boolean" }
            }
        })),
        idempotent: true,
        // INTENTIONALLY uncached (like read_file): the Runtime result cache is
        // keyed only by tool+params, so a cached result could reflect pre-edit
        // filesystem state after the agent's own write/edit — feeding a stale
        // line number or listing into the fresh read/edit flow.
        // (H1/F4-remainder review, audit 2026-07-06.)
        cache_ttl_secs: None,
        rate_limit: None,
    }
}

/// Search file contents recursively.
pub fn grep_files() -> ToolSchema {
    ToolSchema {
        name: "grep_files".to_string(),
        description: "Search file contents recursively with a regex, returning each \
                      match as `{path, line, text}`. `line` is 1-based and matches the \
                      line numbers read_file shows, so grep to locate code and then \
                      read_file/edit_file that exact spot. Only text source files are \
                      scanned (binary and oversized files are skipped) and \
                      dotfiles/`node_modules`/`__pycache__`/`target` are ignored. Use \
                      `max_results` to bound output (default 50). Use find_files instead \
                      to locate files by NAME rather than content."
            .to_string(),
        parameters: json!({
            "type": "object",
            "properties": {
                "pattern": {
                    "type": "string",
                    "description": "Regex pattern to search for"
                },
                "path": {
                    "type": "string",
                    "description": "Root search path (default: .)"
                },
                "max_results": {
                    "type": "integer",
                    "description": "Maximum number of matching lines to return (default: 50)"
                }
            },
            "required": ["pattern"]
        }),
        returns: Some(json!({
            "type": "object",
            "properties": {
                "matches": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "path": { "type": "string" },
                            "line": { "type": "integer" },
                            "text": { "type": "string" }
                        }
                    }
                },
                "count": { "type": "integer" },
                "truncated": { "type": "boolean" }
            }
        })),
        idempotent: true,
        // INTENTIONALLY uncached (like read_file): the Runtime result cache is
        // keyed only by tool+params, so a cached result could reflect pre-edit
        // filesystem state after the agent's own write/edit — feeding a stale
        // line number or listing into the fresh read/edit flow.
        // (H1/F4-remainder review, audit 2026-07-06.)
        cache_ttl_secs: None,
        rate_limit: None,
    }
}

/// List directory contents.
pub fn list_dir() -> ToolSchema {
    ToolSchema {
        name: "list_dir".to_string(),
        description: "List the immediate entries of a directory (NON-recursive), \
                      returning `{name, path, is_dir, size_bytes}` for each. Hidden \
                      dotfiles and `node_modules`/`__pycache__`/`target` are omitted. For \
                      a recursive or globbed search use find_files; to search file \
                      contents use grep_files."
            .to_string(),
        parameters: json!({
            "type": "object",
            "properties": {
                "path": {
                    "type": "string",
                    "description": "Directory path"
                }
            },
            "required": ["path"]
        }),
        returns: Some(json!({
            "type": "object",
            "properties": {
                "entries": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "name": { "type": "string" },
                            "path": { "type": "string" },
                            "is_dir": { "type": "boolean" },
                            "size_bytes": { "type": "integer" }
                        }
                    }
                }
            }
        })),
        idempotent: true,
        // INTENTIONALLY uncached (like read_file): the Runtime result cache is
        // keyed only by tool+params, so a cached result could reflect pre-edit
        // filesystem state after the agent's own write/edit — feeding a stale
        // line number or listing into the fresh read/edit flow.
        // (H1/F4-remainder review, audit 2026-07-06.)
        cache_ttl_secs: None,
        rate_limit: None,
    }
}

/// Make an HTTP request.
pub fn http_request() -> ToolSchema {
    ToolSchema {
        name: "http_request".to_string(),
        description: "Make an HTTP request to a URL.".to_string(),
        parameters: json!({
            "type": "object",
            "properties": {
                "url": {
                    "type": "string",
                    "description": "The URL to request"
                },
                "method": {
                    "type": "string",
                    "description": "HTTP method (GET, POST, PUT, DELETE, PATCH)",
                    "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"]
                },
                "headers": {
                    "type": "object",
                    "description": "Request headers as key-value pairs"
                },
                "body": {
                    "type": "string",
                    "description": "Request body (for POST/PUT/PATCH)"
                }
            },
            "required": ["url"]
        }),
        returns: Some(json!({
            "type": "object",
            "properties": {
                "status": { "type": "integer" },
                "headers": { "type": "object" },
                "body": { "type": "string" }
            }
        })),
        idempotent: false,
        cache_ttl_secs: None,
        rate_limit: Some(ToolRateLimit {
            max_calls: 30,
            interval_secs: 60.0,
        }),
    }
}

/// Evaluate a mathematical expression.
pub fn calculate() -> ToolSchema {
    ToolSchema {
        name: "calculate".to_string(),
        description: "Evaluate a mathematical expression exactly. Prefer this over \
                      arithmetic in your head or a shell one-liner whenever a number \
                      has to be right."
            .to_string(),
        parameters: json!({
            "type": "object",
            "properties": {
                "expression": {
                    "type": "string",
                    "description": "Mathematical expression to evaluate. `^` is exponentiation (e.g. '2^3' = 8); also supports + - * / %, parentheses, and standard functions (e.g. sqrt, sin, ln). Example: '2 + 3 * 4'."
                }
            },
            "required": ["expression"]
        }),
        returns: Some(json!({
            "type": "object",
            "properties": {
                "result": { "type": "number" }
            }
        })),
        idempotent: true,
        cache_ttl_secs: Some(3600),
        rate_limit: None,
    }
}

/// Search/query a knowledge base or external service.
pub fn search() -> ToolSchema {
    ToolSchema {
        name: "search".to_string(),
        description: "Search for information using a query string.".to_string(),
        parameters: json!({
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "Search query"
                },
                "max_results": {
                    "type": "integer",
                    "description": "Maximum number of results (default: 10)"
                }
            },
            "required": ["query"]
        }),
        returns: Some(json!({
            "type": "object",
            "properties": {
                "results": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "title": { "type": "string" },
                            "snippet": { "type": "string" },
                            "url": { "type": "string" }
                        }
                    }
                }
            }
        })),
        idempotent: true,
        cache_ttl_secs: Some(60),
        rate_limit: Some(ToolRateLimit {
            max_calls: 10,
            interval_secs: 60.0,
        }),
    }
}

/// Browser navigation and interaction.
pub fn browser() -> ToolSchema {
    ToolSchema {
        name: "browser".to_string(),
        description: "Navigate and interact with web pages in a browser.".to_string(),
        parameters: json!({
            "type": "object",
            "properties": {
                "action": {
                    "type": "string",
                    "description": "Browser action to perform",
                    "enum": ["navigate", "click", "fill", "screenshot", "text", "back", "forward"]
                },
                "url": {
                    "type": "string",
                    "description": "URL to navigate to (for 'navigate' action)"
                },
                "selector": {
                    "type": "string",
                    "description": "CSS selector for the target element"
                },
                "value": {
                    "type": "string",
                    "description": "Value to fill (for 'fill' action)"
                }
            },
            "required": ["action"]
        }),
        returns: Some(json!({
            "type": "object",
            "properties": {
                "success": { "type": "boolean" },
                "content": { "type": "string" },
                "screenshot_path": { "type": "string" }
            }
        })),
        idempotent: false,
        cache_ttl_secs: None,
        rate_limit: Some(ToolRateLimit {
            max_calls: 60,
            interval_secs: 60.0,
        }),
    }
}

/// Send a message to a human over a messaging channel.
///
/// The dotted name follows the registry's existing convention for
/// namespaced built-ins (`memory.consolidate`, `infer.grounded`,
/// `models.list`).
///
/// Deliberately NOT in [`all`]: the runtime can only execute this tool when a
/// message sink is attached (`Runtime::with_message_sink`), and that builder
/// registers the schema itself. Advertising a tool the runtime cannot execute
/// would put an unusable verb in front of the model.
pub fn messaging_send() -> ToolSchema {
    ToolSchema {
        name: "messaging.send".to_string(),
        description: "Send a message to a HUMAN over a messaging channel \
                      (e.g. iMessage). This reaches a real person on their \
                      device: it is IRREVERSIBLE — a sent message cannot be \
                      unsent — so send only when the user asked you to, or \
                      when reaching a human is the point of the task. Set \
                      `kind` to 'direct' for a message to one person, or \
                      'channel' to post into a shared channel (a larger blast \
                      radius — prefer 'direct' unless a channel was named). \
                      Which channels and recipients are reachable is decided \
                      by project policy and by the channel's own consent \
                      pairing, so a send may be refused; read the error rather \
                      than retrying blindly. Pass `idempotency_key` when a \
                      retry is possible — a send that already went through \
                      under the same key is suppressed instead of duplicated."
            .to_string(),
        parameters: json!({
            "type": "object",
            "properties": {
                "channel": {
                    "type": "string",
                    "description": "Messaging channel to deliver on, e.g. 'imessage'"
                },
                "to": {
                    "type": "string",
                    "description": "Recipient: the person's handle (phone/email/member id) for kind 'direct', or the channel id for kind 'channel'"
                },
                "kind": {
                    "type": "string",
                    "description": "Whether `to` names a person or a shared channel (default: direct)",
                    "enum": ["direct", "channel"]
                },
                "body": {
                    "type": "string",
                    "description": "Message text, as the human will read it"
                },
                "idempotency_key": {
                    "type": "string",
                    "description": "Caller-supplied dedup key. Reusing a key that already delivered suppresses the send instead of sending twice — use it when retrying."
                }
            },
            "required": ["channel", "to", "body"]
        }),
        returns: Some(json!({
            "type": "object",
            "properties": {
                "channel": { "type": "string" },
                "message_id": { "type": "string", "description": "Channel-assigned id, when the channel exposes one" },
                "deduplicated": { "type": "boolean", "description": "True when the send was suppressed because its idempotency_key had already delivered" }
            }
        })),
        // A send is a side effect on a human's device; re-running it is not free.
        idempotent: false,
        // Never cached — a cached "already sent" would hide a second, genuinely
        // wanted message behind an earlier one with identical text.
        cache_ttl_secs: None,
        // A backstop, not a product decision: 30 messages/hour is a ceiling on
        // how fast a misbehaving loop can page a human, chosen to be far above
        // ordinary use. An operator can raise it
        // (`Runtime::set_rate_limit("messaging.send", …)`). The expressive knob
        // for WHO may be messaged, on WHICH channel, and with what content is
        // project policy — not this number.
        rate_limit: Some(ToolRateLimit {
            max_calls: 30,
            interval_secs: 3600.0,
        }),
    }
}

/// Return all built-in tool schemas.
pub fn all() -> Vec<ToolSchema> {
    vec![
        shell(),
        read_file(),
        edit_file(),
        write_file(),
        list_dir(),
        find_files(),
        grep_files(),
        http_request(),
        calculate(),
        search(),
        browser(),
    ]
}

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

    #[test]
    fn all_schemas_have_required_fields() {
        for schema in all() {
            assert!(!schema.name.is_empty(), "schema name is empty");
            assert!(
                !schema.description.is_empty(),
                "schema {} has no description",
                schema.name
            );
            assert!(
                schema.parameters.is_object(),
                "schema {} parameters not an object",
                schema.name
            );
            let params = schema.parameters.as_object().unwrap();
            assert_eq!(
                params.get("type").and_then(|v| v.as_str()),
                Some("object"),
                "schema {} parameters type not 'object'",
                schema.name
            );
            assert!(
                params.contains_key("properties"),
                "schema {} parameters missing 'properties'",
                schema.name
            );
            assert!(
                params.contains_key("required"),
                "schema {} parameters missing 'required'",
                schema.name
            );
        }
    }

    #[test]
    fn schemas_are_unique() {
        let schemas = all();
        let names: Vec<&str> = schemas.iter().map(|s| s.name.as_str()).collect();
        let mut unique = names.clone();
        unique.sort();
        unique.dedup();
        assert_eq!(names.len(), unique.len(), "duplicate schema names");
    }

    #[test]
    fn idempotent_tools_have_cache_hints() {
        for schema in all() {
            if schema.idempotent && schema.name != "shell" {
                // Idempotent tools should generally have cache hints
                // (shell is intentionally not cached despite being marked non-idempotent)
            }
        }
        // calculate (pure) and search (network) are idempotent and cached.
        assert!(calculate().cache_ttl_secs.is_some());
        assert!(search().cache_ttl_secs.is_some());
        // The filesystem tools are idempotent but INTENTIONALLY uncached: the
        // Runtime result cache is keyed only by tool+params, so a cached result
        // could reflect pre-edit filesystem state after the agent's own
        // write/edit — a stale read defeats the read-before-edit staleness
        // guard, and a stale grep/find/list feeds wrong line numbers or
        // listings into the fresh read/edit flow.
        // (H1/F4-remainder + review, audit 2026-07-06.)
        for schema in [read_file(), find_files(), grep_files(), list_dir()] {
            assert!(
                schema.cache_ttl_secs.is_none(),
                "{} must not be cached — a stale result would undermine the \
                 read/edit staleness contract",
                schema.name
            );
        }
    }

    #[test]
    fn messaging_send_schema_shape() {
        let schema = messaging_send();
        assert_eq!(schema.name, "messaging.send");
        let params = schema.parameters.as_object().unwrap();
        let required: Vec<&str> = params["required"]
            .as_array()
            .unwrap()
            .iter()
            .filter_map(|v| v.as_str())
            .collect();
        assert_eq!(required, ["channel", "to", "body"]);
        let props = params["properties"].as_object().unwrap();
        // `kind` is optional (defaulted by the parser) but constrained.
        assert_eq!(
            props["kind"]["enum"],
            serde_json::json!(["direct", "channel"])
        );
        assert!(props.contains_key("idempotency_key"));
        let returns = schema.returns.as_ref().unwrap();
        let ret_props = returns["properties"].as_object().unwrap();
        for key in ["channel", "message_id", "deduplicated"] {
            assert!(ret_props.contains_key(key), "returns missing '{key}'");
        }
        // A message to a human is a side effect: never idempotent, never cached.
        assert!(!schema.idempotent);
        assert!(schema.cache_ttl_secs.is_none());
        let rl = schema.rate_limit.as_ref().unwrap();
        assert_eq!(rl.max_calls, 30);
        assert_eq!(rl.interval_secs, 3600.0);
    }

    #[test]
    fn messaging_send_is_not_advertised_by_default() {
        // Only `Runtime::with_message_sink` registers it — a runtime with no
        // sink must not show the model a tool it cannot execute.
        assert!(!all().iter().any(|s| s.name == "messaging.send"));
    }

    #[test]
    fn rate_limited_tools() {
        assert!(http_request().rate_limit.is_some());
        assert!(search().rate_limit.is_some());
        assert!(browser().rate_limit.is_some());
        assert!(shell().rate_limit.is_none());
    }
}