plain-agent 0.1.0__py3-none-any.whl

plain_agent-0.1.0.dist-info/METADATA

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: plain-agent
+Version: 0.1.0
+Summary: A small agent that calls OpenAI-compatible APIs.
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai==2.43.0
+Requires-Dist: python-dotenv>=1.2.2
+Dynamic: license-file
+
+# Plain Agent
+
+A small agent that calls OpenAI compatible LLM APIs.
+
+This project starts with a streaming agent loop:
+
+```text
+Interactive terminal
+  -> reads your prompt
+  -> streams assistant text as it arrives
+  -> detects tool calls from the model
+  -> runs workspace tools when requested
+  -> sends tool results back to the model
+  -> repeats until the assistant gives a final answer
+```
+
+## Install
+
+This project uses `uv` to track the Python environment.
+If `uv` is not installed, follow the [official installation guide](https://docs.astral.sh/uv/getting-started/installation/).
+
+```bash
+uv sync
+```
+
+## Configuration
+
+Create a local `.env` file or export environment variables in your shell. See `.env.example` for more examples.
+
+For DeepSeek:
+
+```bash
+export DEEPSEEK_API_KEY="your-api-key"
+export LLM_PROVIDER="deepseek"
+export LLM_MODEL="deepseek-v4-flash"
+```
+
+For OpenAI:
+
+```bash
+export OPENAI_API_KEY="your-api-key"
+export LLM_PROVIDER="openai"
+export LLM_MODEL="gpt-5.4-mini"
+```
+
+You can still set `LLM_BASE_URL` when you want to override the provider default, such as pointing at a local OpenAI compatible server like Ollama.
+
+## Run
+
+```bash
+uv run plain-agent
+```

plain_agent-0.1.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+plain_agent-0.1.0.dist-info/licenses/LICENSE,sha256=6zgW5PChFyhFoChqZ6HZlkuGJExiIlcmbwzm-cXaBY8,1064
+simple_agent/agent_loop.py,sha256=wD18vnHGrDxL7l0ydIpjI2K-Rb4TP14wyohd2XTZu9U,4201
+simple_agent/cli.py,sha256=1OVKa4SXwMv2DCLy4Wj2bmIj9E28JhOepXrp-qg08AU,1324
+simple_agent/conversation_history.py,sha256=CoaXkWk8ckF8BexNjsC-HaYW3bBY9m4Tp3BEplZ6osM,1805
+simple_agent/llm_client.py,sha256=cIs6Q502ezKXgGcpgE9ymszRW6SIONTOLLDa0xcmLsQ,1162
+simple_agent/message_types.py,sha256=G-jqN_UKhaMkDpcdYykbvFGf-dclLf84Qjs4u9kW5-E,764
+simple_agent/prompt.py,sha256=NePuYJtdrjXUT5n3KgfaMUMf8NpX0FxEkqFaViNhE4o,207
+simple_agent/streaming.py,sha256=w_PMCdoQyCi2dL2uQBMArdo94d9PQ_dvWR9BLkafrdc,2783
+simple_agent/terminal_loop.py,sha256=3fe6ux5fhp54rj9SMjWBdz584bJmMDu7JwcH-Vmj-Fo,1583
+simple_agent/tools/base_tool.py,sha256=Rz3sqVTQ8ajks-m4qYG-fCpgO8_yovmhyW_neJXbx_4,697
+simple_agent/tools/command_policy.py,sha256=QhWyRZc7YclbbJN8_QAUL5KaJN5wuzmcoTvrBp9pLMk,543
+simple_agent/tools/command_runtime.py,sha256=Wk34ZNfSF5Vb7RxIT35vz_Q9lP5SaysB-BOPAsLDebY,5432
+simple_agent/tools/edit_file.py,sha256=Mw4Ov9xOEHXOPa7Hh0YRXKiEE8gfKNR266IMCeWHEcQ,2672
+simple_agent/tools/list_files.py,sha256=83ksH9RvtpvgTJMVGlC-NNO5gt9X2QC0N12TheKDzk0,1563
+simple_agent/tools/read_file.py,sha256=5X6JGlCfBk8h82seNQoR_CilRHxyeIr4EN8UoWZ1xBU,1858
+simple_agent/tools/run_command.py,sha256=3RDkNe2298DKqdV0gsbNWOvQbf2FBYl94TNCziXvbqk,1855
+simple_agent/tools/search_text.py,sha256=9woE27IA023dAx3B6P0Wl87iJRhvJhhi9D6nQRGC9aw,2331
+simple_agent/tools/tools.py,sha256=jTGK31zh2Ty9Vp_ajgDCEt-GY42vUZjv7qeDu3gpZ1k,1598
+simple_agent/tools/utils.py,sha256=q1yGn7RPMBh8MUoT0_aAoHew0GYZFw9QeM2nxrEujEE,230
+simple_agent/tools/write_file.py,sha256=rQ1bgXlK5qzMTz_TNfFciGiyZnbErzIPrqfLd8QDBog,1815
+simple_agent/tools/permissions/file_permission.py,sha256=UesMDoXBP-iciFYCBG2F0a6ytL_eAD2M9HSXjS12l-w,3755
+plain_agent-0.1.0.dist-info/METADATA,sha256=MXgRpMCHlFXnJ5j3UsEjYrW4sSmcW6XXeRu6cLhv1Eo,1498
+plain_agent-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+plain_agent-0.1.0.dist-info/entry_points.txt,sha256=dglvgV5z6UFGB4xSldi-f2yp0SNAjGuK8ikpSkT4tcI,54
+plain_agent-0.1.0.dist-info/top_level.txt,sha256=GLfnn8uQL8CtYaH1Jj3ROG50x8ecOgIkirf_HVd0VFw,13
+plain_agent-0.1.0.dist-info/RECORD,,

plain_agent-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

plain_agent-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+plain-agent = simple_agent.cli:main

plain_agent-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ribo Mo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

plain_agent-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+simple_agent

simple_agent/agent_loop.py

@@ -0,0 +1,112 @@
+"""Simple tool loop for the educational agent."""
+
+from collections.abc import Iterable
+import json
+from typing import Any, Callable, Generator
+
+from simple_agent.conversation_history import ConversationHistory
+from simple_agent.message_types import ToolCallDict
+from simple_agent.prompt import INITIAL_PROMPT
+from simple_agent.streaming import (
+    ChatCompletionStreamAccumulator,
+    TextDelta,
+    ToolResult,
+)
+from simple_agent.tools.tools import Tools
+from simple_agent.tools.utils import error
+
+
+class SimpleAgent:
+    """A tiny Chat Completions agent loop with workspace tools."""
+
+    def __init__(
+        self,
+        llm_client: Any,
+        model: str,
+        workspace: str = ".",
+        max_turns: int = 5,
+        command_approver: Callable[[str], bool] | None = None,
+    ) -> None:
+        self.llm_client = llm_client
+        self.model = model
+        self.max_turns = max_turns
+        self.command_approver = command_approver
+        self.tools = Tools(workspace)
+        self.conversation_history = ConversationHistory(INITIAL_PROMPT)
+
+    def respond_stream(self, user_input: str) -> Generator[TextDelta | ToolResult, None, None]:
+        self.conversation_history.append_user(user_input)
+
+        for _ in range(self.max_turns):
+            accumulator = ChatCompletionStreamAccumulator()
+            for chunk in self._create_llm_stream():
+                for event in accumulator.add_chunk(chunk):
+                    yield event
+
+            message_dict = accumulator.assistant_message()
+            self.conversation_history.append(message_dict)
+
+            tool_calls = message_dict.get("tool_calls")
+            if not tool_calls:
+                return
+
+            for tool_call_dict in tool_calls:
+                result = self._handle_tool_call(tool_call_dict)
+                self.conversation_history.append_tool(tool_call_dict["id"], result)
+                yield ToolResult(
+                    call_id=tool_call_dict["id"],
+                    name=tool_call_dict["function"]["name"],
+                    result=result,
+                    ok=self._tool_result_ok(result),
+                )
+
+        final_text = "I stopped because the tool loop reached the max turn limit."
+        self.conversation_history.append_assistant(final_text)
+        yield TextDelta(final_text)
+
+    def _create_llm_stream(self) -> Iterable[Any]:
+        return self.llm_client.chat.completions.create(
+            model=self.model,
+            messages=self.conversation_history.to_messages(),
+            tools=self.tools.definitions(),
+            tool_choice="auto",
+            stream=True,
+        )
+
+    def _handle_tool_call(self, tool_call: ToolCallDict) -> str:
+        name = tool_call["function"]["name"]
+        try:
+            arguments = self._parse_tool_arguments(tool_call["function"]["arguments"])
+        except ValueError as exc:
+            return error(str(exc))
+        user_approval = self._approve_run_command(arguments)
+        if name == "run_command" and not user_approval:
+            return error("run_command was not approved")
+        return self.tools.run(name, arguments)
+
+    def _approve_run_command(self, arguments: dict[str, object]) -> bool:
+        command = arguments.get("command")
+        if not isinstance(command, str) or not command.strip():
+            # Empty or invalid commands are blocked by the tool implementation.
+            return True
+        if self.command_approver is None:
+            return False
+        return self.command_approver(command)
+
+    def _tool_result_ok(self, result: str) -> bool:
+        try:
+            parsed = json.loads(result)
+        except json.JSONDecodeError:
+            return False
+        if not isinstance(parsed, dict):
+            return False
+        return parsed.get("ok") is True
+
+    def _parse_tool_arguments(self, raw_arguments: str) -> dict[str, object]:
+        try:
+            arguments = json.loads(raw_arguments or "{}")
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"invalid JSON arguments: {exc}")
+        if not isinstance(arguments, dict):
+            raise ValueError("tool arguments must be a JSON object")
+        return arguments

simple_agent/cli.py

@@ -0,0 +1,43 @@
+import os
+
+from dotenv import load_dotenv
+
+from simple_agent.agent_loop import SimpleAgent
+from simple_agent.llm_client import (
+    DEEPSEEK_BASE_URL,
+    OPENAI_BASE_URL,
+    OpenAICompatibleClient,
+)
+from simple_agent.terminal_loop import approve_run_command, run_interactive_terminal
+
+
+def main() -> None:
+    load_dotenv()
+
+    provider = os.environ.get("LLM_PROVIDER", "deepseek").lower()
+    timeout = float(os.environ.get("LLM_TIMEOUT", "60"))
+
+    if provider == "openai":
+        api_key = os.environ.get("OPENAI_API_KEY") or os.environ.get("LLM_API_KEY")
+        default_model = "gpt-5.4-mini"
+        default_base_url = OPENAI_BASE_URL
+    elif provider == "deepseek":
+        api_key = os.environ.get("DEEPSEEK_API_KEY") or os.environ.get("LLM_API_KEY")
+        default_model = "deepseek-v4-flash"
+        default_base_url = DEEPSEEK_BASE_URL
+    else:
+        raise ValueError("LLM_PROVIDER must be 'openai' or 'deepseek'")
+
+    llm_client = OpenAICompatibleClient(
+        api_key=api_key,
+        base_url=os.environ.get("LLM_BASE_URL", default_base_url),
+        timeout=timeout,
+    )
+    model = os.environ.get("LLM_MODEL", default_model)
+    agent = SimpleAgent(
+        llm_client=llm_client,
+        model=model,
+        command_approver=approve_run_command,
+    )
+
+    run_interactive_terminal(agent)

simple_agent/conversation_history.py

@@ -0,0 +1,59 @@
+"""Typed chat messages and conversation history storage."""
+
+from collections.abc import Iterator
+from copy import deepcopy
+from typing import overload
+
+from simple_agent.message_types import AssistantMessageDict, ChatMessage, ToolMessage, UserMessage
+
+
+class ConversationHistory:
+    """Stores chat messages while exposing list-like read access."""
+    _messages: list[ChatMessage]
+
+    def __init__(self, system_prompt: str) -> None:
+        self._messages = [
+            {"role": "system", "content": system_prompt},
+        ]
+
+    def append(self, message: ChatMessage) -> None:
+        self._messages.append(message)
+
+    def append_user(self, content: str) -> None:
+        message: UserMessage = {"role": "user", "content": content}
+        self.append(message)
+
+    def append_assistant(self, content: str) -> None:
+        message: AssistantMessageDict = {"role": "assistant", "content": content}
+        self.append(message)
+
+    def append_tool(self, tool_call_id: str, content: str) -> None:
+        message: ToolMessage = {
+            "role": "tool",
+            "tool_call_id": tool_call_id,
+            "content": content,
+        }
+        self.append(message)
+
+    def replace(self, messages: list[ChatMessage]) -> None:
+        self._messages = messages
+
+    def to_messages(self) -> list[ChatMessage]:
+        return deepcopy(self._messages)
+
+    def __iter__(self) -> Iterator[ChatMessage]:
+        return iter(self._messages)
+
+    def __len__(self) -> int:
+        return len(self._messages)
+
+    @overload
+    def __getitem__(self, index: int) -> ChatMessage:
+        ...
+
+    @overload
+    def __getitem__(self, index: slice) -> list[ChatMessage]:
+        ...
+
+    def __getitem__(self, index: int | slice) -> ChatMessage | list[ChatMessage]:
+        return self._messages[index]

simple_agent/llm_client.py

@@ -0,0 +1,49 @@
+"""OpenAI-compatible LLM clients."""
+
+from openai import OpenAI
+
+
+OPENAI_BASE_URL = "https://api.openai.com/v1"
+DEEPSEEK_BASE_URL = "https://api.deepseek.com"
+
+
+class LLMClientError(ValueError):
+    """Raised when LLM configuration is incomplete."""
+
+
+class OpenAICompatibleClient:
+    """Small wrapper around the official OpenAI SDK client."""
+
+    base_url = OPENAI_BASE_URL
+
+    def __init__(
+        self,
+        api_key: str | None,
+        base_url: str | None = None,
+        timeout: float = 60.0,
+    ) -> None:
+        if not api_key:
+            raise LLMClientError("api_key is required to create an LLM client")
+
+        self.api_key = api_key
+        self.base_url = base_url or self.base_url
+        self.timeout = timeout
+        self.client = OpenAI(
+            base_url=self.base_url,
+            api_key=self.api_key,
+            timeout=self.timeout,
+        )
+
+    @property
+    def chat(self):
+        return self.client.chat
+
+
+class OpenAIClient(OpenAICompatibleClient):
+    """OpenAI client."""
+
+
+class DeepSeekClient(OpenAICompatibleClient):
+    """DeepSeek client using its OpenAI-compatible API."""
+
+    base_url = DEEPSEEK_BASE_URL

simple_agent/message_types.py

@@ -0,0 +1,39 @@
+"""TypedDict shapes for OpenAI-compatible chat messages."""
+
+from typing import Literal, NotRequired, TypedDict
+
+
+class SystemMessage(TypedDict):
+    role: Literal["system"]
+    content: str
+
+
+class UserMessage(TypedDict):
+    role: Literal["user"]
+    content: str
+
+
+class ToolMessage(TypedDict):
+    role: Literal["tool"]
+    tool_call_id: str
+    content: str
+
+
+class FunctionCallDict(TypedDict):
+    name: str
+    arguments: str
+
+
+class ToolCallDict(TypedDict):
+    id: str
+    type: Literal["function"]
+    function: FunctionCallDict
+
+
+class AssistantMessageDict(TypedDict):
+    role: Literal["assistant"]
+    content: str | None
+    tool_calls: NotRequired[list[ToolCallDict]]
+
+
+ChatMessage = SystemMessage | UserMessage | AssistantMessageDict | ToolMessage

simple_agent/prompt.py

@@ -0,0 +1,5 @@
+INITIAL_PROMPT = """
+You are a helpful educational coding assistant.
+You may inspect and edit the workspace with tools before answering.
+Use tools when file context would make your answer more accurate.
+"""

simple_agent/streaming.py

@@ -0,0 +1,96 @@
+"""Helpers for Chat Completions streaming responses."""
+
+from dataclasses import dataclass
+
+from openai.types.chat.chat_completion_chunk import (
+    ChatCompletionChunk,
+    ChoiceDeltaToolCall,
+)
+
+from simple_agent.message_types import AssistantMessageDict, ToolCallDict
+
+
+@dataclass
+class TextDelta:
+    """A streamed assistant text chunk."""
+
+    content: str
+
+
+@dataclass
+class ToolResult:
+    """A completed tool call event."""
+
+    call_id: str
+    name: str
+    result: str
+    ok: bool
+
+
+def merge_tool_call_delta_into(tool_call: ToolCallDict, tool_call_delta: ChoiceDeltaToolCall) -> None:
+    # Each streamed delta may contain only one fragment of the final tool call.
+    call_id = tool_call_delta.id
+    if call_id:
+        tool_call["id"] = call_id
+
+    call_type = tool_call_delta.type
+    if call_type:
+        tool_call["type"] = call_type
+
+    function_delta = tool_call_delta.function
+    if function_delta is None:
+        return
+
+    name = function_delta.name
+    if name:
+        tool_call["function"]["name"] += name
+
+    arguments = function_delta.arguments
+    if arguments:
+        tool_call["function"]["arguments"] += arguments
+
+
+class ChatCompletionStreamAccumulator:
+    """Build the final assistant message from streamed Chat Completions chunks."""
+
+    def __init__(self) -> None:
+        self.full_text = ""
+        self.tool_calls_by_index: dict[int, ToolCallDict] = {}
+
+    def add_chunk(self, chunk: ChatCompletionChunk) -> list[TextDelta]:
+        # OpenAI can send usage/bookkeeping chunks with choices=[].
+        choices = chunk.choices
+        if not choices:
+            return []
+
+        delta = choices[0].delta
+        events = []
+
+        content = delta.content
+        if content:
+            self.full_text += content
+            events.append(TextDelta(content))
+
+        for tool_call_delta in delta.tool_calls or []:
+            index = tool_call_delta.index
+            if index not in self.tool_calls_by_index:
+                self.tool_calls_by_index[index] = {
+                    "id": "",
+                    "type": "function",
+                    "function": {"name": "", "arguments": ""},
+                }
+
+            tool_call = self.tool_calls_by_index[index]
+            # Later deltas usually add more argument text for this index.
+            merge_tool_call_delta_into(tool_call, tool_call_delta)
+
+        return events
+
+    def assistant_message(self) -> AssistantMessageDict:
+        message_dict: AssistantMessageDict = {"role": "assistant", "content": self.full_text or None}
+        if self.tool_calls_by_index:
+            message_dict["tool_calls"] = [
+                self.tool_calls_by_index[index]
+                for index in sorted(self.tool_calls_by_index)
+            ]
+        return message_dict

simple_agent/terminal_loop.py

@@ -0,0 +1,49 @@
+"""Interactive terminal loop for the simple agent."""
+
+from collections.abc import Iterable
+from typing import Protocol
+
+from simple_agent.streaming import TextDelta, ToolResult
+
+
+class StreamingAgent(Protocol):
+    """Agent interface used by the terminal loop."""
+
+    def respond_stream(self, user_input: str) -> Iterable[TextDelta | ToolResult]:
+        """Return streamed text and tool-result events for one user prompt."""
+
+
+def approve_run_command(command: str) -> bool:
+    """Ask the user whether a requested shell command may run."""
+    while True:
+        answer = input(f"\nApprove command `{command}`? [y/N] ").strip().lower()
+        if answer in {"y", "yes"}:
+            return True
+        if answer in {"", "n", "no"}:
+            return False
+        print("Please answer y or n.")
+
+
+def run_interactive_terminal(agent: StreamingAgent) -> None:
+    """Read prompts, stream responses, show tool results, and repeat."""
+    print("Simple agent client. Type 'exit' to quit.")
+
+    while True:
+        try:
+            user_input = input("> ").strip()
+        except EOFError:
+            print()
+            break
+
+        if user_input.lower() in {"exit", "quit"}:
+            break
+        if not user_input:
+            continue
+
+        for event in agent.respond_stream(user_input):
+            if isinstance(event, TextDelta):
+                print(event.content, end="", flush=True)
+            elif isinstance(event, ToolResult):
+                status = "ok" if event.ok else "error"
+                print(f"\n[tool {event.name}: {status}]")
+        print()

simple_agent/tools/base_tool.py

@@ -0,0 +1,29 @@
+"""Base class for callable tools."""
+
+from copy import deepcopy
+from pathlib import Path
+
+
+class BaseTool:
+    """Base class for a tool the model can call."""
+
+    name = ""
+    description = ""
+    parameters: dict[str, object] = {
+        "type": "object",
+        "properties": {},
+    }
+
+    @property
+    def definition(self) -> dict[str, object]:
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": deepcopy(self.parameters),
+            },
+        }
+
+    def run(self, root: Path, arguments: dict[str, object]) -> str:
+        raise NotImplementedError

simple_agent/tools/command_policy.py

@@ -0,0 +1,20 @@
+"""Allowlist policy for safe workspace commands."""
+
+RUN_COMMAND_ALLOWED_COMMANDS = ("pwd", "ls", "find", "rg", "grep", "cat", "head", "tail", "wc")
+RUN_COMMAND_ALLOWED_GIT_SUBCOMMANDS = (
+    "status",
+    "diff",
+    "log",
+    "show",
+    "branch",
+    "rev-parse",
+    "ls-files",
+    "grep",
+)
+
+RUN_COMMAND_ALLOWED_COMMANDS_TEXT = (
+    "Allowed commands: "
+    f"{', '.join(RUN_COMMAND_ALLOWED_COMMANDS)}. "
+    "Allowed git subcommands: "
+    f"{', '.join(f'git {subcommand}' for subcommand in RUN_COMMAND_ALLOWED_GIT_SUBCOMMANDS)}."
+)

simple_agent/tools/command_runtime.py

@@ -0,0 +1,155 @@
+"""Runtime for safe workspace inspection commands."""
+
+from dataclasses import asdict, dataclass
+from pathlib import Path
+import shlex
+import subprocess
+
+from simple_agent.tools.command_policy import (
+    RUN_COMMAND_ALLOWED_COMMANDS,
+    RUN_COMMAND_ALLOWED_GIT_SUBCOMMANDS,
+)
+from simple_agent.tools.permissions.file_permission import WorkspacePermission
+
+ALLOWED_COMMANDS = set(RUN_COMMAND_ALLOWED_COMMANDS)
+ALLOWED_GIT_SUBCOMMANDS = set(RUN_COMMAND_ALLOWED_GIT_SUBCOMMANDS)
+SHELL_OPERATORS = ("|", ">", "<", "&&", "||", ";", "$(", "`", "&")
+MUTATING_FLAGS = {
+    "-delete",
+    "-exec",
+    "-execdir",
+    "-ok",
+    "-okdir",
+}
+
+
+class CommandRuntimeError(ValueError):
+    """Raised when a command cannot be safely run."""
+
+
+@dataclass
+class CommandResult:
+    ok: bool
+    command: str
+    exit_code: int | None
+    stdout: str
+    stderr: str
+    timed_out: bool
+    truncated: bool
+
+    def to_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+class CommandRuntime:
+    """Runs allowlisted commands from a workspace without shell syntax."""
+
+    def __init__(self, timeout_seconds: float = 30, max_output_chars: int = 12_000) -> None:
+        self.timeout_seconds = timeout_seconds
+        self.max_output_chars = max_output_chars
+
+    def run(self, workspace: Path, command: str) -> CommandResult:
+        argv = self._parse_command(command)
+        self._require_command_access(workspace, argv)
+
+        try:
+            completed = subprocess.run(
+                argv,
+                cwd=workspace,
+                capture_output=True,
+                text=True,
+                timeout=self.timeout_seconds,
+                shell=False,
+                check=False,
+            )
+        except subprocess.TimeoutExpired as exc:
+            stdout = self._output_text(exc.stdout)
+            stderr = self._output_text(exc.stderr)
+            stdout, stderr, truncated = self._truncate_outputs(stdout, stderr)
+            return CommandResult(
+                ok=False,
+                command=command,
+                exit_code=None,
+                stdout=stdout,
+                stderr=stderr,
+                timed_out=True,
+                truncated=truncated,
+            )
+        except OSError as exc:
+            raise CommandRuntimeError(f"could not run command: {exc}") from exc
+
+        stdout, stderr, truncated = self._truncate_outputs(completed.stdout, completed.stderr)
+        return CommandResult(
+            ok=completed.returncode == 0,
+            command=command,
+            exit_code=completed.returncode,
+            stdout=stdout,
+            stderr=stderr,
+            timed_out=False,
+            truncated=truncated,
+        )
+
+    def _parse_command(self, command: str) -> list[str]:
+        self._require_no_shell_syntax(command)
+        try:
+            argv = shlex.split(command)
+        except ValueError as exc:
+            raise CommandRuntimeError(f"invalid command: {exc}") from exc
+        if not argv:
+            raise CommandRuntimeError("command is required")
+        return argv
+
+    def _require_no_shell_syntax(self, command: str) -> None:
+        for operator in SHELL_OPERATORS:
+            if operator in command:
+                raise CommandRuntimeError(f"shell syntax is not allowed: {operator}")
+
+    def _require_command_access(self, workspace: Path, argv: list[str]) -> None:
+        self._check_supported_command(argv)
+        self._check_command_paths(workspace, argv)
+
+    def _check_supported_command(self, argv: list[str]) -> None:
+        executable = argv[0]
+        if executable in ALLOWED_COMMANDS:
+            return
+
+        if executable == "git":
+            if len(argv) < 2:
+                raise CommandRuntimeError("git subcommand is required")
+            subcommand = argv[1]
+            if subcommand in ALLOWED_GIT_SUBCOMMANDS:
+                return
+            raise CommandRuntimeError(f"git subcommand is not allowed: {subcommand}")
+
+        raise CommandRuntimeError(f"command is not allowed: {executable}")
+
+    def _check_command_paths(self, workspace: Path, argv: list[str]) -> None:
+        permissions = WorkspacePermission(workspace)
+        for argument in argv[1:]:
+            if argument in MUTATING_FLAGS:
+                raise CommandRuntimeError(f"command flag is not allowed: {argument}")
+            if argument.startswith("-"):
+                continue
+
+            argument_path = Path(argument)
+            if argument_path.is_absolute() or ".." in argument_path.parts:
+                raise CommandRuntimeError(f"path argument is outside workspace: {argument}")
+
+            candidate = permissions.workspace / argument_path
+            if candidate.exists() and not permissions.contains_path(candidate.resolve()):
+                raise CommandRuntimeError(f"path argument is outside workspace: {argument}")
+
+    def _truncate_outputs(self, stdout: str, stderr: str) -> tuple[str, str, bool]:
+        if len(stdout) + len(stderr) <= self.max_output_chars:
+            return stdout, stderr, False
+
+        stdout = stdout[:self.max_output_chars]
+        stderr = stderr[:self.max_output_chars - len(stdout)]
+        return stdout, stderr, True
+
+    def _output_text(self, output: str | bytes | bytearray | memoryview | None) -> str:
+        if output is None:
+            return ""
+        if isinstance(output, str):
+            return output
+        return bytes(output).decode(errors="replace")

simple_agent/tools/edit_file.py

@@ -0,0 +1,75 @@
+"""Tool for editing workspace files with exact string replacement."""
+
+from pathlib import Path
+
+from simple_agent.tools.base_tool import BaseTool
+from simple_agent.tools.permissions.file_permission import FilePermissionError, WorkspacePermission
+from simple_agent.tools.utils import error, ok
+
+
+class EditFileTool(BaseTool):
+    """Replace an exact string inside an existing workspace file."""
+
+    name = "edit_file"
+    description = "Replace an exact string inside an existing workspace file."
+    parameters = {
+        "type": "object",
+        "properties": {
+            "path": {
+                "type": "string",
+                "description": "Workspace-relative file path.",
+            },
+            "old_string": {
+                "type": "string",
+                "description": "Exact text to replace.",
+            },
+            "new_string": {
+                "type": "string",
+                "description": "Replacement text.",
+            },
+        },
+        "required": ["path", "old_string", "new_string"],
+    }
+
+    def run(self, root: Path, arguments: dict[str, object]) -> str:
+        path = arguments.get("path")
+        old_string = arguments.get("old_string")
+        new_string = arguments.get("new_string")
+        if not isinstance(path, str):
+            return error("path is required")
+        if not isinstance(old_string, str) or not old_string:
+            return error("old_string is required")
+        if not isinstance(new_string, str):
+            return error("new_string is required")
+
+        try:
+            permissions = WorkspacePermission(root)
+            workspace_path = permissions.require_access(path)
+        except FilePermissionError as exc:
+            return error(str(exc))
+
+        if not workspace_path.is_file():
+            return error(f"path is not a file: {path}")
+
+        try:
+            text = workspace_path.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            return error(f"file is not valid UTF-8 text: {path}")
+        except OSError as exc:
+            return error(f"could not read file: {exc}")
+
+        count = text.count(old_string)
+        if count == 0:
+            return error(f"old_string not found in {path}")
+        if count > 1:
+            return error(f"old_string found {count} times in {path} — provide more context")
+
+        try:
+            workspace_path.write_text(text.replace(old_string, new_string), encoding="utf-8")
+        except OSError as exc:
+            return error(f"could not write file: {exc}")
+
+        return ok({
+            "path": permissions.relative_to_workspace(workspace_path),
+            "replaced": True,
+        })

simple_agent/tools/list_files.py

@@ -0,0 +1,45 @@
+"""Tool for listing workspace files."""
+
+from pathlib import Path
+
+from simple_agent.tools.base_tool import BaseTool
+from simple_agent.tools.permissions.file_permission import FilePermissionError, WorkspacePermission
+from simple_agent.tools.utils import error, ok
+
+
+class ListFilesTool(BaseTool):
+    """List files and directories inside the workspace."""
+
+    name = "list_files"
+    description = "List files and directories inside the workspace."
+    parameters = {
+        "type": "object",
+        "properties": {
+            "path": {
+                "type": "string",
+                "description": "Workspace-relative directory path.",
+                "default": ".",
+            }
+        },
+    }
+
+    def run(self, root: Path, arguments: dict[str, object]) -> str:
+        path = arguments.get("path", ".")
+        try:
+            permissions = WorkspacePermission(root)
+            workspace_path = permissions.require_access(path)
+        except FilePermissionError as exc:
+            return error(str(exc))
+
+        if not workspace_path.is_dir():
+            return error(f"path is not a directory: {path}")
+
+        entries = []
+        for child in sorted(workspace_path.iterdir()):
+            relative_path = child.relative_to(permissions.workspace)
+            if permissions.is_sensitive_path(relative_path):
+                continue
+            suffix = "/" if child.is_dir() else ""
+            entries.append(f"{relative_path}{suffix}")
+
+        return ok({"path": permissions.relative_to_workspace(workspace_path), "entries": entries})

simple_agent/tools/permissions/file_permission.py

@@ -0,0 +1,94 @@
+"""File permission helpers for workspace tools."""
+
+from pathlib import Path
+
+IGNORED_DIRS = {".agents", ".codex", ".git", ".sandbox", ".venv", "__pycache__"}
+SENSITIVE_FILE_NAMES = {".env", "id_dsa", "id_ecdsa", "id_ed25519", "id_rsa"}
+SENSITIVE_FILE_SUFFIXES = {".key", ".pem", ".p12", ".pfx"}
+
+
+class FilePermissionError(PermissionError):
+    """Raised when a tool cannot safely access a workspace path."""
+
+
+class WorkspacePermission:
+    """Checks whether paths are safe to access inside a workspace."""
+
+    def __init__(self, workspace: Path) -> None:
+        self.workspace = workspace.resolve()
+
+    def _resolve_to_absolute_path(self, path: Path) -> Path:
+        try:
+            if path.is_absolute():
+                return path.resolve()
+            return (self.workspace / path).resolve()
+        except (OSError, RuntimeError) as exc:
+            raise FilePermissionError(f"path could not be resolved: {path}") from exc
+
+    def is_sensitive_path(self, relative_path: Path) -> bool:
+        for part in relative_path.parts:
+            lower_part = part.lower()
+            if lower_part in IGNORED_DIRS or lower_part in SENSITIVE_FILE_NAMES:
+                return True
+        return relative_path.suffix.lower() in SENSITIVE_FILE_SUFFIXES
+
+    def require_access(self, path: str | Path, must_exist: bool = True) -> Path:
+        try:
+            user_path = Path(path)
+        except TypeError as exc:
+            raise FilePermissionError("path must be a string") from exc
+
+        absolute_path = self._resolve_to_absolute_path(user_path)
+        self._check_inside_workspace(absolute_path, path)
+        self._check_not_sensitive(absolute_path, path)
+        self._check_exists(absolute_path, path, must_exist=must_exist)
+        return absolute_path
+
+    def contains_path(self, path: Path) -> bool:
+        return path == self.workspace or self.workspace in path.parents
+
+    def get_files_under_path(self, path: Path) -> list[Path]:
+        if path.is_file():
+            return [path]
+        return self._walk_files(path)
+
+    def _walk_files(self, path: Path) -> list[Path]:
+        """Collect workspace files recursively, skipping symlinks and blocked paths."""
+        files: list[Path] = []
+        for child in sorted(path.iterdir()):
+            if child.is_symlink():
+                continue
+
+            relative_path = child.relative_to(self.workspace)
+            if child.name in IGNORED_DIRS or self.is_sensitive_path(relative_path):
+                continue
+
+            if child.is_dir():
+                files += self._walk_files(child)
+            elif child.is_file():
+                files.append(child)
+        return files
+
+    def _check_inside_workspace(self, absolute_path: Path, original_path: str | Path) -> None:
+        if not self.contains_path(absolute_path):
+            raise FilePermissionError(f"path is outside workspace: {original_path}")
+
+    def _check_not_sensitive(self, absolute_path: Path, original_path: str | Path) -> None:
+        if absolute_path != self.workspace and self.is_sensitive_path(absolute_path.relative_to(self.workspace)):
+            raise FilePermissionError(f"path is blocked: {original_path}")
+
+    def _check_exists(
+        self,
+        absolute_path: Path,
+        original_path: str | Path,
+        must_exist: bool = True,
+    ) -> None:
+        try:
+            path_exists = absolute_path.exists()
+        except OSError as exc:
+            raise FilePermissionError(f"path could not be checked: {original_path}") from exc
+        if must_exist and not path_exists:
+            raise FilePermissionError(f"path does not exist: {original_path}")
+
+    def relative_to_workspace(self, path: Path) -> str:
+        return str(path.relative_to(self.workspace))

simple_agent/tools/read_file.py

@@ -0,0 +1,60 @@
+"""Tool for reading workspace files."""
+
+from pathlib import Path
+
+from simple_agent.tools.base_tool import BaseTool
+from simple_agent.tools.permissions.file_permission import FilePermissionError, WorkspacePermission
+from simple_agent.tools.utils import error, ok
+
+
+class ReadFileTool(BaseTool):
+    """Read a UTF-8 text file inside the workspace."""
+
+    name = "read_file"
+    description = "Read a UTF-8 text file inside the workspace."
+    parameters = {
+        "type": "object",
+        "properties": {
+            "path": {
+                "type": "string",
+                "description": "Workspace-relative file path.",
+            }
+        },
+        "required": ["path"],
+    }
+
+    def __init__(self, max_chars: int = 12_000) -> None:
+        self.max_chars = max_chars
+
+    def run(self, root: Path, arguments: dict[str, object]) -> str:
+        path = arguments.get("path")
+        if not isinstance(path, str):
+            return error("path is required")
+
+        try:
+            permissions = WorkspacePermission(root)
+            workspace_path = permissions.require_access(path)
+        except FilePermissionError as exc:
+            return error(str(exc))
+
+        if not workspace_path.is_file():
+            return error(f"path is not a file: {path}")
+
+        try:
+            text = workspace_path.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            return error(f"file is not valid UTF-8 text: {path}")
+        except OSError as exc:
+            return error(f"could not read file: {exc}")
+
+        truncated = len(text) > self.max_chars
+        if truncated:
+            text = text[: self.max_chars]
+
+        return ok(
+            {
+                "path": permissions.relative_to_workspace(workspace_path),
+                "content": text,
+                "truncated": truncated,
+            }
+        )

simple_agent/tools/run_command.py

@@ -0,0 +1,54 @@
+"""Tool for running safe inspection commands in the workspace."""
+
+import json
+from pathlib import Path
+
+from simple_agent.tools.base_tool import BaseTool
+from simple_agent.tools.command_policy import RUN_COMMAND_ALLOWED_COMMANDS_TEXT
+from simple_agent.tools.command_runtime import CommandRuntime, CommandRuntimeError
+from simple_agent.tools.utils import error
+
+
+class RunCommandTool(BaseTool):
+    """Run a small allowlisted command without shell syntax."""
+
+    # This tool is for trusted workspace inspection, not a full sandbox. It
+    # runs outside the WorkspacePermission file filters, so keep the command
+    # allowlist and argument checks conservative.
+
+    name = "run_command"
+    description = (
+        "Run a safe inspection command inside the workspace. "
+        f"{RUN_COMMAND_ALLOWED_COMMANDS_TEXT}"
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "command": {
+                "type": "string",
+                "description": (
+                    "Simple command to run. Shell syntax is not supported. "
+                    f"{RUN_COMMAND_ALLOWED_COMMANDS_TEXT}"
+                ),
+            },
+        },
+        "required": ["command"],
+    }
+
+    def __init__(self, timeout_seconds: float = 30, max_output_chars: int = 12_000) -> None:
+        self.runtime = CommandRuntime(
+            timeout_seconds=timeout_seconds,
+            max_output_chars=max_output_chars,
+        )
+
+    def run(self, root: Path, arguments: dict[str, object]) -> str:
+        command = arguments.get("command")
+        if not isinstance(command, str) or not command.strip():
+            return error("command is required")
+
+        try:
+            result = self.runtime.run(root, command)
+        except CommandRuntimeError as exc:
+            return error(str(exc))
+
+        return json.dumps(result.to_dict())

simple_agent/tools/search_text.py

@@ -0,0 +1,66 @@
+"""Tool for searching workspace text."""
+
+from pathlib import Path
+
+from simple_agent.tools.base_tool import BaseTool
+from simple_agent.tools.permissions.file_permission import FilePermissionError, WorkspacePermission
+from simple_agent.tools.utils import error, ok
+
+
+class SearchTextTool(BaseTool):
+    """Search for exact text inside workspace files."""
+
+    name = "search_text"
+    description = "Search for exact text inside workspace files."
+    parameters = {
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "description": "Exact text to search for.",
+            },
+            "path": {
+                "type": "string",
+                "description": "Workspace-relative file or directory path.",
+                "default": ".",
+            },
+        },
+        "required": ["query"],
+    }
+
+    def __init__(self, max_results: int = 20) -> None:
+        self.max_results = max_results
+
+    def run(self, root: Path, arguments: dict[str, object]) -> str:
+        query = arguments.get("query")
+        if not isinstance(query, str) or not query:
+            return error("query is required")
+
+        path = str(arguments.get("path", "."))
+        try:
+            permissions = WorkspacePermission(root)
+            workspace_path = permissions.require_access(path)
+        except FilePermissionError as exc:
+            return error(str(exc))
+
+        files = permissions.get_files_under_path(workspace_path)
+        results = []
+        for file_path in files:
+            try:
+                lines = file_path.read_text(encoding="utf-8").splitlines()
+            except (UnicodeDecodeError, OSError):
+                continue
+
+            for line_number, line in enumerate(lines, start=1):
+                if query in line:
+                    results.append(
+                        {
+                            "path": permissions.relative_to_workspace(file_path),
+                            "line": line_number,
+                            "text": line.strip(),
+                        }
+                    )
+                    if len(results) >= self.max_results:
+                        return ok({"query": query, "results": results, "truncated": True})
+
+        return ok({"query": query, "results": results, "truncated": False})

simple_agent/tools/tools.py

@@ -0,0 +1,46 @@
+"""Dispatcher for workspace tools."""
+
+from pathlib import Path
+
+from simple_agent.tools.base_tool import BaseTool
+from simple_agent.tools.utils import error
+from simple_agent.tools.list_files import ListFilesTool
+from simple_agent.tools.read_file import ReadFileTool
+from simple_agent.tools.search_text import SearchTextTool
+from simple_agent.tools.write_file import WriteFileTool
+from simple_agent.tools.edit_file import EditFileTool
+from simple_agent.tools.run_command import RunCommandTool
+
+
+class Tools:
+    """Small tool dispatcher scoped to a workspace directory."""
+
+    def __init__(
+        self,
+        root: str | Path = ".",
+        max_read_chars: int = 12_000,
+        max_search_results: int = 20,
+    ) -> None:
+        self.root = Path(root).resolve()
+        self.max_read_chars = max_read_chars
+        self.max_search_results = max_search_results
+        self.tools: dict[str, BaseTool] = {
+            tool.name: tool
+            for tool in [
+                ListFilesTool(),
+                ReadFileTool(max_chars=self.max_read_chars),
+                SearchTextTool(max_results=self.max_search_results),
+                WriteFileTool(),
+                EditFileTool(),
+                RunCommandTool(),
+            ]
+        }
+
+    def definitions(self) -> list[dict[str, object]]:
+        return [tool.definition for tool in self.tools.values()]
+
+    def run(self, name: str, arguments: dict[str, object]) -> str:
+        tool = self.tools.get(name)
+        if tool is None:
+            return error(f"unknown tool: {name}")
+        return tool.run(self.root, arguments)

simple_agent/tools/utils.py

@@ -0,0 +1,11 @@
+"""Shared helpers for workspace tools."""
+
+import json
+
+
+def ok(data: dict[str, object]) -> str:
+    return json.dumps({"ok": True, **data})
+
+
+def error(message: str) -> str:
+    return json.dumps({"ok": False, "error": message})

simple_agent/tools/write_file.py

@@ -0,0 +1,55 @@
+"""Tool for creating or overwriting workspace files."""
+
+from pathlib import Path
+
+from simple_agent.tools.base_tool import BaseTool
+from simple_agent.tools.permissions.file_permission import FilePermissionError, WorkspacePermission
+from simple_agent.tools.utils import error, ok
+
+
+class WriteFileTool(BaseTool):
+    """Create or overwrite a file inside the workspace."""
+
+    name = "write_file"
+    description = "Create or overwrite a file inside the workspace."
+    parameters = {
+        "type": "object",
+        "properties": {
+            "path": {
+                "type": "string",
+                "description": "Workspace-relative file path.",
+            },
+            "content": {
+                "type": "string",
+                "description": "Full file content.",
+            },
+        },
+        "required": ["path", "content"],
+    }
+
+    def run(self, root: Path, arguments: dict[str, object]) -> str:
+        path = arguments.get("path")
+        content = arguments.get("content")
+        if not isinstance(path, str):
+            return error("path is required")
+        if not isinstance(content, str) or not content:
+            return error("content is required")
+
+        try:
+            permissions = WorkspacePermission(root)
+            workspace_path = permissions.require_access(path, must_exist=False)
+        except FilePermissionError as exc:
+            return error(str(exc))
+
+        if workspace_path.is_dir():
+            return error(f"path is not a file: {path}")
+
+        try:
+            workspace_path.write_text(content, encoding="utf-8")
+        except OSError as exc:
+            return error(f"could not write file: {exc}")
+
+        return ok({
+            "path": permissions.relative_to_workspace(workspace_path),
+            "written": len(content),
+        })