codex-agent-framework 0.1.1__py3-none-any.whl

codex_agent/builtin_tools.py

@@ -0,0 +1,418 @@
+import os
+import subprocess
+import sys
+import webbrowser
+from collections.abc import Mapping
+
+from .image import persist_image_url
+from .memory import format_memory_results_xml
+from .tool import ImageGenerationTool, WebSearchTool, get_agent, tool
+from .utils import read_document_content
+
+web_search = WebSearchTool()
+image_generation = ImageGenerationTool()
+
+
+@tool
+def read(source, start_at_line: int = 1):
+    """
+    description: |
+        Read and extract text content from various sources including folders, files, urls or python variables / objects.
+        This tool reads exactly one source per call. To read multiple sources at once, issue multiple `read` tool calls in parallel.
+        For folders: returns a tree view of the folder structure.
+        For files: returns the text content. PDF, DOCX, XLSX, PPTX, ODT, HTML, TXT, and more are supported.
+        For urls: returns the text content of the web page (or of the remote file if the url points to a file).
+        For python variables / objects: introspects the object or gives a str repr.
+
+        For large outputs: The output will be automatically truncated to fit token limits. When truncated, you'll see a message at the end of content indicating the truncated line range to know from where to resume reading.
+    parameters:
+        source:
+            description: |
+                Document source - can be either:
+                - Absolute path to a local folder or file (e.g., "/home/user/document.pdf")
+                - URL (e.g., "https://example.com/report.pdf")
+                - any other data structure, or python variable living in the shell's namespace
+                Pass only one source. Use parallel `read` calls for multiple sources.
+        start_at_line:
+            description: |
+                Line number to start reading from (1-indexed). Default is 1 (start from beginning).
+                When reading large documents in chunks, set this to continue from where you left off.
+            type: integer
+    required:
+        - source
+    """
+    agent = get_agent()
+    max_tokens = agent.config.get('max_input_tokens', 8000)
+    return read_document_content(source, start_at_line=start_at_line, max_tokens=max_tokens)
+
+
+@tool(type="custom")
+def python(content=None):
+    """
+    Runs Python code in the interactive shell. Pass raw Python source code,
+    not JSON, quotes, or a markdown code fence.
+    """
+    agent = get_agent()
+    if agent.shell is not None and content:
+        response = agent.shell.run(content)
+        if response.exception:
+            exception = response.exception
+            return f"**{type(exception).__name__}**: {str(exception)}\n```\n{exception.enriched_traceback_string}\n```"
+
+        output = ""
+        if response.stdout:
+            output += f"stdout:\n{response.stdout}"
+        if response.result:
+            output += f"result:\n{str(response.result)}"
+        return output
+
+    return "Shell not initialized. Cannot run code."
+
+
+@tool(type="custom")
+def bash(content=None):
+    """
+    Runs Bash commands on the local system. Pass raw shell script text,
+    not JSON, quotes, or a markdown code fence.
+    """
+    if not content:
+        return "No bash command provided."
+
+    response = subprocess.run(
+        str(content),
+        shell=True,
+        executable="/bin/bash",
+        text=True,
+        capture_output=True,
+        cwd=os.getcwd(),
+    )
+    output = ""
+    if response.stdout:
+        output += f"stdout:\n{response.stdout}"
+    if response.stderr:
+        output += f"stderr:\n{response.stderr}"
+    if response.returncode:
+        output += f"exit_code: {response.returncode}"
+    return output or "Command completed with no output."
+
+
+@tool
+def write(writes):
+    """
+    description: |
+        Write or overwrite one or more complete UTF-8 text files.
+        Use this when creating new text files or replacing entire files is clearer than targeted edits.
+        Parent directories are created automatically.
+        Pass either a single write object or a list of write objects.
+    parameters:
+        writes:
+            description: |
+                A single write object or a list of write objects.
+                Each object must contain file_path and content.
+            anyOf:
+                - type: object
+                  properties:
+                    file_path:
+                        type: string
+                    content:
+                        type: string
+                  required:
+                    - file_path
+                    - content
+                - type: array
+                  items:
+                    type: object
+                    properties:
+                        file_path:
+                            type: string
+                        content:
+                            type: string
+                    required:
+                        - file_path
+                        - content
+    """
+    if isinstance(writes, Mapping):
+        writes = [writes]
+    elif not isinstance(writes, list):
+        return "Failed: writes must be an object or a list of objects."
+
+    reports = []
+    for index, item in enumerate(writes, start=1):
+        reports.append(apply_file_write(index, item))
+    return "\n".join(reports)
+
+
+def apply_file_write(index, item):
+    if not isinstance(item, Mapping):
+        return f"{index}. failed: write must be an object."
+
+    file_path = item.get("file_path")
+    content = item.get("content")
+    if not file_path:
+        return f"{index}. failed: file_path must not be empty."
+    if content is None:
+        return f"{index}. failed: content must not be null."
+
+    path = os.path.abspath(os.path.expanduser(str(file_path)))
+    try:
+        parent = os.path.dirname(path)
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(str(content))
+    except OSError as exc:
+        return f"{index}. failed: could not write {path}: {exc}"
+
+    return f"{index}. success: wrote {len(str(content))} characters to {path}."
+
+
+@tool
+def edit(edits):
+    """
+    description: |
+        Perform targeted exact-string replacements in local text files.
+        Pass either a single edit object or a list of edit objects.
+        Each edit object must contain:
+        - file_path: path to the file to edit
+        - old_string: exact text to replace
+        - new_string: replacement text
+        - replace_all: optional boolean, default false
+
+        By default old_string must match exactly once in the file. If it matches
+        zero times or more than once, that edit fails and the file is left unchanged.
+        Set replace_all=true to replace every match.
+        Multiple edits are tried in sequence; later edits see the result of earlier successful edits.
+    parameters:
+        edits:
+            description: A single edit object or a list of edit objects.
+    required:
+        - edits
+    """
+    if isinstance(edits, Mapping):
+        edit_items = [edits]
+    elif isinstance(edits, list):
+        edit_items = edits
+    else:
+        return "Failed: edits must be an object or a list of objects."
+
+    reports = []
+    for index, item in enumerate(edit_items, start=1):
+        reports.append(apply_text_edit(index, item))
+    return "\n".join(reports)
+
+
+def apply_text_edit(index, item):
+    if not isinstance(item, Mapping):
+        return f"{index}. failed: edit must be an object."
+
+    file_path = item.get("file_path")
+    old_string = item.get("old_string")
+    new_string = item.get("new_string")
+    replace_all = bool(item.get("replace_all", False))
+
+    missing = [
+        key for key, value in (
+            ("file_path", file_path),
+            ("old_string", old_string),
+            ("new_string", new_string),
+        )
+        if value is None
+    ]
+    if missing:
+        return f"{index}. failed: missing {', '.join(missing)}."
+    if old_string == "":
+        return f"{index}. failed: old_string must not be empty."
+
+    path = os.path.abspath(os.path.expanduser(str(file_path)))
+    if not os.path.isfile(path):
+        return f"{index}. failed: file not found: {path}"
+
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            content = f.read()
+    except UnicodeDecodeError:
+        return f"{index}. failed: file is not valid UTF-8 text: {path}"
+    except OSError as exc:
+        return f"{index}. failed: could not read {path}: {exc}"
+
+    old_string = str(old_string)
+    new_string = str(new_string)
+    matches = content.count(old_string)
+    if matches == 0:
+        return f"{index}. failed: old_string not found in {path}."
+    if matches > 1 and not replace_all:
+        return f"{index}. failed: old_string matched {matches} times in {path}; set replace_all=true to replace all matches."
+
+    updated = content.replace(old_string, new_string) if replace_all else content.replace(old_string, new_string, 1)
+    try:
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(updated)
+    except OSError as exc:
+        return f"{index}. failed: could not write {path}: {exc}"
+
+    replaced = matches if replace_all else 1
+    return f"{index}. success: replaced {replaced} match{'es' if replaced != 1 else ''} in {path}."
+
+
+@tool
+def memory_add(content: str, title: str = ""):
+    """
+    description: |
+        Create a durable memory entry in the agent's runtime memory store.
+        Use this only for information that should be remembered beyond the current session.
+    parameters:
+        content:
+            description: The memory text to store.
+            type: string
+        title:
+            description: Optional title that can later be used instead of the memory id.
+            type: string
+    required:
+        - content
+    """
+    entry = get_agent().memory.remember(content=content, title=title)
+    return f"Created memory {entry.id}: {entry.content}"
+
+
+@tool
+def memory_edit(memory_id: str, content: str):
+    """
+    description: |
+        Edit an existing durable memory entry by id.
+        The memory_id argument can be either the memory id or its title. Editing content refreshes the embedding.
+    parameters:
+        memory_id:
+            description: The id or title of the memory entry to edit.
+            type: string
+        content:
+            description: Replacement memory text.
+            type: string
+    required:
+        - memory_id
+        - content
+    """
+    entry = get_agent().memory.edit(memory_id, content=content)
+    return f"Updated memory {entry.id}: {entry.content}"
+
+
+@tool
+def memory_delete(memory_id: str):
+    """
+    description: |
+        Delete a durable memory entry by id.
+        The memory_id argument can be either the memory id or its title.
+    parameters:
+        memory_id:
+            description: The id or title of the memory entry to delete.
+            type: string
+    required:
+        - memory_id
+    """
+    entry = get_agent().memory.delete(memory_id)
+    if entry is None:
+        return f"Memory not found: {memory_id}"
+    return f"Deleted memory {entry.id}: {entry.content}"
+
+
+@tool
+def memory_search(query: str, limit: int = 5, recent_is_better: bool = False):
+    """
+    description: |
+        Search durable memory entries by semantic similarity to a text query.
+        This does not create a new memory entry.
+    parameters:
+        query:
+            description: Search query text.
+            type: string
+        limit:
+            description: Maximum number of memory entries to return.
+            type: integer
+        recent_is_better:
+            description: Whether to add the temporal recency score to semantic relevance (favors more recent).
+            type: boolean
+    required:
+        - query
+    """
+    agent = get_agent()
+    results = agent.memory.search(
+        query,
+        limit=limit,
+        recent_is_better=recent_is_better,
+        until=agent.memory_retrieval_until_timestamp(),
+    )
+    if not results:
+        return "No memories found."
+    return format_memory_results_xml(results)
+
+
+@tool
+def observe(source: str):
+    """
+    description: |
+        Observe and analyze an image by adding it to the conversation context.
+        The image will be available for visual analysis in the next response.
+        Supports local file paths and URLs (http/https).
+
+        Use this tool when you need to see and analyze images, screenshots, diagrams, charts, photos, or any visual content.
+    parameters:
+        source:
+            description: |
+                Image source - can be either:
+                - Absolute file path to a local image file (e.g., "/home/user/image.png")
+                - URL to an image (e.g., "https://example.com/image.jpg")
+            type: string
+    required:
+        - source
+    """
+    original_source = source
+    if isinstance(source, str) and source.startswith(("http://", "https://")):
+        source = persist_image_url(source)
+        get_agent().add_image(source=source, pending=True, image_name=original_source)
+        return (
+            f"Image from '{original_source}' has been downloaded, cached at '{source}', "
+            "and is now visible for analysis."
+        )
+
+    get_agent().add_image(source=source, pending=True)
+    return f"Image from '{source}' has been loaded and is now visible for analysis."
+
+
+@tool
+def show(file_or_url: str):
+    """
+    description: |
+        Open a local file, folder, or URL with the system default application/browser.
+        Use this tool when the user wants to visually inspect a source outside the chat.
+    parameters:
+        file_or_url:
+            description: Absolute or relative local path, folder path, file URI, or HTTP(S) URL to open.
+            type: string
+    required:
+        - file_or_url
+    """
+    target = str(file_or_url)
+    if not target.startswith(("http://", "https://", "file://")):
+        target = os.path.abspath(os.path.expanduser(target))
+
+    opened = open_silently(target)
+    if opened:
+        return f"Opened: {target}"
+    return f"Could not open: {target}"
+
+
+def open_silently(target: str) -> bool:
+    if os.name == "posix":
+        opener = "open" if sys.platform == "darwin" else "xdg-open"
+        try:
+            subprocess.Popen(
+                [opener, target],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                stdin=subprocess.DEVNULL,
+                start_new_session=True,
+            )
+            return True
+        except FileNotFoundError:
+            pass
+
+    return webbrowser.open(target)

codex_agent/chat.py

@@ -0,0 +1,139 @@
+from prompt_toolkit import PromptSession
+from rich.console import Console
+from rich.panel import Panel
+from rich.rule import Rule
+from rich.text import Text
+from .event import ResponseContentDeltaEvent, ResponseDoneEvent, ResponseStartEvent, ServerToolCallEvent, ToolCallStartEvent
+
+
+class TerminalChat:
+    """Small terminal UI wired to agent events."""
+
+    def __init__(self, agent, console=None):
+        self.agent = agent
+        self.console = console or Console()
+        self.prompt_session = PromptSession(multiline=True)
+        self._in_response = False
+        self._has_content = False
+        self._seen_tool_calls = set()
+
+    def attach(self):
+        self.agent.on(ResponseStartEvent, self._on_response_start)
+        self.agent.on(ResponseContentDeltaEvent, self._on_content_delta)
+        self.agent.on(ToolCallStartEvent, self._on_tool_call_start)
+        self.agent.on(ServerToolCallEvent, self._on_server_tool_call)
+        self.agent.on(ResponseDoneEvent, self._on_response_done)
+        return self
+
+    def run(self):
+        self.attach()
+        self.console.print(Panel.fit(
+            "[bold]Codex Agent[/bold]\n[dim]Alt+Enter submits multiline input. Type exit or quit to stop.[/dim]",
+            border_style="cyan",
+        ))
+        while True:
+            try:
+                self.print_status_bar()
+                prompt = self.prompt_session.prompt(
+                    [("class:prompt", "You > ")],
+                    prompt_continuation="...   ",
+                )
+                if prompt.strip().lower() in ["exit", "quit", "/exit", "/quit"]:
+                    self.console.print("[dim]Bye.[/dim]")
+                    break
+                if not prompt.strip():
+                    continue
+                try:
+                    result = self.agent(prompt)
+                    if isinstance(result, str) and result:
+                        self.console.print(result, style="dim")
+                except KeyboardInterrupt:
+                    self.agent.interrupt("keyboard_interrupt")
+                    self.console.print("\n[dim]Interrupted.[/dim]")
+                self.console.print()
+            except (KeyboardInterrupt, EOFError):
+                self.console.print("\n[dim]Bye.[/dim]")
+                break
+
+    def print_status_bar(self):
+        try:
+            status = self.agent.context_status()
+        except Exception as exc:
+            self.console.print(f"[dim red]status unavailable: {exc}[/dim red]")
+            return
+
+        percent = status.percent
+        style = "green"
+        if percent >= 90:
+            style = "bold red"
+        elif percent >= 75:
+            style = "yellow"
+        elif percent >= 50:
+            style = "cyan"
+
+        used = self._format_int(status.used_tokens)
+        limit = self._format_int(status.input_token_limit)
+        session = str(status.session_id or "-")[-15:]
+        compact_hint = " auto-compact:on" if status.auto_compact else " auto-compact:off"
+        if status.auto_compact and status.used_tokens >= status.auto_compact_threshold:
+            compact_hint = " auto-compact:due"
+
+        self.console.print(
+            Text.assemble(
+                ("ctx ", "dim"),
+                (f"{percent:.1f}%", style),
+                (f" {used}/{limit} tok", "dim"),
+                (f" · hist {status.visible_history_messages}/{status.total_history_messages}", "dim"),
+                (f" · msgs {status.total_session_messages}", "dim"),
+                (f" · img {status.image_messages}", "dim"),
+                (f" · mem {status.memory_entries}", "dim"),
+                (f" · pending {status.pending_messages}", "dim"),
+                (f" · {session}", "dim"),
+                (compact_hint, "dim"),
+            )
+        )
+
+    @staticmethod
+    def _format_int(value):
+        try:
+            return f"{int(value):,}".replace(",", " ")
+        except Exception:
+            return str(value)
+
+    def _on_response_start(self, event):
+        if self._in_response:
+            self.console.print()
+        self._in_response = True
+        self._has_content = False
+        self._seen_tool_calls.clear()
+        name = event.message.get("name") if event.get("message") else None
+        self.console.print(Rule(Text(name or "Agent", style="bold cyan"), style="cyan"))
+
+    def _on_content_delta(self, event):
+        self._has_content = True
+        self.console.print(event.delta, end="", markup=False, highlight=False, soft_wrap=True)
+
+    def _on_tool_call_start(self, event):
+        tool_call = event.get("tool_call") or {}
+        name = tool_call.get("name") or "unknown"
+        call_id = tool_call.get("call_id") or name
+        self._print_tool_call(name, call_id)
+
+    def _on_server_tool_call(self, event):
+        name = event.get("name") or "unknown"
+        call_id = event.get("call_id") or name
+        self._print_tool_call(name, call_id)
+
+    def _print_tool_call(self, name, call_id):
+        if call_id in self._seen_tool_calls:
+            return
+        self._seen_tool_calls.add(call_id)
+        if self._has_content:
+            self.console.print()
+        self.console.print(f"tool: {name}", style="dim cyan")
+        self._has_content = False
+
+    def _on_response_done(self, event):
+        if self._has_content:
+            self.console.print()
+        self._in_response = False

codex_agent/command.py

@@ -0,0 +1,19 @@
+from modict import modict
+
+
+COMMAND_MARKER = "__codex_agent_command__"
+
+
+def command(func=None, **options):
+    """Mark a function as an agent slash command for automatic discovery."""
+    if func is None:
+        def decorator(f):
+            return command(f, **options)
+        return decorator
+
+    setattr(func, COMMAND_MARKER, modict(options))
+    return func
+
+
+def command_options(func):
+    return getattr(func, COMMAND_MARKER, None)