python-codex 0.0.1__py3-none-any.whl → 0.1.0__py3-none-any.whl

pycodex/tools/read_file_tool.py

@@ -0,0 +1,217 @@
+"""`read_file` tool for the Python Codex prototype.
+
+Original Codex mapping:
+- Corresponds to the original Codex `read_file` tool.
+
+Expected behavior:
+- Read a local file with 1-indexed line numbers.
+- Support the original tool's core slice mode and the indentation-aware block
+  mode used to inspect code structure without shelling out to `sed` or `cat`.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from pathlib import Path
+
+from ..protocol import JSONDict, JSONValue
+from .base_tool import BaseTool, ToolContext
+
+MAX_LINE_LENGTH = 500
+TAB_WIDTH = 4
+COMMENT_PREFIXES = ("#", "//", "--")
+
+
+class ReadFileTool(BaseTool):
+    name = "read_file"
+    description = (
+        "Reads a local file with 1-indexed line numbers, supporting slice and "
+        "indentation-aware block modes."
+    )
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "file_path": {"type": "string"},
+            "offset": {"type": "integer"},
+            "limit": {"type": "integer"},
+            "mode": {"type": "string"},
+            "indentation": {
+                "type": "object",
+                "properties": {
+                    "anchor_line": {"type": "integer"},
+                    "max_levels": {"type": "integer"},
+                    "include_siblings": {"type": "boolean"},
+                    "include_header": {"type": "boolean"},
+                    "max_lines": {"type": "integer"},
+                },
+            },
+        },
+        "required": ["file_path"],
+    }
+
+    async def run(self, context: ToolContext, args: JSONDict) -> JSONValue:
+        del context
+        file_path = Path(str(args.get("file_path", "")))
+        offset = int(args.get("offset", 1))
+        limit = int(args.get("limit", 2000))
+        mode = str(args.get("mode", "slice"))
+        indentation = args.get("indentation") or {}
+
+        if not file_path.is_absolute():
+            return "Error: `file_path` must be an absolute path."
+        if offset <= 0:
+            return "Error: `offset` must be a 1-indexed line number."
+        if limit <= 0:
+            return "Error: `limit` must be greater than zero."
+        if not file_path.exists():
+            return f"Error: `{file_path}` does not exist."
+        if not file_path.is_file():
+            return f"Error: `{file_path}` is not a file."
+
+        if mode == "indentation":
+            return self._read_indentation(file_path, offset, limit, indentation)
+        return self._read_slice(file_path, offset, limit)
+
+    def _read_slice(self, file_path: Path, offset: int, limit: int) -> str:
+        lines = file_path.read_text(errors="replace").splitlines()
+        if offset > len(lines):
+            return "Error: `offset` exceeds file length."
+
+        selected = lines[offset - 1 : offset - 1 + limit]
+        return "\n".join(
+            f"L{line_number}: {self._format_line(text)}"
+            for line_number, text in enumerate(selected, start=offset)
+        )
+
+    def _read_indentation(
+        self,
+        file_path: Path,
+        offset: int,
+        limit: int,
+        indentation: JSONDict,
+    ) -> str:
+        lines = self._collect_line_records(file_path)
+        anchor_line = int(indentation.get("anchor_line", offset))
+        max_levels = int(indentation.get("max_levels", 0))
+        include_siblings = bool(indentation.get("include_siblings", False))
+        include_header = bool(indentation.get("include_header", True))
+        max_lines = int(indentation.get("max_lines", limit))
+
+        if anchor_line <= 0:
+            return "Error: `anchor_line` must be a 1-indexed line number."
+        if anchor_line > len(lines):
+            return "Error: `anchor_line` exceeds file length."
+        if max_lines <= 0:
+            return "Error: `max_lines` must be greater than zero."
+
+        anchor_index = anchor_line - 1
+        effective_indents = self._compute_effective_indents(lines)
+        anchor_indent = effective_indents[anchor_index]
+        min_indent = 0 if max_levels == 0 else max(anchor_indent - max_levels * TAB_WIDTH, 0)
+        final_limit = min(limit, max_lines, len(lines))
+
+        if final_limit == 1:
+            record = lines[anchor_index]
+            return f"L{record['number']}: {record['display']}"
+
+        upper = anchor_index - 1
+        lower = anchor_index + 1
+        upper_min_indent_count = 0
+        lower_min_indent_count = 0
+        selected = deque([lines[anchor_index]])
+
+        while len(selected) < final_limit:
+            progressed = 0
+
+            if upper >= 0:
+                if effective_indents[upper] >= min_indent:
+                    selected.appendleft(lines[upper])
+                    progressed += 1
+                    if effective_indents[upper] == min_indent and not include_siblings:
+                        allow_header_comment = include_header and lines[upper]["is_comment"]
+                        can_take_line = allow_header_comment or upper_min_indent_count == 0
+                        if can_take_line:
+                            upper_min_indent_count += 1
+                        else:
+                            selected.popleft()
+                            progressed -= 1
+                            upper = -1
+                            if progressed == 0 and lower >= len(lines):
+                                break
+                            continue
+                    upper -= 1
+                else:
+                    upper = -1
+
+            if len(selected) >= final_limit:
+                break
+
+            if lower < len(lines):
+                if effective_indents[lower] >= min_indent:
+                    selected.append(lines[lower])
+                    progressed += 1
+                    if effective_indents[lower] == min_indent and not include_siblings:
+                        if lower_min_indent_count > 0:
+                            selected.pop()
+                            progressed -= 1
+                            lower = len(lines)
+                            if progressed == 0 and upper < 0:
+                                break
+                            continue
+                        lower_min_indent_count += 1
+                    lower += 1
+                else:
+                    lower = len(lines)
+
+            if progressed == 0:
+                break
+
+        self._trim_empty_lines(selected)
+        return "\n".join(
+            f"L{record['number']}: {record['display']}" for record in selected
+        )
+
+    def _collect_line_records(self, file_path: Path) -> list[dict[str, object]]:
+        records = []
+        for number, raw in enumerate(file_path.read_text(errors="replace").splitlines(), start=1):
+            records.append(
+                {
+                    "number": number,
+                    "raw": raw,
+                    "display": self._format_line(raw),
+                    "indent": self._measure_indent(raw),
+                    "is_comment": raw.strip().startswith(COMMENT_PREFIXES),
+                }
+            )
+        return records
+
+    def _compute_effective_indents(self, records: list[dict[str, object]]) -> list[int]:
+        effective = []
+        previous_indent = 0
+        for record in records:
+            if not str(record["raw"]).strip():
+                effective.append(previous_indent)
+            else:
+                previous_indent = int(record["indent"])
+                effective.append(previous_indent)
+        return effective
+
+    def _measure_indent(self, line: str) -> int:
+        total = 0
+        for character in line:
+            if character == " ":
+                total += 1
+            elif character == "\t":
+                total += TAB_WIDTH
+            else:
+                break
+        return total
+
+    def _format_line(self, text: str) -> str:
+        return text[:MAX_LINE_LENGTH]
+
+    def _trim_empty_lines(self, records: deque[dict[str, object]]) -> None:
+        while records and not str(records[0]["raw"]).strip():
+            records.popleft()
+        while records and not str(records[-1]["raw"]).strip():
+            records.pop()

pycodex/tools/request_permissions_tool.py

@@ -0,0 +1,95 @@
+"""`request_permissions` tool for the Python Codex prototype.
+
+Original Codex mapping:
+- Corresponds to the original Codex `request_permissions` collaboration tool.
+
+Expected behavior:
+- Ask the user to approve additional filesystem or network permissions.
+- Wait for an interactive response from the client/UI layer.
+- Return the granted permission profile and scope so later tool calls can use it.
+"""
+
+from __future__ import annotations
+
+from ..protocol import JSONDict, JSONValue
+from ..runtime_services import RequestPermissionsManager
+from .base_tool import BaseTool, ToolContext
+
+NETWORK_PERMISSIONS_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "enabled": {
+            "type": "boolean",
+            "description": "Set to true to request network access.",
+        }
+    },
+    "additionalProperties": False,
+}
+
+FILE_SYSTEM_PERMISSIONS_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "read": {
+            "type": "array",
+            "items": {"type": "string"},
+            "description": "Absolute paths to grant read access to.",
+        },
+        "write": {
+            "type": "array",
+            "items": {"type": "string"},
+            "description": "Absolute paths to grant write access to.",
+        },
+    },
+    "additionalProperties": False,
+}
+
+REQUEST_PERMISSION_PROFILE_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "network": NETWORK_PERMISSIONS_SCHEMA,
+        "file_system": FILE_SYSTEM_PERMISSIONS_SCHEMA,
+    },
+    "additionalProperties": False,
+}
+
+
+class RequestPermissionsTool(BaseTool):
+    name = "request_permissions"
+    description = (
+        "Request additional filesystem or network permissions from the user "
+        "and wait for a response."
+    )
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "reason": {
+                "type": "string",
+                "description": "Optional short explanation for why additional permissions are needed.",
+            },
+            "permissions": REQUEST_PERMISSION_PROFILE_SCHEMA,
+        },
+        "required": ["permissions"],
+        "additionalProperties": False,
+    }
+    supports_parallel = False
+
+    def __init__(self, request_manager: RequestPermissionsManager) -> None:
+        self._request_manager = request_manager
+
+    async def run(self, context: ToolContext, args: JSONDict) -> JSONValue:
+        del context
+        permissions = args.get("permissions")
+        if not isinstance(permissions, dict):
+            return "Error: `permissions` must be an object."
+        if not permissions:
+            return "Error: request_permissions requires at least one permission."
+
+        response = await self._request_manager.request(
+            {
+                "reason": None if args.get("reason") in (None, "") else str(args.get("reason")),
+                "permissions": permissions,
+            }
+        )
+        if response is None:
+            return "Error: request_permissions was cancelled before receiving a response."
+        return response

pycodex/tools/request_user_input_tool.py

@@ -0,0 +1,167 @@
+"""`request_user_input` tool for the Python Codex prototype.
+
+Original Codex mapping:
+- Corresponds to the original Codex `request_user_input` collaboration tool.
+
+Expected behavior:
+- In upstream Codex this tool is only actually usable in Plan mode.
+- In the current `pycodex` default-mode path, runtime invocation returns the
+  same fixed unavailable error string as upstream Codex.
+- In Plan mode, the tool validates its question payload, forces `isOther=true`
+  on every question, and returns a JSON-string `function_call_output` with
+  `success=true`.
+"""
+
+from __future__ import annotations
+
+import json
+
+from ..collaboration import collaboration_mode_display_name
+from ..protocol import JSONDict, JSONValue
+from ..runtime_services import RequestUserInputManager
+from .base_tool import BaseTool, StructuredToolOutput, ToolContext
+
+REQUEST_USER_INPUT_QUESTION_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "id": {
+            "type": "string",
+            "description": "Stable identifier for mapping answers (snake_case).",
+        },
+        "header": {
+            "type": "string",
+            "description": "Short header label shown in the UI (12 or fewer chars).",
+        },
+        "question": {
+            "type": "string",
+            "description": "Single-sentence prompt shown to the user.",
+        },
+        "options": {
+            "type": "array",
+            "description": (
+                "Provide 2-3 mutually exclusive choices. Put the recommended option "
+                "first and suffix its label with \"(Recommended)\". Do not include "
+                "an \"Other\" option in this list; the client will add a free-form "
+                "Other option automatically."
+            ),
+            "items": {
+                "type": "object",
+                "properties": {
+                    "label": {
+                        "type": "string",
+                        "description": "User-facing label (1-5 words).",
+                    },
+                    "description": {
+                        "type": "string",
+                        "description": "One short sentence explaining impact/tradeoff if selected.",
+                    },
+                },
+                "required": ["label", "description"],
+                "additionalProperties": False,
+            },
+        },
+    },
+    "required": ["id", "header", "question", "options"],
+    "additionalProperties": False,
+}
+
+
+def request_user_input_is_available(
+    mode: str,
+    default_mode_request_user_input: bool = False,
+) -> bool:
+    normalized = mode.strip().lower()
+    return normalized == "plan" or (
+        default_mode_request_user_input and normalized == "default"
+    )
+
+
+def request_user_input_unavailable_message(
+    mode: str,
+    default_mode_request_user_input: bool = False,
+) -> str | None:
+    if request_user_input_is_available(mode, default_mode_request_user_input):
+        return None
+    return (
+        "request_user_input is unavailable in "
+        f"{collaboration_mode_display_name(mode)} mode"
+    )
+
+
+def request_user_input_tool_description(
+    default_mode_request_user_input: bool = False,
+) -> str:
+    if default_mode_request_user_input:
+        allowed_modes = "Default or Plan mode"
+    else:
+        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}."
+    )
+
+
+class RequestUserInputTool(BaseTool):
+    name = "request_user_input"
+    description = request_user_input_tool_description()
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "questions": {
+                "type": "array",
+                "description": "Questions to show the user. Prefer 1 and do not exceed 3",
+                "items": REQUEST_USER_INPUT_QUESTION_SCHEMA,
+            }
+        },
+        "required": ["questions"],
+        "additionalProperties": False,
+    }
+    supports_parallel = False
+
+    def __init__(
+        self,
+        request_manager: RequestUserInputManager,
+        default_mode_request_user_input: bool = False,
+    ) -> None:
+        self._request_manager = request_manager
+        self._default_mode_request_user_input = default_mode_request_user_input
+        self.description = request_user_input_tool_description(
+            default_mode_request_user_input
+        )
+
+    async def run(self, context: ToolContext, args: JSONDict) -> JSONValue:
+        unavailable = request_user_input_unavailable_message(
+            context.collaboration_mode,
+            self._default_mode_request_user_input,
+        )
+        if unavailable is not None:
+            return unavailable
+
+        questions = args.get("questions")
+        if not isinstance(questions, list):
+            raise ValueError("questions must be a list")
+
+        if any(
+            not isinstance(question, dict)
+            or not isinstance(question.get("options"), list)
+            or not question["options"]
+            for question in questions
+        ):
+            return "request_user_input requires non-empty options for every question"
+
+        request_payload = {
+            "questions": [
+                {
+                    **question,
+                    "isOther": True,
+                }
+                for question in questions
+            ]
+        }
+        response = await self._request_manager.request(request_payload)
+        if response is None:
+            return "request_user_input was cancelled before receiving a response"
+        return StructuredToolOutput(
+            json.dumps(response, ensure_ascii=False, separators=(",", ":")),
+            success=True,
+        )

pycodex/tools/resume_agent_tool.py

@@ -0,0 +1,56 @@
+"""`resume_agent` tool for the Python Codex prototype.
+
+Original Codex mapping:
+- Corresponds to the original Codex `resume_agent` collaboration tool.
+
+Expected behavior:
+- Restart a previously closed local sub-agent runtime.
+- Return the agent's current status payload.
+"""
+
+from __future__ import annotations
+
+from ..protocol import JSONDict, JSONValue
+from ..runtime_services import SubAgentManager
+from .agent_tool_schemas import AGENT_STATUS_SCHEMA
+from .base_tool import BaseTool, ToolContext
+
+RESUME_AGENT_OUTPUT_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "status": AGENT_STATUS_SCHEMA,
+    },
+    "required": ["status"],
+    "additionalProperties": False,
+}
+
+
+class ResumeAgentTool(BaseTool):
+    name = "resume_agent"
+    description = (
+        "Resume a previously closed agent by id so it can receive send_input "
+        "and wait_agent calls."
+    )
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "id": {
+                "type": "string",
+                "description": "Agent id to resume.",
+            }
+        },
+        "required": ["id"],
+        "additionalProperties": False,
+    }
+    output_schema = RESUME_AGENT_OUTPUT_SCHEMA
+    supports_parallel = False
+
+    def __init__(self, subagent_manager: SubAgentManager) -> None:
+        self._subagent_manager = subagent_manager
+
+    async def run(self, context: ToolContext, args: JSONDict) -> JSONValue:
+        del context
+        agent_id = str(args.get("id", "")).strip()
+        if not agent_id:
+            return "Error: `id` is required."
+        return await self._subagent_manager.resume_agent(agent_id)

pycodex/tools/send_input_tool.py

@@ -0,0 +1,106 @@
+"""`send_input` tool for the Python Codex prototype.
+
+Original Codex mapping:
+- Corresponds to the original Codex `send_input` collaboration tool.
+
+Expected behavior:
+- Send a follow-up message to an existing spawned agent.
+- Optionally interrupt the agent's current turn before queueing the new input.
+- Return the submission id for the queued input.
+"""
+
+from __future__ import annotations
+
+from ..protocol import JSONDict, JSONValue
+from ..runtime_services import SubAgentManager
+from .agent_tool_schemas import COLLAB_INPUT_ITEMS_SCHEMA
+from .base_tool import BaseTool, ToolContext
+
+SEND_INPUT_OUTPUT_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "submission_id": {
+            "type": "string",
+            "description": "Identifier for the queued input submission.",
+        }
+    },
+    "required": ["submission_id"],
+    "additionalProperties": False,
+}
+
+
+class SendInputTool(BaseTool):
+    name = "send_input"
+    description = (
+        "Send a message to an existing agent. Use interrupt=true to redirect "
+        "work immediately."
+    )
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "id": {
+                "type": "string",
+                "description": "Agent id to message (from spawn_agent).",
+            },
+            "message": {
+                "type": "string",
+                "description": "Legacy plain-text message to send to the agent. Use either message or items.",
+            },
+            "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.",
+            },
+        },
+        "required": ["id"],
+        "additionalProperties": False,
+    }
+    output_schema = SEND_INPUT_OUTPUT_SCHEMA
+    supports_parallel = False
+
+    def __init__(self, subagent_manager: SubAgentManager) -> None:
+        self._subagent_manager = subagent_manager
+
+    async def run(self, context: ToolContext, args: JSONDict) -> JSONValue:
+        del context
+        agent_id = str(args.get("id", "")).strip()
+        if not agent_id:
+            return "Error: `id` is required."
+        items = args.get("items")
+        if items is not None and not isinstance(items, list):
+            return "Error: `items` must be a list when provided."
+        prompt_text = self._compose_prompt(
+            self._optional_string(args, "message"),
+            items,
+        )
+        if not prompt_text:
+            return "Error: `message` or `items` is required."
+        return await self._subagent_manager.send_input(
+            agent_id,
+            prompt_text,
+            interrupt=bool(args.get("interrupt", False)),
+        )
+
+    def _compose_prompt(
+        self,
+        message: str | None,
+        items: list[dict[str, object]] | None,
+    ) -> str:
+        parts: list[str] = []
+        if message:
+            parts.append(message.strip())
+        for item in items or []:
+            item_type = str(item.get("type", ""))
+            if item_type == "text":
+                text = str(item.get("text", "")).strip()
+                if text:
+                    parts.append(text)
+            else:
+                parts.append(str(item))
+        return "\n\n".join(part for part in parts if part)
+
+    def _optional_string(self, args: JSONDict, key: str) -> str | None:
+        value = args.get(key)
+        if value in (None, ""):
+            return None
+        return str(value)