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

pycodex/tools/update_plan_tool.py

@@ -0,0 +1,79 @@
+"""`update_plan` tool for the Python Codex prototype.
+
+Original Codex mapping:
+- Corresponds to the original Codex `update_plan` tool.
+
+Expected behavior:
+- Give the model a structured checklist with optional explanation text.
+- Validate that at most one step is `in_progress`.
+- Persist the latest plan in local runtime state and return the standard
+  confirmation text Codex uses.
+"""
+
+from __future__ import annotations
+
+from ..protocol import JSONDict, JSONValue
+from ..runtime_services import PlanItem, PlanStore
+from .base_tool import BaseTool, ToolContext
+
+VALID_PLAN_STATUSES = {"pending", "in_progress", "completed"}
+
+
+class UpdatePlanTool(BaseTool):
+    name = "update_plan"
+    description = (
+        "Updates the task plan. Provide an optional explanation and a list of "
+        "plan items, each with a step and status. At most one step can be "
+        "in_progress at a time."
+    )
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "explanation": {"type": "string"},
+            "plan": {
+                "type": "array",
+                "description": "The list of steps",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "step": {"type": "string"},
+                        "status": {
+                            "type": "string",
+                            "description": "One of: pending, in_progress, completed",
+                        },
+                    },
+                    "required": ["step", "status"],
+                    "additionalProperties": False,
+                },
+            },
+        },
+        "required": ["plan"],
+        "additionalProperties": False,
+    }
+    supports_parallel = False
+
+    def __init__(self, plan_store: PlanStore) -> None:
+        self._plan_store = plan_store
+
+    async def run(self, context: ToolContext, args: JSONDict) -> JSONValue:
+        del context
+        raw_plan = args.get("plan")
+        if not isinstance(raw_plan, list):
+            return "Error: `plan` must be a list."
+
+        plan_items: list[PlanItem] = []
+        for item in raw_plan:
+            if not isinstance(item, dict):
+                return "Error: each `plan` item must be an object."
+            step = str(item.get("step", "")).strip()
+            status = str(item.get("status", "")).strip()
+            if not step:
+                return "Error: each `plan` item must include a non-empty `step`."
+            if status not in VALID_PLAN_STATUSES:
+                return f"Error: invalid plan status `{status}`."
+            plan_items.append(PlanItem(step=step, status=status))
+
+        explanation_value = args.get("explanation")
+        explanation = None if explanation_value in (None, "") else str(explanation_value)
+        self._plan_store.update(explanation, tuple(plan_items))
+        return "Plan updated"

pycodex/tools/view_image_tool.py

@@ -0,0 +1,111 @@
+"""`view_image` tool for the Python Codex prototype.
+
+Original Codex mapping:
+- Corresponds to the original Codex `view_image` tool.
+
+Expected behavior:
+- Load a local image file and turn it into a data URL that can be attached back
+  into the next model request.
+- Accept the documented `path` argument plus the optional `detail: "original"`
+  hint.
+- Return both the JSON object result and the structured `input_image` content
+  item that Codex uses when feeding image tool output back to the model.
+"""
+
+from __future__ import annotations
+
+import base64
+import mimetypes
+from pathlib import Path
+
+from ..protocol import JSONDict, JSONValue
+from .base_tool import BaseTool, StructuredToolOutput, ToolContext
+
+VIEW_IMAGE_OUTPUT_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "image_url": {
+            "type": "string",
+            "description": "Data URL for the loaded image.",
+        },
+        "detail": {
+            "type": ["string", "null"],
+            "description": "Image detail hint returned by view_image. Returns `original` when original resolution is preserved, otherwise `null`.",
+        },
+    },
+    "required": ["image_url", "detail"],
+    "additionalProperties": False,
+}
+
+
+class ViewImageTool(BaseTool):
+    name = "view_image"
+    description = (
+        "View a local image from the filesystem (only use if given a full "
+        "filepath by the user, and the image isn't already attached to the "
+        "thread context within <image ...> tags)."
+    )
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "path": {
+                "type": "string",
+                "description": "Local filesystem path to an image file",
+            },
+            "detail": {
+                "type": "string",
+                "description": "Optional detail override. The only supported value is `original`; omit this field for default resized behavior. Use `original` to preserve the file's original resolution instead of resizing to fit.",
+            },
+        },
+        "required": ["path"],
+        "additionalProperties": False,
+    }
+    output_schema = VIEW_IMAGE_OUTPUT_SCHEMA
+
+    def __init__(self, cwd: str | Path | None = None) -> None:
+        self._workspace_root = Path(cwd or Path.cwd()).resolve()
+
+    async def run(self, context: ToolContext, args: JSONDict) -> JSONValue:
+        del context
+        path_value = str(args.get("path", "")).strip()
+        if not path_value:
+            return "Error: `path` is required."
+
+        detail_value = args.get("detail")
+        if detail_value in (None, ""):
+            detail = None
+        elif detail_value == "original":
+            detail = "original"
+        else:
+            return (
+                "Error: `detail` only supports `original`; omit `detail` for default "
+                f"behavior, got `{detail_value}`."
+            )
+
+        path = Path(path_value)
+        if not path.is_absolute():
+            path = self._workspace_root / path
+        path = path.resolve()
+        if not path.exists():
+            return f"Error: unable to locate image at `{path}`."
+        if not path.is_file():
+            return f"Error: image path `{path}` is not a file."
+
+        mime_type, _ = mimetypes.guess_type(path.name)
+        if not mime_type or not mime_type.startswith("image/"):
+            return f"Error: `{path}` does not look like an image file."
+
+        image_bytes = path.read_bytes()
+        encoded = base64.b64encode(image_bytes).decode("ascii")
+        image_url = f"data:{mime_type};base64,{encoded}"
+        output = {
+            "image_url": image_url,
+            "detail": detail,
+        }
+        image_item: JSONDict = {
+            "type": "input_image",
+            "image_url": image_url,
+        }
+        if detail is not None:
+            image_item["detail"] = detail
+        return StructuredToolOutput(output=output, content_items=(image_item,))

pycodex/tools/wait_agent_tool.py

@@ -0,0 +1,75 @@
+"""`wait_agent` tool for the Python Codex prototype.
+
+Original Codex mapping:
+- Corresponds to the original Codex `wait_agent` collaboration tool.
+
+Expected behavior:
+- Wait for one or more spawned agents to reach a final state.
+- Return the current status map for requested agents, or an empty map when the
+  wait times out.
+"""
+
+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
+
+WAIT_AGENT_OUTPUT_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "status": {
+            "type": "object",
+            "description": "Final statuses keyed by agent id.",
+            "additionalProperties": AGENT_STATUS_SCHEMA,
+        },
+        "timed_out": {
+            "type": "boolean",
+            "description": "Whether the wait call returned due to timeout before any agent reached a final status.",
+        },
+    },
+    "required": ["status", "timed_out"],
+    "additionalProperties": False,
+}
+
+
+class WaitAgentTool(BaseTool):
+    name = "wait_agent"
+    description = (
+        "Wait for agents to reach a final status. Completed statuses may "
+        "include the agent's final message. Returns empty status when timed "
+        "out."
+    )
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "ids": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Agent ids to wait on. Pass multiple ids to wait for whichever finishes first.",
+            },
+            "timeout_ms": {
+                "type": "integer",
+                "description": "Optional timeout in milliseconds.",
+            },
+        },
+        "required": ["ids"],
+        "additionalProperties": False,
+    }
+    output_schema = WAIT_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
+        ids = args.get("ids")
+        if not isinstance(ids, list) or not ids:
+            return "Error: `ids` must be a non-empty list."
+        agent_ids = [str(item).strip() for item in ids if str(item).strip()]
+        if not agent_ids:
+            return "Error: `ids` must include at least one non-empty id."
+        timeout_ms = int(args.get("timeout_ms", 30_000))
+        return await self._subagent_manager.wait_agents(agent_ids, timeout_ms)

pycodex/tools/wait_tool.py

@@ -0,0 +1,68 @@
+"""`wait` tool for the Python Codex prototype.
+
+Original Codex mapping:
+- Corresponds to the original Codex code-mode `wait` tool.
+
+Expected behavior:
+- Wait on a yielded `exec` cell for more output or completion.
+- Optionally terminate the running cell.
+- Return only the new output since the previous `exec` / `wait` snapshot.
+"""
+
+from __future__ import annotations
+
+from ..protocol import JSONDict, JSONValue
+from .base_tool import BaseTool, ToolContext
+from .code_mode_manager import DEFAULT_WAIT_YIELD_TIME_MS, CodeModeManager
+
+
+class WaitTool(BaseTool):
+    name = "wait"
+    description = (
+        "Waits on a yielded `exec` cell and returns new output or completion."
+    )
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "cell_id": {
+                "type": "string",
+                "description": "Identifier of the running exec cell.",
+            },
+            "yield_time_ms": {
+                "type": "integer",
+                "description": "How long to wait (in milliseconds) for more output before yielding again.",
+            },
+            "max_tokens": {
+                "type": "integer",
+                "description": "Maximum number of output tokens to return for this wait call.",
+            },
+            "terminate": {
+                "type": "boolean",
+                "description": "Whether to terminate the running exec cell.",
+            },
+        },
+        "required": ["cell_id"],
+        "additionalProperties": False,
+    }
+    supports_parallel = False
+
+    def __init__(self, manager: CodeModeManager) -> None:
+        self._manager = manager
+
+    async def run(self, context: ToolContext, args: JSONDict) -> JSONValue:
+        del context
+        cell_id = str(args.get("cell_id", "")).strip()
+        if not cell_id:
+            return "Error: `cell_id` is required."
+        return await self._manager.wait(
+            cell_id=cell_id,
+            yield_time_ms=int(args.get("yield_time_ms", DEFAULT_WAIT_YIELD_TIME_MS)),
+            max_tokens=self._optional_int(args, "max_tokens"),
+            terminate=bool(args.get("terminate", False)),
+        )
+
+    def _optional_int(self, args: JSONDict, key: str) -> int | None:
+        value = args.get(key)
+        if value in (None, ""):
+            return None
+        return int(value)

pycodex/tools/web_search_tool.py

@@ -0,0 +1,30 @@
+"""`web_search` tool declaration for the Python Codex prototype.
+
+Original Codex mapping:
+- Corresponds to the original Codex provider-native `web_search` tool.
+
+Expected behavior:
+- Advertise the Responses API built-in web search tool to the model.
+- Let the provider handle search execution directly instead of routing through
+  the local `ToolRegistry`.
+- Never expect a local tool-call round-trip result from the model.
+"""
+
+from __future__ import annotations
+
+from ..protocol import JSONDict, JSONValue
+from .base_tool import BaseTool, ToolContext
+
+
+class WebSearchTool(BaseTool):
+    name = "web_search"
+    description = "Provider-native web search tool declaration."
+    tool_type = "web_search"
+    options = {
+        "external_web_access": True,
+    }
+    supports_parallel = False
+
+    async def run(self, context: ToolContext, args: JSONValue) -> JSONValue:
+        del context, args
+        return "Error: web_search is provider-native and should not be executed locally."

pycodex/tools/write_stdin_tool.py

@@ -0,0 +1,75 @@
+"""`write_stdin` tool for the Python Codex prototype.
+
+Original Codex mapping:
+- Corresponds to the original Codex `write_stdin` tool.
+
+Expected behavior:
+- Write bytes into an existing `exec_command` session.
+- Also support polling with empty input to fetch fresh output from a running
+  session.
+- Reuse the same `session_id` until the process exits.
+"""
+
+from __future__ import annotations
+
+from ..protocol import JSONDict, JSONValue
+from .base_tool import BaseTool, ToolContext
+from .unified_exec_manager import (
+    DEFAULT_WRITE_STDIN_YIELD_TIME_MS,
+    UNIFIED_EXEC_OUTPUT_SCHEMA,
+    UnifiedExecManager,
+)
+
+
+class WriteStdinTool(BaseTool):
+    name = "write_stdin"
+    description = "Writes characters to an existing unified exec session and returns recent output."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "session_id": {
+                "type": "integer",
+                "description": "Identifier of the running unified exec session.",
+            },
+            "chars": {
+                "type": "string",
+                "description": "Bytes to write to stdin (may be empty to poll).",
+            },
+            "yield_time_ms": {
+                "type": "integer",
+                "description": "How long to wait (in milliseconds) for output before yielding.",
+            },
+            "max_output_tokens": {
+                "type": "integer",
+                "description": "Maximum number of tokens to return. Excess output will be truncated.",
+            },
+        },
+        "required": ["session_id"],
+        "additionalProperties": False,
+    }
+    output_schema = UNIFIED_EXEC_OUTPUT_SCHEMA
+    supports_parallel = False
+
+    def __init__(self, manager: UnifiedExecManager) -> None:
+        self._manager = manager
+
+    async def run(self, context: ToolContext, args: JSONDict) -> JSONValue:
+        del context
+        session_id = args.get("session_id")
+        if session_id is None:
+            return "Error: `session_id` is required."
+
+        return await self._manager.write_stdin(
+            session_id=int(session_id),
+            chars=str(args.get("chars", "")),
+            yield_time_ms=int(
+                args.get("yield_time_ms", DEFAULT_WRITE_STDIN_YIELD_TIME_MS)
+            ),
+            max_output_tokens=self._optional_int(args, "max_output_tokens"),
+        )
+
+    def _optional_int(self, args: JSONDict, key: str) -> int | None:
+        value = args.get(key)
+        if value in (None, ""):
+            return None
+        return int(value)

pycodex/utils/__init__.py

@@ -0,0 +1,40 @@
+from .dotenv import DOTENV_FILENAME, load_codex_dotenv, parse_dotenv, parse_dotenv_value
+from .get_env import build_user_agent, get_shell_name, get_timezone_name
+from .random_ids import uuid7_string
+from .visualize import (
+    CliSessionView,
+    Spinner,
+    build_cli_spinner_frame,
+    cli_color_enabled,
+    colorize_cli_message,
+    extract_plan_items,
+    format_cli_plan_messages,
+    format_cli_tool_call_message,
+    format_cli_tool_message,
+    short_id,
+    shorten_title,
+    summarize_tool_event,
+)
+
+__all__ = [
+    "CliSessionView",
+    "DOTENV_FILENAME",
+    "Spinner",
+    "build_user_agent",
+    "build_cli_spinner_frame",
+    "cli_color_enabled",
+    "colorize_cli_message",
+    "extract_plan_items",
+    "format_cli_plan_messages",
+    "format_cli_tool_call_message",
+    "format_cli_tool_message",
+    "get_shell_name",
+    "get_timezone_name",
+    "load_codex_dotenv",
+    "parse_dotenv",
+    "parse_dotenv_value",
+    "short_id",
+    "shorten_title",
+    "summarize_tool_event",
+    "uuid7_string",
+]

pycodex/utils/dotenv.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+ILLEGAL_ENV_VAR_PREFIX = "CODEX_"
+DOTENV_FILENAME = ".env"
+_LOADED_CODEX_DOTENV_HOMES: set[str] = set()
+
+
+def load_codex_dotenv(config_path: str | Path) -> None:
+    codex_home = str(Path(config_path).resolve().parent)
+    if codex_home in _LOADED_CODEX_DOTENV_HOMES:
+        return
+
+    dotenv_path = Path(codex_home) / DOTENV_FILENAME
+    if not dotenv_path.is_file():
+        _LOADED_CODEX_DOTENV_HOMES.add(codex_home)
+        return
+
+    for key, value in parse_dotenv(dotenv_path.read_text()).items():
+        if key.upper().startswith(ILLEGAL_ENV_VAR_PREFIX):
+            continue
+        os.environ[key] = value
+
+    _LOADED_CODEX_DOTENV_HOMES.add(codex_home)
+
+
+def parse_dotenv(text: str) -> dict[str, str]:
+    values: dict[str, str] = {}
+    for raw_line in text.splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[len("export ") :].lstrip()
+        if "=" not in line:
+            continue
+
+        key, raw_value = line.split("=", 1)
+        key = key.strip()
+        if not key:
+            continue
+        values[key] = parse_dotenv_value(raw_value.strip())
+    return values
+
+
+def parse_dotenv_value(raw_value: str) -> str:
+    if not raw_value:
+        return ""
+
+    quote = raw_value[0]
+    if quote in {'"', "'"}:
+        if len(raw_value) >= 2 and raw_value[-1] == quote:
+            inner = raw_value[1:-1]
+        else:
+            inner = raw_value[1:]
+        if quote == "'":
+            return inner
+        return bytes(inner, "utf-8").decode("unicode_escape")
+
+    if " #" in raw_value:
+        raw_value = raw_value.split(" #", 1)[0].rstrip()
+    return raw_value