python-codex 0.1.13__py3-none-any.whl → 0.2.0__py3-none-any.whl

pycodex/tools/exec_command_tool.py

@@ -21,10 +21,17 @@ from .unified_exec_manager import (
 )
 import typing
 
+MIN_EXEC_YIELD_TIME_MS = 250
+MAX_EXEC_YIELD_TIME_MS = 30_000
+
 
 class ExecCommandTool(BaseTool):
     name = "exec_command"
-    description = "Runs a command in a PTY, returning output or a session ID for ongoing interaction."
+    description = (
+        "Runs a command in a PTY, returning output or a session ID for ongoing interaction. "
+        "For long tasks, you can reply first; when the task finishes, you will be "
+        "invoked to continue."
+    )
     input_schema = {
         "type": "object",
         "properties": {
@@ -34,27 +41,27 @@ class ExecCommandTool(BaseTool):
             },
             "workdir": {
                 "type": "string",
-                "description": "Optional working directory to run the command in; defaults to the turn cwd.",
-            },
-            "shell": {
-                "type": "string",
-                "description": "Shell binary to launch. Defaults to the user's default shell.",
-            },
-            "login": {
-                "type": "boolean",
-                "description": "Whether to run the shell with -l/-i semantics. Defaults to true.",
+                "description": "Working directory for the command. Defaults to the turn cwd.",
             },
             "tty": {
                 "type": "boolean",
-                "description": "Whether to allocate a TTY for the command. Defaults to false (plain pipes); set to true to open a PTY and access TTY process.",
+                "description": "True allocates a PTY for the command; false or omitted uses plain pipes.",
             },
             "yield_time_ms": {
-                "type": "integer",
-                "description": "How long to wait (in milliseconds) for output before yielding.",
+                "type": "number",
+                "description": "Wait before yielding output. Defaults to 10000 ms; effective range is 250-30000 ms.",
             },
             "max_output_tokens": {
-                "type": "integer",
-                "description": "Maximum number of tokens to return. Excess output will be truncated.",
+                "type": "number",
+                "description": "Output token budget. Defaults to 10000 tokens; larger requests may be capped by policy.",
+            },
+            "shell": {
+                "type": "string",
+                "description": "Shell binary to launch. Defaults to the user's default shell.",
+            },
+            "login": {
+                "type": "boolean",
+                "description": "True runs the shell with -l/-i semantics; false disables them. Defaults to true.",
             },
         },
         "required": ["cmd"],
@@ -78,7 +85,13 @@ class ExecCommandTool(BaseTool):
             shell=self._optional_string(args, "shell"),
             login=bool(args.get("login", DEFAULT_LOGIN)),
             tty=bool(args.get("tty", DEFAULT_TTY)),
-            yield_time_ms=int(args.get("yield_time_ms", DEFAULT_EXEC_YIELD_TIME_MS)),
+            yield_time_ms=self._bounded_int(
+                args,
+                "yield_time_ms",
+                DEFAULT_EXEC_YIELD_TIME_MS,
+                MIN_EXEC_YIELD_TIME_MS,
+                MAX_EXEC_YIELD_TIME_MS,
+            ),
             max_output_tokens=self._optional_int(args, "max_output_tokens"),
         )
 
@@ -93,3 +106,14 @@ class ExecCommandTool(BaseTool):
         if value in (None, ""):
             return None
         return int(value)
+
+    def _bounded_int(
+        self,
+        args: 'JSONDict',
+        key: 'str',
+        default: 'int',
+        minimum: 'int',
+        maximum: 'int',
+    ) -> 'int':
+        value = int(args.get(key, default))
+        return min(max(value, minimum), maximum)

pycodex/tools/exec_tool.py

@@ -28,8 +28,24 @@ SOURCE: /[\s\S]+/
 class ExecTool(BaseTool):
     name = "exec"
     description = (
-        "Runs raw JavaScript in an isolated context. Send raw JavaScript "
-        "source text, not JSON, quoted strings, or markdown code fences."
+        "Run JavaScript code to orchestrate/compose tool calls\n"
+        "- Evaluates the provided JavaScript code in a fresh V8 isolate as an "
+        "async module.\n"
+        "- All nested tools are available on the global `tools` object, for "
+        "example `await tools.exec_command(...)`.\n"
+        "- Nested tool methods take either a string or an object as their input "
+        "argument.\n"
+        "- Runs raw JavaScript -- no Node, no file system, no network access, "
+        "no console.\n"
+        "- Accepts raw JavaScript source text, not JSON, quoted strings, or "
+        "markdown code fences.\n"
+        "- You may optionally start the tool input with a first-line pragma "
+        "like `// @exec: {\"yield_time_ms\": 10000, "
+        "\"max_output_tokens\": 1000}`.\n"
+        "- `yield_time_ms` asks `exec` to yield early if the script is still "
+        "running. Defaults to 10000 ms.\n"
+        "- `max_output_tokens` sets the token budget for direct `exec` results. "
+        "Defaults to 10000 tokens."
     )
     tool_type = "custom"
     format = {

pycodex/tools/grep_files_tool.py

@@ -26,18 +26,31 @@ COMMAND_TIMEOUT_SECONDS = 30
 class GrepFilesTool(BaseTool):
     name = "grep_files"
     description = (
-        "Finds files whose contents match the pattern and lists them by "
-        "modification time."
+        "Search file contents with ripgrep and return matching file paths, "
+        "newest first."
     )
     input_schema = {
         "type": "object",
         "properties": {
-            "pattern": {"type": "string"},
-            "include": {"type": "string"},
-            "path": {"type": "string"},
-            "limit": {"type": "integer"},
+            "pattern": {
+                "type": "string",
+                "description": "Regular expression to search for.",
+            },
+            "include": {
+                "type": "string",
+                "description": "Optional glob pattern to limit searched file names.",
+            },
+            "path": {
+                "type": "string",
+                "description": "File or directory to search. Defaults to the tool cwd.",
+            },
+            "limit": {
+                "type": "integer",
+                "description": "Maximum number of matching paths to return.",
+            },
         },
         "required": ["pattern"],
+        "additionalProperties": False,
     }
 
     def __init__(self, cwd: 'typing.Union[typing.Union[str, Path], None]' = None) -> 'None':

pycodex/tools/ipython_tool.py

@@ -7,8 +7,9 @@ from .base_tool import BaseTool, ToolContext
 class IPythonTool(BaseTool):
     name = "ipython"
     description = (
-        "Execute Python code in the current IPython kernel namespace. "
-        "Use this to inspect live Python variables in the user's IPython session."
+        "Execute Python code in the current IPython kernel namespace. Use this "
+        "only when running inside IPython and live notebook/session variables "
+        "need to be inspected."
     )
     input_schema = {
         "type": "object",

pycodex/tools/list_dir_tool.py

@@ -23,18 +23,31 @@ INDENTATION_SPACES = 2
 class ListDirTool(BaseTool):
     name = "list_dir"
     description = (
-        "Lists entries in a local directory with 1-indexed entry numbers and "
-        "simple type labels."
+        "List entries in a local directory as a stable tree slice with simple "
+        "type labels."
     )
     input_schema = {
         "type": "object",
         "properties": {
-            "dir_path": {"type": "string"},
-            "offset": {"type": "integer"},
-            "limit": {"type": "integer"},
-            "depth": {"type": "integer"},
+            "dir_path": {
+                "type": "string",
+                "description": "Absolute path to the directory to list.",
+            },
+            "offset": {
+                "type": "integer",
+                "description": "1-indexed entry offset for pagination. Defaults to 1.",
+            },
+            "limit": {
+                "type": "integer",
+                "description": "Maximum number of entries to return. Defaults to 25.",
+            },
+            "depth": {
+                "type": "integer",
+                "description": "Maximum directory depth to include. Defaults to 2.",
+            },
         },
         "required": ["dir_path"],
+        "additionalProperties": False,
     }
 
     async def run(self, context: 'ToolContext', args: 'JSONDict') -> 'JSONValue':

pycodex/tools/read_file_tool.py

@@ -30,22 +30,52 @@ class ReadFileTool(BaseTool):
     input_schema = {
         "type": "object",
         "properties": {
-            "file_path": {"type": "string"},
-            "offset": {"type": "integer"},
-            "limit": {"type": "integer"},
-            "mode": {"type": "string"},
+            "file_path": {
+                "type": "string",
+                "description": "Absolute path to the file to read.",
+            },
+            "offset": {
+                "type": "integer",
+                "description": "1-indexed starting line number. Defaults to 1.",
+            },
+            "limit": {
+                "type": "integer",
+                "description": "Maximum number of lines to return. Defaults to 2000.",
+            },
+            "mode": {
+                "type": "string",
+                "description": "Read mode. Use `slice` for a line range or `indentation` for an indentation-aware block.",
+            },
             "indentation": {
                 "type": "object",
+                "description": "Options for indentation-aware block mode.",
                 "properties": {
-                    "anchor_line": {"type": "integer"},
-                    "max_levels": {"type": "integer"},
-                    "include_siblings": {"type": "boolean"},
-                    "include_header": {"type": "boolean"},
-                    "max_lines": {"type": "integer"},
+                    "anchor_line": {
+                        "type": "integer",
+                        "description": "1-indexed anchor line for block expansion.",
+                    },
+                    "max_levels": {
+                        "type": "integer",
+                        "description": "How many indentation levels above the anchor to include. Use 0 for file-root scope.",
+                    },
+                    "include_siblings": {
+                        "type": "boolean",
+                        "description": "Whether to include sibling blocks at the same indentation level.",
+                    },
+                    "include_header": {
+                        "type": "boolean",
+                        "description": "Whether to include immediately preceding header/comment lines.",
+                    },
+                    "max_lines": {
+                        "type": "integer",
+                        "description": "Maximum number of lines to return in indentation mode.",
+                    },
                 },
+                "additionalProperties": False,
             },
         },
         "required": ["file_path"],
+        "additionalProperties": False,
     }
 
     async def run(self, context: 'ToolContext', args: 'JSONDict') -> 'JSONValue':

pycodex/tools/request_permissions_tool.py

@@ -55,7 +55,13 @@ class RequestPermissionsTool(BaseTool):
     name = "request_permissions"
     description = (
         "Request additional filesystem or network permissions from the user "
-        "and wait for a response."
+        "and wait for the client to grant a subset of the requested permission "
+        "profile. Use environment_id to target a specific attached "
+        "environment; omit it to use the primary environment. Relative "
+        "filesystem paths resolve against the selected environment cwd. "
+        "Granted permissions apply automatically to later shell-like commands "
+        "in the current turn, or for the rest of the session if the client "
+        "approves them at session scope."
     )
     input_schema = {
         "type": "object",
@@ -64,6 +70,10 @@ class RequestPermissionsTool(BaseTool):
                 "type": "string",
                 "description": "Optional short explanation for why additional permissions are needed.",
             },
+            "environment_id": {
+                "type": "string",
+                "description": "Environment id from <environment_context>. Omit to use the primary environment.",
+            },
             "permissions": REQUEST_PERMISSION_PROFILE_SCHEMA,
         },
         "required": ["permissions"],
@@ -85,6 +95,7 @@ class RequestPermissionsTool(BaseTool):
         response = await self._request_manager.request(
             {
                 "reason": None if args.get("reason") in (None, "") else str(args.get("reason")),
+                "environment_id": None if args.get("environment_id") in (None, "") else str(args.get("environment_id")),
                 "permissions": permissions,
             }
         )

pycodex/tools/request_user_input_tool.py

@@ -20,6 +20,9 @@ from ..runtime_services import RequestUserInputManager
 from .base_tool import BaseTool, StructuredToolOutput, ToolContext
 import typing
 
+MIN_AUTO_RESOLUTION_MS = 60_000
+MAX_AUTO_RESOLUTION_MS = 240_000
+
 REQUEST_USER_INPUT_QUESTION_SCHEMA = {
     "type": "object",
     "properties": {
@@ -96,7 +99,11 @@ def request_user_input_tool_description(
         allowed_modes = "Plan mode"
     return (
         "Request user input for one to three short questions and wait for the "
-        f"response. This tool is only available in {allowed_modes}."
+        f"response. Set autoResolutionMs, from {MIN_AUTO_RESOLUTION_MS} to "
+        f"{MAX_AUTO_RESOLUTION_MS} milliseconds, only when the question is "
+        "useful but non-blocking and continuing with best judgment is "
+        "acceptable if the user does not answer; omit it when explicit user "
+        f"input is required. This tool is only available in {allowed_modes}."
     )
 
 
@@ -110,6 +117,20 @@ class RequestUserInputTool(BaseTool):
                 "type": "array",
                 "description": "Questions to show the user. Prefer 1 and do not exceed 3",
                 "items": REQUEST_USER_INPUT_QUESTION_SCHEMA,
+            },
+            "autoResolutionMs": {
+                "type": "number",
+                "description": (
+                    "Optional auto-resolution window in milliseconds, from "
+                    f"{MIN_AUTO_RESOLUTION_MS} to {MAX_AUTO_RESOLUTION_MS}. "
+                    "Include this only when the question is useful but "
+                    "non-blocking and continuing with best judgment is "
+                    "acceptable if the user does not answer; omit it when "
+                    "explicit user input is required before continuing. Use "
+                    f"{MIN_AUTO_RESOLUTION_MS} for lightly helpful context and "
+                    f"up to {MAX_AUTO_RESOLUTION_MS} when the answer would "
+                    "materially unblock better work."
+                ),
             }
         },
         "required": ["questions"],
@@ -157,6 +178,12 @@ class RequestUserInputTool(BaseTool):
                 for question in questions
             ]
         }
+        auto_resolution_ms = args.get("autoResolutionMs")
+        if auto_resolution_ms not in (None, ""):
+            request_payload["autoResolutionMs"] = min(
+                max(int(auto_resolution_ms), MIN_AUTO_RESOLUTION_MS),
+                MAX_AUTO_RESOLUTION_MS,
+            )
         response = await self._request_manager.request(request_payload)
         if response is None:
             return "request_user_input was cancelled before receiving a response"

pycodex/tools/send_input_tool.py

@@ -32,7 +32,9 @@ class SendInputTool(BaseTool):
     name = "send_input"
     description = (
         "Send a message to an existing agent. Use interrupt=true to redirect "
-        "work immediately."
+        "work immediately. You should reuse the agent by send_input if you "
+        "believe your assigned task is highly dependent on the context of a "
+        "previous task."
     )
     input_schema = {
         "type": "object",
@@ -48,7 +50,7 @@ class SendInputTool(BaseTool):
             "items": COLLAB_INPUT_ITEMS_SCHEMA,
             "interrupt": {
                 "type": "boolean",
-                "description": "When true, stop the agent's current task and handle this immediately. When false (default), queue this message.",
+                "description": "True interrupts the current task and handles this message immediately; false or omitted queues it.",
             },
         },
         "required": ["id"],

pycodex/tools/shell_command_tool.py

@@ -18,22 +18,39 @@ from ..protocol import JSONDict, JSONValue
 from .base_tool import BaseTool, ToolContext
 import typing
 
-DEFAULT_SHELL_TIMEOUT_MS = 30_000
+DEFAULT_SHELL_TIMEOUT_MS = 10_000
 MAX_OUTPUT_CHARS = 12_000
 
 
 class ShellCommandTool(BaseTool):
     name = "shell_command"
-    description = "Runs a shell command string and returns its output."
+    description = (
+        "Runs a shell command and returns its output.\n"
+        "- Always set the `workdir` param when using the shell_command "
+        "function. Do not use `cd` unless absolutely necessary."
+    )
     input_schema = {
         "type": "object",
         "properties": {
-            "command": {"type": "string"},
-            "workdir": {"type": "string"},
-            "timeout_ms": {"type": "integer"},
-            "login": {"type": "boolean"},
+            "command": {
+                "type": "string",
+                "description": "Shell script to run in the user's default shell.",
+            },
+            "workdir": {
+                "type": "string",
+                "description": "Working directory for the command. Defaults to the turn cwd.",
+            },
+            "timeout_ms": {
+                "type": "integer",
+                "description": "Maximum command runtime. Defaults to 10000 ms.",
+            },
+            "login": {
+                "type": "boolean",
+                "description": "True runs with login shell semantics; false disables them. Defaults to true.",
+            },
         },
         "required": ["command"],
+        "additionalProperties": False,
     }
     supports_parallel = False
 

pycodex/tools/shell_tool.py

@@ -25,8 +25,9 @@ MAX_OUTPUT_CHARS = 12_000
 class ShellTool(BaseTool):
     name = "shell"
     description = (
-        "Runs a shell command and returns its output. The command must be passed "
-        "as argv, typically prefixed with ['bash', '-lc'] for shell syntax."
+        "Runs a process from an argv array and returns its output. Use "
+        "`shell_command` for shell-script strings; use this tool when the exact "
+        "argv vector matters."
     )
     input_schema = {
         "type": "object",
@@ -34,11 +35,19 @@ class ShellTool(BaseTool):
             "command": {
                 "type": "array",
                 "items": {"type": "string"},
+                "description": "Command argv to execute.",
+            },
+            "workdir": {
+                "type": "string",
+                "description": "Working directory for the command. Defaults to the tool cwd.",
+            },
+            "timeout_ms": {
+                "type": "integer",
+                "description": "Maximum command runtime in milliseconds.",
             },
-            "workdir": {"type": "string"},
-            "timeout_ms": {"type": "integer"},
         },
         "required": ["command"],
+        "additionalProperties": False,
     }
     supports_parallel = False
 

pycodex/tools/spawn_agent_tool.py

@@ -34,11 +34,34 @@ SPAWN_AGENT_OUTPUT_SCHEMA = {
 
 class SpawnAgentTool(BaseTool):
     name = "spawn_agent"
-    description = (
-        "Spawn a sub-agent for a well-scoped task. Returns the agent id (and "
-        "user-facing nickname when available) to use to communicate with this "
-        "agent."
-    )
+    description = """
+        Spawn a sub-agent for a well-scoped task. Returns the spawned agent id plus the user-facing nickname when available. Spawned agents inherit your current model by default. Omit `model` to use that preferred default; set `model` only when an explicit override is needed.
+This spawn_agent tool provides you access to sub-agents that inherit your current model by default. Do not set the `model` field unless the user explicitly asks for a different model or there is a clear task-specific reason. You should follow the rules and guidelines below to use this tool.
+
+Do not spawn sub-agents unless the user explicitly asks for sub-agents, delegation, or parallel agent work.
+
+### Designing delegated subtasks
+- Subtasks must be concrete, well-defined, and self-contained.
+- Delegated subtasks must materially advance the main task.
+- Do not duplicate work between the main rollout and delegated subtasks.
+- Avoid issuing multiple delegate calls on the same unresolved thread unless the new delegated task is genuinely different and necessary.
+- Narrow the delegated ask to the concrete output you need next.
+- For coding tasks, prefer delegating concrete code-change worker subtasks over read-only explorer analysis when the subagent can make a bounded patch in a clear write scope.
+- When delegating coding work, instruct the submodel to edit files directly in its forked workspace and list the file paths it changed in the final answer.
+- For code-edit subtasks, decompose work so each delegated task has a disjoint write set.
+
+### After you delegate
+- Call wait_agent very sparingly. Only call wait_agent when you need the result immediately for the next critical-path step and you are blocked until it returns.
+- Do not redo delegated subagent tasks yourself; focus on integrating results or tackling non-overlapping work.
+- While the subagent is running in the background, do meaningful non-overlapping work immediately.
+- Do not repeatedly wait by reflex.
+- When a delegated coding task returns, quickly review the uploaded changes, then integrate or refine them.
+
+### Parallel delegation patterns
+- Run multiple independent information-seeking subtasks in parallel when you have distinct questions that can be answered independently.
+- Split implementation into disjoint codebase slices and spawn multiple agents in parallel when the write scopes do not overlap.
+- Delegate verification only when it can run in parallel with ongoing implementation and is likely to catch a concrete risk before final integration.
+- The key is to find opportunities to spawn multiple independent subtasks in parallel within the same round, while ensuring each subtask is well-defined, self-contained, and materially advances the main task."""
     input_schema = {
         "type": "object",
         "properties": {
@@ -53,15 +76,15 @@ class SpawnAgentTool(BaseTool):
             },
             "fork_context": {
                 "type": "boolean",
-                "description": "When true, fork the current thread history into the new agent before sending the initial prompt.",
+                "description": "True forks the current thread history into the new agent; false or omitted starts with only the initial prompt.",
             },
             "model": {
                 "type": "string",
-                "description": "Optional model override for the new agent.",
+                "description": "Model override for the new agent. Omit unless an explicit override is needed.",
             },
             "reasoning_effort": {
                 "type": "string",
-                "description": "Optional reasoning effort override for the new agent.",
+                "description": "Reasoning effort override for the new agent. Omit to inherit the parent effort.",
             },
         },
         "additionalProperties": False,