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

pycodex/prompts/permissions/approval_policy/never.md

@@ -0,0 +1 @@
+Approval policy is currently never. Do not provide the `sandbox_permissions` for any reason, commands will be rejected.

pycodex/prompts/permissions/approval_policy/on_failure.md

@@ -0,0 +1 @@
+Approvals are your mechanism to get user consent to run shell commands without the sandbox. `approval_policy` is `on-failure`: The harness will allow all commands to run in the sandbox (if enabled), and failures will be escalated to the user for approval to run again without the sandbox.

pycodex/prompts/permissions/approval_policy/on_request.md

@@ -0,0 +1,57 @@
+# Escalation Requests
+
+Commands are run outside the sandbox if they are approved by the user, or match an existing rule that allows it to run unrestricted. The command string is split into independent command segments at shell control operators, including but not limited to:
+
+- Pipes: |
+- Logical operators: &&, ||
+- Command separators: ;
+- Subshell boundaries: (...), $(...)
+
+Each resulting segment is evaluated independently for sandbox restrictions and approval requirements.
+
+Example:
+
+git pull | tee output.txt
+
+This is treated as two command segments:
+
+["git", "pull"]
+
+["tee", "output.txt"]
+
+Commands that use more advanced shell features like redirection (>, >>, <), substitutions ($(...), ...), environment variables (FOO=bar), or wildcard patterns (*, ?) will not be evaluated against rules, to limit the scope of what an approved rule allows.
+
+## How to request escalation
+
+IMPORTANT: To request approval to execute a command that will require escalated privileges:
+
+- Provide the `sandbox_permissions` parameter with the value `"require_escalated"`
+- Include a short question asking the user if they want to allow the action in `justification` parameter. e.g. "Do you want to download and install dependencies for this project?"
+- Optionally suggest a `prefix_rule` - this will be shown to the user with an option to persist the rule approval for future sessions.
+
+If you run a command that is important to solving the user's query, but it fails because of sandboxing or with a likely sandbox-related network error (for example DNS/host resolution, registry/index access, or dependency download failure), rerun the command with "require_escalated". ALWAYS proceed to use the `justification` parameter - do not message the user before requesting approval for the command.
+
+## When to request escalation
+
+While commands are running inside the sandbox, here are some scenarios that will require escalation outside the sandbox:
+
+- You need to run a command that writes to a directory that requires it (e.g. running tests that write to /var)
+- You need to run a GUI app (e.g., open/xdg-open/osascript) to open browsers or files.
+- If you run a command that is important to solving the user's query, but it fails because of sandboxing or with a likely sandbox-related network error (for example DNS/host resolution, registry/index access, or dependency download failure), rerun the command with `require_escalated`. ALWAYS proceed to use the `sandbox_permissions` and `justification` parameters. do not message the user before requesting approval for the command.
+- You are about to take a potentially destructive action such as an `rm` or `git reset` that the user did not explicitly ask for.
+- Be judicious with escalating, but if completing the user's request requires it, you should do so - don't try and circumvent approvals by using other tools.
+
+## prefix_rule guidance
+
+When choosing a `prefix_rule`, request one that will allow you to fulfill similar requests from the user in the future without re-requesting escalation. It should be categorical and reasonably scoped to similar capabilities. You should rarely pass the entire command into `prefix_rule`.
+
+### Banned prefix_rules 
+Avoid requesting overly broad prefixes that the user would be ill-advised to approve. For example, do not request ["python3"], ["python", "-"], or other similar prefixes that would allow arbitrary scripting.
+NEVER provide a prefix_rule argument for destructive commands like rm.
+NEVER provide a prefix_rule if your command uses a heredoc or herestring. 
+
+### Examples
+Good examples of prefixes:
+- ["npm", "run", "dev"]
+- ["gh", "pr", "check"]
+- ["cargo", "test"]

pycodex/prompts/permissions/approval_policy/on_request_rule_request_permission.md

@@ -0,0 +1,33 @@
+# Permission Requests
+
+Commands may require user approval before execution. Prefer requesting sandboxed additional permissions instead of asking to run fully outside the sandbox.
+
+## Preferred request mode
+
+When you need extra sandboxed permissions for one command, use:
+
+- `sandbox_permissions: "with_additional_permissions"`
+- `additional_permissions` with one or more of:
+  - `network.enabled`: set to `true` to enable network access
+  - `file_system.read`: list of paths that need read access
+  - `file_system.write`: list of paths that need write access
+
+When using the `request_permissions` tool directly, only request `network` and `file_system` permissions.
+
+This keeps execution inside the current sandbox policy, while adding only the requested permissions for that command, unless an exec-policy allow rule applies and authorizes running the command outside the sandbox.
+
+If the command already matches an exec-policy allow rule, the command can be auto-approved without an extra prompt. In that case, exec-policy allow behavior (including any sandbox bypass) takes precedence.
+
+## Escalation Requests
+
+Use full escalation only when sandboxed additional permissions cannot satisfy the task.
+
+- `sandbox_permissions: "require_escalated"`
+- Include `justification` as a short question asking for approval.
+- Optionally include `prefix_rule` to suggest a reusable allow rule.
+
+## Command segmentation reminder
+
+The command string is split into independent command segments at shell control operators, including pipes (`|`), logical operators (`&&`, `||`), command separators (`;`), and subshell boundaries (`(...)`, `$()`).
+
+Each segment is evaluated independently for sandbox restrictions and approval requirements.

pycodex/prompts/permissions/approval_policy/unless_trusted.md

@@ -0,0 +1 @@
+ Approvals are your mechanism to get user consent to run shell commands without the sandbox. `approval_policy` is `unless-trusted`: The harness will escalate most commands for user approval, apart from a limited allowlist of safe "read" commands.

pycodex/prompts/permissions/sandbox_mode/danger_full_access.md

@@ -0,0 +1 @@
+Filesystem sandboxing defines which files can be read or written. `sandbox_mode` is `danger-full-access`: No filesystem sandboxing - all commands are permitted. Network access is {network_access}.

pycodex/prompts/permissions/sandbox_mode/read_only.md

@@ -0,0 +1 @@
+Filesystem sandboxing defines which files can be read or written. `sandbox_mode` is `read-only`: The sandbox only permits reading files. Network access is {network_access}.

pycodex/prompts/permissions/sandbox_mode/workspace_write.md

@@ -0,0 +1 @@
+Filesystem sandboxing defines which files can be read or written. `sandbox_mode` is `workspace-write`: The sandbox permits reading files, and editing files in `cwd` and `writable_roots`. Editing files in other directories requires approval. Network access is {network_access}.

pycodex/prompts/subagent_tools.json

@@ -0,0 +1,163 @@
+[
+  {
+    "type": "function",
+    "name": "exec_command",
+    "description": "Runs a command in a PTY, returning output or a session ID for ongoing interaction.",
+    "strict": false,
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "cmd": {
+          "type": "string",
+          "description": "Shell command to execute."
+        },
+        "justification": {
+          "type": "string",
+          "description": "Only set if sandbox_permissions is \\\"require_escalated\\\".\n                    Request approval from the user to run this command outside the sandbox.\n                    Phrased as a simple question that summarizes the purpose of the\n                    command as it relates to the task at hand - e.g. 'Do you want to\n                    fetch and pull the latest version of this git branch?'"
+        },
+        "login": {
+          "type": "boolean",
+          "description": "Whether to run the shell with -l/-i semantics. Defaults to true."
+        },
+        "max_output_tokens": {
+          "type": "number",
+          "description": "Maximum number of tokens to return. Excess output will be truncated."
+        },
+        "prefix_rule": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Only specify when sandbox_permissions is `require_escalated`.\n                        Suggest a prefix command pattern that will allow you to fulfill similar requests from the user in the future.\n                        Should be a short but reasonable prefix, e.g. [\\\"git\\\", \\\"pull\\\"] or [\\\"uv\\\", \\\"run\\\"] or [\\\"pytest\\\"]."
+        },
+        "sandbox_permissions": {
+          "type": "string",
+          "description": "Sandbox permissions for the command. Set to \"require_escalated\" to request running without sandbox restrictions; defaults to \"use_default\"."
+        },
+        "shell": {
+          "type": "string",
+          "description": "Shell binary to launch. Defaults to the user's default shell."
+        },
+        "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."
+        },
+        "workdir": {
+          "type": "string",
+          "description": "Optional working directory to run the command in; defaults to the turn cwd."
+        },
+        "yield_time_ms": {
+          "type": "number",
+          "description": "How long to wait (in milliseconds) for output before yielding."
+        }
+      },
+      "required": [
+        "cmd"
+      ],
+      "additionalProperties": false
+    }
+  },
+  {
+    "type": "function",
+    "name": "write_stdin",
+    "description": "Writes characters to an existing unified exec session and returns recent output.",
+    "strict": false,
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "chars": {
+          "type": "string",
+          "description": "Bytes to write to stdin (may be empty to poll)."
+        },
+        "max_output_tokens": {
+          "type": "number",
+          "description": "Maximum number of tokens to return. Excess output will be truncated."
+        },
+        "session_id": {
+          "type": "number",
+          "description": "Identifier of the running unified exec session."
+        },
+        "yield_time_ms": {
+          "type": "number",
+          "description": "How long to wait (in milliseconds) for output before yielding."
+        }
+      },
+      "required": [
+        "session_id"
+      ],
+      "additionalProperties": false
+    }
+  },
+  {
+    "type": "function",
+    "name": "update_plan",
+    "description": "Updates the task plan.\nProvide an optional explanation and a list of plan items, each with a step and status.\nAt most one step can be in_progress at a time.\n",
+    "strict": false,
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "explanation": {
+          "type": "string"
+        },
+        "plan": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "status": {
+                "type": "string",
+                "description": "One of: pending, in_progress, completed"
+              },
+              "step": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "step",
+              "status"
+            ],
+            "additionalProperties": false
+          },
+          "description": "The list of steps"
+        }
+      },
+      "required": [
+        "plan"
+      ],
+      "additionalProperties": false
+    }
+  },
+  {
+    "type": "custom",
+    "name": "apply_patch",
+    "description": "Use the `apply_patch` tool to edit files. This is a FREEFORM tool, so do not wrap the patch in JSON.",
+    "format": {
+      "type": "grammar",
+      "syntax": "lark",
+      "definition": "start: begin_patch hunk+ end_patch\nbegin_patch: \"*** Begin Patch\" LF\nend_patch: \"*** End Patch\" LF?\n\nhunk: add_hunk | delete_hunk | update_hunk\nadd_hunk: \"*** Add File: \" filename LF add_line+\ndelete_hunk: \"*** Delete File: \" filename LF\nupdate_hunk: \"*** Update File: \" filename LF change_move? change?\n\nfilename: /(.+)/\nadd_line: \"+\" /(.*)/ LF -> line\n\nchange_move: \"*** Move to: \" filename LF\nchange: (change_context | change_line)+ eof_line?\nchange_context: (\"@@\" | \"@@ \" /(.+)/) LF\nchange_line: (\"+\" | \"-\" | \" \") /(.*)/ LF\neof_line: \"*** End of File\" LF\n\n%import common.LF\n"
+    }
+  },
+  {
+    "type": "web_search",
+    "external_web_access": true
+  },
+  {
+    "type": "function",
+    "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).",
+    "strict": false,
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "path": {
+          "type": "string",
+          "description": "Local filesystem path to an image file"
+        }
+      },
+      "required": [
+        "path"
+      ],
+      "additionalProperties": false
+    }
+  }
+]

pycodex/protocol.py

@@ -0,0 +1,347 @@
+"""pycodex 的最小协议层定义。
+
+核心抽象：
+- AgentLoop：内层 turn 主循环，负责维护历史、调用模型、执行工具，并在
+  `ToolCall -> ToolResult -> 下一轮模型调用` 之间反复闭环，直到得到稳定回复。
+- AgentRuntime：外层提交队列，负责按顺序接收 `Submission`，驱动
+  `UserTurnOp` / `ShutdownOp` 这类运行时操作。
+- ContextManager：负责把基础指令、AGENTS.md、环境信息等上下文拼成每轮模型看到的
+  `Prompt` 前缀，但这些注入内容不会写回长期会话历史。
+- ModelClient：模型后端抽象，接收 `Prompt`，返回 `ModelResponse`。
+- ModelStreamEvent：模型在一次 `Prompt` 处理中途产生的流式事件，例如文本增量。
+- ToolRegistry：工具执行抽象，接收 `ToolCall`，产出 `ToolResult`。
+
+本文件只定义这些抽象之间传递的数据结构，不包含具体执行逻辑。
+"""
+
+from __future__ import annotations
+
+from copy import deepcopy
+import json
+from dataclasses import dataclass, field
+from typing import Any, Literal, TypeAlias
+
+JSONValue: TypeAlias = Any
+JSONDict: TypeAlias = dict[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class ToolSpec:
+    """何时：AgentLoop 准备发起一轮模型请求时，随 `Prompt.tools` 一起发送。
+    发送方：AgentLoop。
+    接收方：ModelClient。
+    """
+
+    name: str
+    description: str
+    input_schema: JSONDict | None = None
+    tool_type: Literal["function", "custom", "web_search"] = "function"
+    format: JSONDict | None = None
+    options: JSONDict | None = None
+    output_schema: JSONDict | None = None
+    supports_parallel: bool = True
+    raw_payload: JSONDict | None = None
+
+    def serialize(self) -> JSONDict:
+        if self.raw_payload is not None:
+            return deepcopy(self.raw_payload)
+        if self.tool_type == "web_search":
+            payload = {"type": "web_search"}
+            if self.options is not None:
+                payload.update(self.options)
+            return payload
+
+        if self.tool_type == "custom":
+            if self.format is None:
+                raise ValueError("custom tools require `format`")
+            return {
+                "type": "custom",
+                "name": self.name,
+                "description": self.description,
+                "format": self.format,
+            }
+
+        if self.input_schema is None:
+            raise ValueError("function tools require `input_schema`")
+
+        payload = {
+            "type": "function",
+            "name": self.name,
+            "description": self.description,
+            "parameters": self.input_schema,
+            "strict": False,
+        }
+        if self.output_schema is not None:
+            payload["output_schema"] = self.output_schema
+        return payload
+
+
+@dataclass(frozen=True, slots=True)
+class UserMessage:
+    """何时：外部发起一个新的用户 turn 时创建，并写入会话历史。
+    发送方：外部调用方创建，AgentLoop 转发。
+    接收方：AgentLoop 先接收，随后 ModelClient 在 `Prompt.input` 中看到它。
+    """
+
+    text: str
+    role: Literal["user"] = "user"
+
+    def serialize(self) -> JSONDict:
+        return {
+            "type": "message",
+            "role": self.role,
+            "content": [{"type": "input_text", "text": self.text}],
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class AssistantMessage:
+    """何时：模型要直接输出自然语言内容时产生，可作为中间文本或最终回复。
+    发送方：ModelClient。
+    接收方：AgentLoop。
+    """
+
+    text: str
+    role: Literal["assistant"] = "assistant"
+
+    def serialize(self) -> JSONDict:
+        return {
+            "type": "message",
+            "role": self.role,
+            "content": [{"type": "output_text", "text": self.text}],
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class ContextMessage:
+    """何时：ContextManager 为单轮模型请求注入额外上下文时构造。
+    发送方：ContextManager。
+    接收方：ModelClient。
+    """
+
+    text: str | None = None
+    role: Literal["user", "developer"] = "user"
+    content_items: tuple[JSONDict, ...] | None = None
+
+    def serialize(self) -> JSONDict:
+        if self.content_items is not None:
+            content = list(self.content_items)
+        else:
+            if self.text is None:
+                raise ValueError("ContextMessage requires `text` or `content_items`")
+            content = [{"type": "input_text", "text": self.text}]
+        return {
+            "type": "message",
+            "role": self.role,
+            "content": content,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class ToolCall:
+    """何时：模型决定调用工具而不是只输出文本时产生。
+    发送方：ModelClient。
+    接收方：AgentLoop，随后由它转给 ToolRegistry 执行。
+    """
+
+    call_id: str
+    name: str
+    arguments: JSONValue
+    tool_type: Literal["function", "custom"] = "function"
+    kind: Literal["tool_call"] = "tool_call"
+
+    def serialize(self) -> JSONDict:
+        if self.tool_type == "custom":
+            return {
+                "type": "custom_tool_call",
+                "name": self.name,
+                "input": str(self.arguments),
+                "call_id": self.call_id,
+            }
+        return {
+            "type": "function_call",
+            "name": self.name,
+            "arguments": json.dumps(
+                self.arguments,
+                ensure_ascii=False,
+                separators=(",", ":"),
+            ),
+            "call_id": self.call_id,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class ReasoningItem:
+    """何时：模型在一次 Responses 采样里产出 reasoning item 时产生。
+    发送方：ModelClient。
+    接收方：AgentLoop；它会把该 item 保留进 history，并在后续请求里原样回传给
+    ModelClient。
+    """
+
+    payload: JSONDict
+    kind: Literal["reasoning"] = "reasoning"
+
+    def serialize(self) -> JSONDict:
+        return deepcopy(self.payload)
+
+
+@dataclass(frozen=True, slots=True)
+class ToolResult:
+    """何时：某个 `ToolCall` 执行完成后产生，用于喂回下一轮模型调用。
+    发送方：ToolRegistry 产出，AgentLoop 追加并转发。
+    接收方：AgentLoop 先接收，随后 ModelClient 在下一轮 `Prompt.input` 中看到它。
+    """
+
+    call_id: str
+    name: str
+    output: JSONValue
+    content_items: tuple[JSONDict, ...] | None = None
+    success: bool | None = None
+    is_error: bool = False
+    tool_type: Literal["function", "custom"] = "function"
+    kind: Literal["tool_result"] = "tool_result"
+
+    def output_text(self) -> str:
+        if self.content_items is not None:
+            text_parts = [
+                str(item.get("text", ""))
+                for item in self.content_items
+                if item.get("type") == "input_text"
+            ]
+            if text_parts:
+                return "\n".join(text_parts)
+            if isinstance(self.output, str):
+                return self.output
+            return json.dumps(self.output, ensure_ascii=False)
+        if isinstance(self.output, str):
+            return self.output
+        return json.dumps(self.output, ensure_ascii=False)
+
+    def serialize(self) -> JSONDict:
+        payload_output: JSONValue
+        if self.content_items is not None:
+            payload_output = list(self.content_items)
+        elif isinstance(self.output, str):
+            payload_output = self.output
+        else:
+            payload_output = json.dumps(
+                self.output,
+                ensure_ascii=False,
+                separators=(",", ":"),
+            )
+
+        item_type = (
+            "custom_tool_call_output"
+            if self.tool_type == "custom"
+            else "function_call_output"
+        )
+        payload = {
+            "type": item_type,
+            "call_id": self.call_id,
+            "output": payload_output,
+        }
+        if self.success is not None:
+            payload["success"] = self.success
+        if self.tool_type == "custom":
+            payload["name"] = self.name
+        return payload
+
+
+ConversationItem: TypeAlias = (
+    UserMessage | AssistantMessage | ContextMessage | ToolCall | ReasoningItem | ToolResult
+)
+ModelOutputItem: TypeAlias = AssistantMessage | ToolCall | ReasoningItem
+Operation: TypeAlias = "UserTurnOp | ShutdownOp"
+
+
+@dataclass(frozen=True, slots=True)
+class Prompt:
+    """何时：AgentLoop 每发起一轮模型采样前构造。
+    发送方：AgentLoop。
+    接收方：ModelClient。
+    """
+
+    input: list[ConversationItem]
+    tools: list[ToolSpec]
+    parallel_tool_calls: bool = True
+    base_instructions: str | None = None
+    turn_id: str | None = None
+    turn_metadata: JSONDict | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ModelResponse:
+    """何时：ModelClient 完成一轮 `Prompt` 处理后返回。
+    发送方：ModelClient。
+    接收方：AgentLoop。
+    """
+
+    items: list[ModelOutputItem]
+
+
+@dataclass(frozen=True, slots=True)
+class ModelStreamEvent:
+    """何时：ModelClient 处理 `Prompt` 的过程中有流式中间结果时产生。
+    发送方：ModelClient。
+    接收方：AgentLoop。
+    """
+
+    kind: str
+    payload: JSONDict = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class TurnResult:
+    """何时：一个 turn 已经收敛，AgentLoop 决定结束本轮时返回。
+    发送方：AgentLoop。
+    接收方：外部调用方。
+    """
+
+    turn_id: str
+    output_text: str | None
+    iterations: int
+    response_items: tuple[ModelOutputItem, ...]
+    history: tuple[ConversationItem, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class AgentEvent:
+    """何时：主循环运行过程中发生阶段性事件时发出，例如模型调用、工具开始/结束。
+    发送方：AgentLoop。
+    接收方：可选的事件观察者 / 回调。
+    """
+
+    kind: str
+    turn_id: str
+    payload: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class UserTurnOp:
+    """何时：运行时要提交一个新的用户请求时创建。
+    发送方：外部运行时调用方。
+    接收方：AgentRuntime。
+    """
+
+    texts: list[str]
+
+
+@dataclass(frozen=True, slots=True)
+class ShutdownOp:
+    """何时：运行时要停止外层提交循环时创建。
+    发送方：外部运行时调用方。
+    接收方：AgentRuntime。
+    """
+
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class Submission:
+    """何时：任意运行时操作要进入 AgentRuntime 队列时创建。
+    发送方：外部运行时调用方。
+    接收方：AgentRuntime 的提交队列 / 外层循环。
+    """
+
+    id: str
+    op: Operation