use serde::{Deserialize, Serialize};
use serde_json::Value;
#[cfg(feature = "schemars")]
use schemars::{JsonSchema, schema_for};
/// Convert a Rust struct schema into an OpenAI tool `parameters` object.
///
/// - remove `$schema` and `title`
/// - convert `definitions` to `$defs`
/// - convert `oneOf` to `anyOf`
#[cfg(feature = "schemars")]
pub fn tool_parameters<T: JsonSchema>() -> Value {
let mut v = serde_json::to_value(schema_for!(T)).expect("can't parse value from schema");
// remove the $schema and title fields
if let Some(value) = v.as_object_mut() {
value.remove("$schema");
value.remove("title");
}
let mut v_str = serde_json::to_string(&v).unwrap();
v_str = v_str
.replace("/definitions/", "/$defs/")
.replace("\"definitions\":", "\"$defs\":");
// Replace oneOf with anyOf, because it's better supported by the LLMs
v_str = v_str.replace("\"oneOf\":", "\"anyOf\":");
let mut v: Value = serde_json::from_str(&v_str).expect("can't parse value from updated schema");
enforce_openai_strict_schema(&mut v);
v
}
#[cfg(feature = "schemars")]
fn enforce_openai_strict_schema(v: &mut Value) {
match v {
Value::Object(map) => {
// Recurse first so we fix nested schemas too.
for (_k, child) in map.iter_mut() {
enforce_openai_strict_schema(child);
}
// If this looks like an object schema, enforce strict rules.
let is_object = map
.get("type")
.and_then(|t| t.as_str())
.is_some_and(|t| t == "object");
let has_props = map.get("properties").is_some();
if is_object || has_props {
map.entry("additionalProperties".to_string())
.or_insert(Value::Bool(false));
if let Some(Value::Object(props)) = map.get("properties") {
let mut keys: Vec<String> = props.keys().cloned().collect();
keys.sort();
map.insert(
"required".to_string(),
Value::Array(keys.into_iter().map(Value::String).collect()),
);
}
}
}
Value::Array(arr) => {
for child in arr.iter_mut() {
enforce_openai_strict_schema(child);
}
}
_ => {}
}
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(JsonSchema))]
pub struct ReadFileArgs {
/// Path to file.
pub path: String,
/// Optional starting line (0-based).
pub offset: Option<usize>,
/// Optional maximum number of lines to read.
pub limit: Option<usize>,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(JsonSchema))]
pub struct ListDirArgs {
/// Directory path to list.
pub path: String,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[cfg_attr(feature = "schemars", derive(JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum GlobKind {
Files,
Dirs,
All,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(JsonSchema))]
pub struct GlobArgs {
/// Glob pattern to match. Supports `*`, `**`, `?`, and character classes.
pub pattern: String,
/// Optional directory root to search under. Defaults to `"."`.
pub path: Option<String>,
/// Optional maximum number of returned paths. Defaults to `50`.
pub limit: Option<usize>,
/// Optional match kind. Defaults to `files`.
pub kind: Option<GlobKind>,
/// Optional exclude patterns. Defaults to an empty list.
#[serde(default)]
pub exclude: Vec<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(JsonSchema))]
pub struct GrepArgs {
/// Regex pattern to search for.
pub pattern: String,
/// Optional path (file or directory) to search in.
pub path: Option<String>,
/// Optional glob filter, e.g. `"*.rs"`.
pub glob: Option<String>,
/// Optional limit for returned matches.
pub head_limit: Option<usize>,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(JsonSchema))]
pub struct RunShellArgs {
/// Shell command line to run (executed via `bash -lc`), supports pipes/redirection.
pub command: String,
/// Optional working directory (relative to project root).
pub cwd: Option<String>,
/// Optional timeout in seconds for foreground execution.
/// Omit to use the default 30 second timeout.
/// Must be omitted when `bg=true`.
/// For longer-running work like model training, set a larger value up front on the safe side to avoid retries.
pub timeout_seconds: Option<u64>,
/// Optional maximum captured bytes per stream (stdout/stderr) for foreground execution.
/// Must be omitted when `bg=true`.
///
/// Truncated output keeps roughly the first 30% and last 70%, so very large
/// values are usually unnecessary; prefer a few KB or low tens of KB and only
/// increase if needed.
pub max_output_bytes: Option<u64>,
/// When true, spawn the shell in the background and return immediately with a shell id.
#[serde(default)]
pub bg: bool,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(JsonSchema))]
pub struct ReadShellOutputArgs {
/// Background shell id returned by `run_shell` with `bg=true`.
pub shell_id: String,
/// When true, read from the start of the log. Defaults to `false` meaning read from the end.
#[serde(default)]
pub from_start: bool,
/// Optional 0-based line offset from the selected side. Defaults to `0`.
pub offset: Option<usize>,
/// Optional maximum number of lines to read. Defaults to `200`, max `1000`.
pub limit: Option<usize>,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(JsonSchema))]
pub struct StopShellArgs {
/// Background shell id returned by `run_shell` with `bg=true`.
pub shell_id: String,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(JsonSchema))]
pub struct SleepArgs {
/// Sleep duration in seconds. Clients may clamp this to a supported range.
pub seconds: u64,
/// Background shell ids to watch. Use an empty array for a plain timer.
/// If any watched shell exits early, the sleep may end early.
#[serde(default)]
pub shell_ids: Vec<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(JsonSchema))]
pub struct ApplyDiffArgs {
/// A git-style unified diff to apply to the working tree.
///
/// You may pass either:
/// - the raw diff text starting with `diff --git ...`, OR
/// - a fenced diff block like ```diff ... ``` (indentation is OK).
pub diff: String,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(JsonSchema))]
pub struct DeleteFilesArgs {
/// Paths to delete (relative to project root; no absolute paths; no `..`).
pub paths: Vec<String>,
}
/// Tools (function definitions) to send to the OpenAI Responses API.
#[cfg(feature = "schemars")]
pub fn openai_tools() -> Vec<Value> {
vec![
serde_json::json!({
"type": "function",
"name": "read_file",
"description": "Read a local file (by path), optionally with offset/limit. Returns a JSON string with keys: path, offset, limit, total_lines, content, numbered_content, fingerprint{hash64,len_bytes}, truncated.",
"strict": true,
"parameters": tool_parameters::<ReadFileArgs>(),
}),
serde_json::json!({
"type": "function",
"name": "list_dir",
"description": "List a local directory (by path). Returns a JSON string: { path, entries: [{ name, is_dir, is_file }, ...] }.",
"strict": true,
"parameters": tool_parameters::<ListDirArgs>(),
}),
serde_json::json!({
"type": "function",
"name": "glob",
"description": "Find local file or directory paths using a glob pattern under a search root. Use this for path discovery when you need matching paths, not file contents. Returns plain text with Returned, Total, and one relative path per line.",
"strict": true,
"parameters": tool_parameters::<GlobArgs>(),
}),
serde_json::json!({
"type": "function",
"name": "grep",
"description": "Search for a regex pattern in files. Returns a JSON string including matches (file, line_number, line). May be truncated to head_limit.",
"strict": true,
"parameters": tool_parameters::<GrepArgs>(),
}),
serde_json::json!({
"type": "function",
"name": "run_shell",
"description": "Run a shell command via `bash -lc` (supports pipes/redirection). Requires user confirmation unless the client auto-approves it. Use `max_output_bytes` intentionally for foreground runs: prefer the smallest limit that answers the question, and increase only when needed. Oversize output is cut from the middle, preserving roughly the first 30% and last 70%, so large requests are rarely necessary just to inspect the tail. Set `bg=true` to start a background shell that returns immediately with a shell id. When `bg=true`, omit `timeout_seconds` and omit `max_output_bytes`.",
"parameters": tool_parameters::<RunShellArgs>(),
}),
serde_json::json!({
"type": "function",
"name": "read_shell_output",
"description": "Read captured output from a background shell started with `run_shell(bg=true)`. Output is line-oriented. By default it reads from the end; set `from_start=true` to read from the beginning.",
"strict": true,
"parameters": tool_parameters::<ReadShellOutputArgs>(),
}),
serde_json::json!({
"type": "function",
"name": "stop_shell",
"description": "Stop a background shell started with `run_shell(bg=true)` and discard its retained state and logs.",
"strict": true,
"parameters": tool_parameters::<StopShellArgs>(),
}),
serde_json::json!({
"type": "function",
"name": "sleep",
"description": "Wait for 15 to 275 seconds. Provide `shell_ids` to return early when any watched background shell exits. Use `shell_ids: []` for a plain timer.",
"strict": true,
"parameters": tool_parameters::<SleepArgs>(),
}),
serde_json::json!({
"type": "function",
"name": "apply_diff",
"description": "Apply a git-style unified diff to the local working tree (create/update files). Returns a JSON string describing what changed or an error.",
"strict": true,
"parameters": tool_parameters::<ApplyDiffArgs>(),
}),
serde_json::json!({
"type": "function",
"name": "delete_files",
"description": "Delete one or more files by path (relative to project root). Returns a JSON string listing deleted and missing paths.",
"strict": true,
"parameters": tool_parameters::<DeleteFilesArgs>(),
}),
]
}
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
#[test]
fn glob_args_default_exclude_to_empty_list() {
let args: GlobArgs = serde_json::from_value(json!({
"pattern": "**/*.rs",
"path": "src",
"limit": 50,
"kind": "files",
}))
.expect("glob args");
assert_eq!(args.pattern, "**/*.rs");
assert_eq!(args.path.as_deref(), Some("src"));
assert_eq!(args.limit, Some(50));
assert_eq!(args.kind, Some(GlobKind::Files));
assert!(args.exclude.is_empty());
}
#[cfg(feature = "schemars")]
#[test]
fn run_shell_tool_schema_encourages_small_output_limits() {
let run_shell = openai_tools()
.into_iter()
.find(|tool| tool.get("name").and_then(Value::as_str) == Some("run_shell"))
.expect("run_shell tool");
let description = run_shell
.get("description")
.and_then(Value::as_str)
.expect("run_shell description");
assert!(description.contains("max_output_bytes"));
assert!(description.contains("30%"));
assert!(description.contains("70%"));
assert!(description.contains("smallest limit"));
assert!(description.contains("bg=true"));
assert!(description.contains("omit `timeout_seconds`"));
assert!(description.contains("omit `max_output_bytes`"));
let timeout_description = run_shell
.get("parameters")
.and_then(|value| value.get("properties"))
.and_then(|value| value.get("timeout_seconds"))
.and_then(|value| value.get("description"))
.and_then(Value::as_str)
.expect("timeout_seconds description");
assert!(timeout_description.contains("30 second timeout"));
assert!(timeout_description.contains("model training"));
assert!(timeout_description.contains("safe side"));
assert!(timeout_description.contains("Must be omitted when `bg=true`"));
let max_output_description = run_shell
.get("parameters")
.and_then(|value| value.get("properties"))
.and_then(|value| value.get("max_output_bytes"))
.and_then(|value| value.get("description"))
.and_then(Value::as_str)
.expect("max_output_bytes description");
assert!(max_output_description.contains("30%"));
assert!(max_output_description.contains("70%"));
assert!(max_output_description.contains("few KB"));
assert!(max_output_description.contains("Must be omitted when `bg=true`"));
let properties = run_shell
.get("parameters")
.and_then(|value| value.get("properties"))
.and_then(Value::as_object)
.expect("run_shell parameters");
assert!(properties.contains_key("bg"));
}
#[cfg(feature = "schemars")]
#[test]
fn openai_tools_include_glob_tool() {
let glob_tool = openai_tools()
.into_iter()
.find(|tool| tool.get("name").and_then(Value::as_str) == Some("glob"))
.expect("glob tool");
let description = glob_tool
.get("description")
.and_then(Value::as_str)
.expect("glob description");
assert!(description.contains("path discovery"));
assert!(description.contains("Returned"));
assert!(description.contains("Total"));
let properties = glob_tool
.get("parameters")
.and_then(|value| value.get("properties"))
.and_then(Value::as_object)
.expect("glob parameters");
assert!(properties.contains_key("pattern"));
assert!(properties.contains_key("path"));
assert!(properties.contains_key("limit"));
assert!(properties.contains_key("kind"));
assert!(properties.contains_key("exclude"));
}
#[test]
fn background_shell_tool_args_default_to_tail_reads() {
let read_shell_output: ReadShellOutputArgs = serde_json::from_value(json!({
"shell_id": "bg_123"
}))
.expect("read_shell_output args");
assert_eq!(read_shell_output.shell_id, "bg_123");
assert!(!read_shell_output.from_start);
assert_eq!(read_shell_output.offset, None);
assert_eq!(read_shell_output.limit, None);
let run_shell: RunShellArgs = serde_json::from_value(json!({
"command": "echo hi"
}))
.expect("run_shell args");
assert_eq!(run_shell.command, "echo hi");
assert!(!run_shell.bg);
let sleep: SleepArgs = serde_json::from_value(json!({
"seconds": 30,
"shell_ids": ["bg_123", "bg_456"]
}))
.expect("sleep args");
assert_eq!(sleep.seconds, 30);
assert_eq!(sleep.shell_ids, vec!["bg_123", "bg_456"]);
let timer_only_sleep: SleepArgs = serde_json::from_value(json!({
"seconds": 15
}))
.expect("timer-only sleep args");
assert_eq!(timer_only_sleep.seconds, 15);
assert!(timer_only_sleep.shell_ids.is_empty());
}
#[cfg(feature = "schemars")]
#[test]
fn openai_tools_include_background_shell_tools() {
let tools = openai_tools();
let names = tools
.iter()
.filter_map(|tool| tool.get("name").and_then(Value::as_str))
.collect::<Vec<_>>();
assert!(names.contains(&"read_shell_output"));
assert!(names.contains(&"stop_shell"));
assert!(names.contains(&"sleep"));
}
}