toolplane-python-client 0.1.0__py3-none-any.whl

toolplane/toolkits/swe/descriptions.py

@@ -0,0 +1,273 @@
+##############################################################################
+# tool definitions
+##############################################################################
+
+ALLOWED_STR_REPLACE_EDITOR_COMMANDS = ["view", "create", "str_replace", "insert"]
+
+# V1 File Editor
+_FILE_EDITOR_DESCRIPTION = """Custom editing tool for viewing, creating and editing files
+* State is persistent across command calls and discussions with the user
+* If `path` is a file, `view` displays the result of applying `cat -n`. If `path` is a directory, `view` lists non-hidden files and directories up to 2 levels deep
+* The `create` command cannot be used if the specified `path` already exists as a file
+* If a `command` generates a long output, it will be truncated and marked with `<response clipped>`
+* The `undo_edit` command will revert the last edit made to the file at `path`
+
+Notes for using the `str_replace` command:
+* The `old_str` parameter should match EXACTLY one or more consecutive lines from the original file. Be mindful of whitespaces!
+* If the `old_str` parameter is not unique in the file, the replacement will not be performed. Make sure to include enough context in `old_str` to make it unique
+* The `new_str` parameter should contain the edited lines that should replace the `old_str`
+"""
+
+file_editor = {
+    "type": "function",
+    "function": {
+        "name": "file_editor",
+        "description": _FILE_EDITOR_DESCRIPTION,
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "command": {
+                    "description": "The command to run. Allowed options are: `view`, `create`, `str_replace`, `insert`, `undo_edit`.",
+                    "enum": ["view", "create", "str_replace", "insert", "undo_edit"],
+                    "type": "string",
+                },
+                "path": {
+                    "description": "Absolute path to file or directory, e.g. `/testbed/file.py` or `/testbed`.",
+                    "type": "string",
+                },
+                "file_text": {
+                    "description": "Required for the `create` command, contains the content of the file to be created.",
+                    "type": "string",
+                },
+                "old_str": {
+                    "description": "Required for the `str_replace` command, specifies the string in `path` to replace.",
+                    "type": "string",
+                },
+                "new_str": {
+                    "description": "Optional for the `str_replace` command to specify the replacement string. Required for the `insert` command to specify the string to insert.",
+                    "type": "string",
+                },
+                "insert_line": {
+                    "description": "Required for the `insert` command. The `new_str` will be inserted AFTER the line specified.",
+                    "type": "integer",
+                },
+                "view_range": {
+                    "description": "Optional for the `view` command when `path` points to a file. Specifies the line range to view. E.g., [11, 12] shows lines 11 and 12. Indexing starts at 1. Use [start_line, -1] to show all lines from `start_line` to the end.",
+                    "type": "array",
+                    "items": {"type": "integer"},
+                },
+                "concise": {
+                    "description": "Optional for the `view` command. If `True`, displays a concise skeletal view of the file. Very useful for localization tasks. Highly recommended for large files.",
+                    "type": "boolean",
+                },
+            },
+            "required": ["command", "path"],
+        },
+    },
+}
+
+
+_STR_REPLACE_EDITOR_DESCRIPTION = """Custom editing tool for viewing, creating and editing files
+* State is persistent across command calls and discussions with the user
+* If `path` is a file, `view` displays the result of applying `cat -n`. If `path` is a directory, `view` lists non-hidden files and directories up to 2 levels deep
+* The `create` command cannot be used if the specified `path` already exists as a file
+* If a `command` generates a long output, it will be truncated and marked with `<response clipped>`
+
+Notes for using the `str_replace` command:
+* The `old_str` parameter should match EXACTLY one or more consecutive lines from the original file. Be mindful of whitespaces!
+* If the `old_str` parameter is not unique in the file, the replacement will not be performed. Make sure to include enough context in `old_str` to make it unique
+* The `new_str` parameter should contain the edited lines that should replace the `old_str`
+"""
+
+str_replace_editor_tool = {
+    "type": "function",
+    "function": {
+        "name": "str_replace_editor",
+        "description": _STR_REPLACE_EDITOR_DESCRIPTION,
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "command": {
+                    "description": f"The command to run. Allowed options are: {', '.join(f'`{cmd}`' for cmd in ALLOWED_STR_REPLACE_EDITOR_COMMANDS)}.",
+                    "enum": ALLOWED_STR_REPLACE_EDITOR_COMMANDS,
+                    "type": "string",
+                },
+                "path": {
+                    "description": "Absolute path to file or directory, e.g. `/testbed/file.py` or `/testbed`.",
+                    "type": "string",
+                },
+                "file_text": {
+                    "description": "Required for the `create` command, contains the content of the file to be created.",
+                    "type": "string",
+                },
+                "old_str": {
+                    "description": "Required for the `str_replace` command, specifies the string in `path` to replace.",
+                    "type": "string",
+                },
+                "new_str": {
+                    "description": "Optional for the `str_replace` command to specify the replacement string. Required for the `insert` command to specify the string to insert.",
+                    "type": "string",
+                },
+                "insert_line": {
+                    "description": "Required for the `insert` command. The `new_str` will be inserted AFTER the line specified.",
+                    "type": "integer",
+                },
+                "view_range": {
+                    "description": "Optional for the `view` command when `path` points to a file. Specifies the line range to view. E.g., [11, 12] shows lines 11 and 12. Indexing starts at 1. Use [start_line, -1] to show all lines from `start_line` to the end.",
+                    "type": "array",
+                    "items": {"type": "integer"},
+                },
+            },
+            "required": ["command", "path"],
+        },
+    },
+}
+
+
+_R2EGYM_BASH_EXECUTE_DESCRIPTION = """
+Description: Execute a bash command in the terminal.
+
+Parameters:
+  (1) command (string, required): The bash command to execute. For example: `python my_script.py`
+"""
+
+r2egym_bash_execute_tool = {
+    "type": "function",
+    "function": {
+        "name": "execute_bash",
+        "description": _R2EGYM_BASH_EXECUTE_DESCRIPTION,
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "cmd": {
+                    "type": "string",
+                    "description": "The command (and optional arguments) to execute. For example: 'python my_script.py'",
+                }
+            },
+            "required": ["cmd"],
+        },
+    },
+}
+
+
+_BASH_DESCRIPTION = """
+Description: Execute a bash command in the terminal. Note: all commands will be executed in the current working directory: {PWD}
+
+WARNING: UNSANDBOXED. Commands run with the full privileges of the provider
+process and there is no command filtering. This tool is only safe to register
+when the provider itself runs inside an isolated container or VM. Commands
+are killed after TOOLPLANE_BASH_TIMEOUT_SECONDS (default 120).
+
+Parameters:
+  (1) command (string, optional): The bash command to execute. For example: `python my_script.py`. If not provided, will show help.
+"""
+
+execute_bash_tool = {
+    "type": "function",
+    "function": {
+        "name": "execute_bash",
+        "description": _BASH_DESCRIPTION,
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "command": {
+                    "type": "string",
+                    "description": "The command (and optional arguments) to execute. For example: 'python my_script.py'",
+                }
+            },
+            "required": [],
+        },
+    },
+}
+
+
+_SEARCH_DESCRIPTION = """
+Description: Search for a term in either a directory or a single file.
+
+Behavior:
+* If `--path` points to a directory (default is `.`), we recursively search all non-hidden files and directories.
+* If `--path` points to a file, we run `grep -n` on that file to find line numbers containing the search term.
+* If more than 100 files match (directory search scenario), the tool will stop listing and inform you to narrow your search.
+* If no files are found that match your search term, the tool will inform you of that as well.
+
+**Parameters:**
+  1. **search_term** (`string`, required): The term to search for in files.
+  2. **path** (`string`, optional): The file or directory in which to search. If not provided, defaults to the current directory (i.e., `.`).
+"""
+
+search_tool = {
+    "type": "function",
+    "function": {
+        "name": "search",
+        "description": _SEARCH_DESCRIPTION,
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "search_term": {
+                    "description": "The term to search for in files.",
+                    "type": "string",
+                },
+                "path": {
+                    "description": "The file or directory to search in. Defaults to `.` if not specified.",
+                    "type": "string",
+                },
+            },
+            "required": ["search_term"],
+        },
+    },
+}
+
+# V1 Finish
+_FINISH_DESCRIPTION = """
+"A simple finish tool with a 'submit' command.\n\n"
+"Notes about the `submit` command:\n"
+"* When invoked with `--result`, the provided string is used for submitting required task results.\n"
+"* If no `--result` is provided, it defaults to an empty string.\n\n"
+"**Parameters:**\n"
+"  1. **command** (`string`, required): The command to run. Currently allowed option is: `submit`.\n"
+"     - Allowed value: [`submit`]\n"
+"  2. **result** (`string`, optional): The result text to submit. Defaults to an empty string.\n"
+"""
+finish_tool = {
+    "type": "function",
+    "function": {
+        "name": "finish",
+        "description": _FINISH_DESCRIPTION,
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "command": {
+                    "description": "The command to run. Currently only `submit` is supported.",
+                    "type": "string",
+                    "enum": ["submit"],
+                },
+                "result": {
+                    "description": "Optional. The result text to submit. Defaults to an empty string if not provided.",
+                    "type": "string",
+                },
+            },
+            "required": ["command"],
+        },
+    },
+}
+
+# V2 Submit
+_SUBMIT_DESCRIPTION = """
+A simple submit tool to finish tasks.
+
+This tool signals completion of a task or submission of results.
+No parameters required - simply call to indicate task completion.
+"""
+
+submit_tool = {
+    "type": "function",
+    "function": {
+        "name": "submit",
+        "description": _SUBMIT_DESCRIPTION,
+        "parameters": {
+            "type": "object",
+            "properties": {},
+            "required": [],
+        },
+    },
+}

toolplane/toolkits/swe/execute_bash.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""
+Description: Execute a bash command in the terminal.
+
+WARNING: this tool provides NO sandboxing. It runs model-supplied shell
+commands with the full privileges of the provider process. Only register it
+on a provider that is itself isolated (container or VM). The former
+first-token command blocklist was deliberately removed: such filters are
+trivially bypassed (absolute paths, env assignments, `sh -c`, ...) and
+provided a false sense of guardrail while blocking nothing.
+
+Environment:
+  TOOLPLANE_BASH_TIMEOUT_SECONDS  maximum runtime per command (default 120).
+  TOOLPLANE_WORKSPACE_ROOT        when set, commands run with this working
+                                  directory. This is a convenience and a soft
+                                  boundary only — the shell itself is not
+                                  confined; real isolation must come from the
+                                  provider's container/VM.
+
+Parameters:
+  --command (string, optional): The bash command to execute. For example: --command 'python my_script.py'. If not provided, will show help.
+"""
+
+import argparse
+import os
+import subprocess
+import sys
+
+DEFAULT_COMMAND_TIMEOUT_SECONDS = 120.0
+
+
+def command_timeout_seconds():
+    raw = os.environ.get("TOOLPLANE_BASH_TIMEOUT_SECONDS", "").strip()
+    if not raw:
+        return DEFAULT_COMMAND_TIMEOUT_SECONDS
+    try:
+        value = float(raw)
+    except ValueError:
+        return DEFAULT_COMMAND_TIMEOUT_SECONDS
+    return value if value > 0 else DEFAULT_COMMAND_TIMEOUT_SECONDS
+
+
+def workspace_root():
+    root = os.environ.get("TOOLPLANE_WORKSPACE_ROOT", "").strip()
+    return root or None
+
+
+def run_command(cmd):
+    """Run a shell command with a hard timeout and the configured workspace cwd."""
+    return subprocess.run(
+        cmd,
+        shell=True,
+        capture_output=True,
+        text=True,
+        timeout=command_timeout_seconds(),
+        cwd=workspace_root(),
+    )
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Execute a bash command.")
+    parser.add_argument(
+        "command",
+        type=str,
+        help="The command (and optional arguments) to execute. For example: 'python my_script.py'",
+    )
+    args = parser.parse_args()
+
+    try:
+        result = run_command(args.command)
+    except subprocess.TimeoutExpired:
+        print(
+            f"Command timed out after {command_timeout_seconds():.0f}s "
+            "(configure via TOOLPLANE_BASH_TIMEOUT_SECONDS)."
+        )
+        sys.exit(124)
+
+    if result.returncode != 0:
+        print("Error executing command:\n")
+        print("[STDOUT]\n")
+        print(result.stdout.strip(), "\n")
+        print("[STDERR]\n")
+        print(result.stderr.strip())
+        sys.exit(result.returncode)
+
+    print("[STDOUT]\n")
+    print(result.stdout.strip(), "\n")
+    print("[STDERR]\n")
+    print(result.stderr.strip())
+
+
+if __name__ == "__main__":
+    main()