codex-agent-framework 0.1.26__tar.gz → 0.1.27__tar.gz

{codex_agent_framework-0.1.26/codex_agent_framework.egg-info → codex_agent_framework-0.1.27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-agent-framework
-Version: 0.1.26
+Version: 0.1.27
 Summary: A lightweight event-driven Codex agent runtime.
 Author: Baptiste
 License-Expression: MIT
@@ -626,6 +626,7 @@ Core LLM calls, memory embeddings, non-streaming STT transcription, and realtime
 
 ## Recent releases
 
+- `0.1.27`: upgrade the agentic `read` tool with folder trees, recursive folder pattern search, and precise `start_at_line`/`end_at_line` ranges; add visible wrapper/token split stats, compactable turn counts, and refreshed TUI status-bar context telemetry.
 - `0.1.26`: align SDK-facing config with Responses API shapes, add the `context` management plugin with selective non-destructive wrapper pruning, keep wrappers out of memory retrieval and compaction payloads, move embeddings/STT/realtime onto Codex backend auth, streamline voice/TTS plugin config, and improve TUI streaming/windowing.
 - `0.1.25`: move built-in capabilities further into plugin-scoped modules, add bundled plugin requirement metadata, and replace the TUI conversation pane with a selectable rich chat area that preserves mouse scrolling, copy selection, lazy transcript loading, and bottom-aware auto-scroll.
 - `0.1.24`: add slash-command lifecycle events and TUI progress/result rendering so commands such as `/compact` and `/help` show running, done, failed, result, and error feedback instead of going silent.

{codex_agent_framework-0.1.26 → codex_agent_framework-0.1.27}/README.md

@@ -577,6 +577,7 @@ Core LLM calls, memory embeddings, non-streaming STT transcription, and realtime
 
 ## Recent releases
 
+- `0.1.27`: upgrade the agentic `read` tool with folder trees, recursive folder pattern search, and precise `start_at_line`/`end_at_line` ranges; add visible wrapper/token split stats, compactable turn counts, and refreshed TUI status-bar context telemetry.
 - `0.1.26`: align SDK-facing config with Responses API shapes, add the `context` management plugin with selective non-destructive wrapper pruning, keep wrappers out of memory retrieval and compaction payloads, move embeddings/STT/realtime onto Codex backend auth, streamline voice/TTS plugin config, and improve TUI streaming/windowing.
 - `0.1.25`: move built-in capabilities further into plugin-scoped modules, add bundled plugin requirement metadata, and replace the TUI conversation pane with a selectable rich chat area that preserves mouse scrolling, copy selection, lazy transcript loading, and bottom-aware auto-scroll.
 - `0.1.24`: add slash-command lifecycle events and TUI progress/result rendering so commands such as `/compact` and `/help` show running, done, failed, result, and error feedback instead of going silent.

{codex_agent_framework-0.1.26 → codex_agent_framework-0.1.27}/codex_agent/builtin_plugins/context/__init__.py

@@ -33,6 +33,15 @@ Tool result wrappers expose stable `wrapper_id` values in their XML representati
             total_history_messages=status.get("total_history_messages", 0),
             persistent_session_messages=status.get("persistent_session_messages", 0),
             temporary_session_messages=status.get("temporary_session_messages", 0),
+            active_wrapper_messages=status.get("active_wrapper_messages", 0),
+            vanished_wrapper_messages=status.get("vanished_wrapper_messages", 0),
+            total_wrapper_messages=status.get("total_wrapper_messages", 0),
+            base_context_tokens=status.get("base_context_tokens", status.used_tokens),
+            active_wrapper_tokens=status.get("active_wrapper_tokens", 0),
+            vanished_wrapper_tokens=status.get("vanished_wrapper_tokens", 0),
+            compactable_turns=status.get("compactable_turns", 0),
+            compactable_messages=status.get("compactable_messages", 0),
+            compactable_tokens=status.get("compactable_tokens", 0),
             context_session_messages=status.get("context_session_messages", 0),
             image_messages=status.get("image_messages", 0),
             pending_messages=status.get("pending_messages", 0),
@@ -48,8 +57,11 @@ Tool result wrappers expose stable `wrapper_id` values in their XML representati
         return "\n".join([
             "Context status:",
             f"- tokens: {status.used_tokens}/{status.input_token_limit} ({status.percent:.2f}%)",
+            f"- token split base/active_wrappers/vanished_wrappers: {status.base_context_tokens}/{status.active_wrapper_tokens}/{status.vanished_wrapper_tokens}",
             f"- messages sent/total: {status.sent_session_messages}/{status.total_session_messages}",
             f"- persistent/temporary context messages: {status.persistent_session_messages}/{status.temporary_session_messages}",
+            f"- wrappers active/vanished/total: {status.active_wrapper_messages}/{status.vanished_wrapper_messages}/{status.total_wrapper_messages}",
+            f"- compactable turns/messages/tokens: {status.compactable_turns}/{status.compactable_messages}/{status.compactable_tokens}",
             f"- visible/total history messages: {status.visible_history_messages}/{status.total_history_messages}",
             f"- tool spec tokens: {status.tool_spec_tokens}",
             f"- auto_compact: {status.auto_compact} threshold={status.auto_compact_threshold}",

{codex_agent_framework-0.1.26 → codex_agent_framework-0.1.27}/codex_agent/builtin_plugins/files/__init__.py

@@ -7,13 +7,13 @@ from . import tools as file_tools
 
 class FilesPlugin(Plugin):
     name = "files"
-    description = "Strict local UTF-8 file read/write/edit operations."
+    description = "Strict local UTF-8 file/folder read and search plus write/edit operations."
     prefix_tools = False
     system_prompt = """
 # File Tools
 
-Use the specialized file tools for local UTF-8 text file operations:
-- `read`: read line-numbered local UTF-8 files precisely, with optional pattern search.
+Use the specialized file tools for local UTF-8 text operations:
+- `read`: read line-numbered local UTF-8 files precisely, list local folders as a compact one-level tree, or search folders recursively with a pattern.
 - `write`: create or overwrite complete UTF-8 text files; use with caution.
 - `edit`: perform targeted exact-string replacements in local UTF-8 text files.
 

{codex_agent_framework-0.1.26 → codex_agent_framework-0.1.27}/codex_agent/builtin_plugins/files/tools.py

@@ -8,10 +8,11 @@ from ...utils import read_document_content, view_document_content
 def read(reads):
     """
     description: |
-        Strictly read one or more local UTF-8 text files as source-of-truth content.
-        This tool always prefixes returned content with reliable source line numbers.
-        It does not extract document formats, fetch URLs, inspect Python objects, or render directory trees.
-        Use `view` for folders, URLs, PDFs, DOCX, ODT, HTML, XLSX, and other extracted or transformed content.
+        Read one or more local UTF-8 text files or folders as source-of-truth content.
+        File reads always prefix returned content with reliable source line numbers.
+        Folder reads without `pattern` render a compact tree with one level of recursion.
+        Folder reads with `pattern` recursively search UTF-8 files under the folder and return numbered snippets per matching file.
+        This tool does not extract document formats, fetch URLs, or inspect Python objects; use `view` for URLs, PDFs, DOCX, ODT, HTML, XLSX, archives, and other extracted or transformed content.
 
         For large outputs: the output is automatically truncated. When truncated, a message indicates the omitted line range.
         When `pattern` is provided, it is treated as a Python regex by default and all matches are returned as separated numbered snippets with up to 10 lines before and after each match.
@@ -20,16 +21,19 @@ def read(reads):
         reads:
             description: |
                 A single read object or a list of read objects.
-                Each object must contain `source` and may contain `start_at_line`, `pattern`, and `regex`.
+                Each object must contain `source` and may contain `start_at_line`, `end_at_line`, `pattern`, and `regex`.
             anyOf:
                 - type: object
                   properties:
                     source:
-                        description: Local UTF-8 text file path only. For directories, URLs, rich documents, or Python objects, use `view` instead.
+                        description: Local UTF-8 text file or folder path. Folders are listed as a compact tree, or searched recursively when pattern is provided. For URLs, rich documents, archives, or Python objects, use `view` instead.
                         type: string
                     start_at_line:
                         description: Line number to start reading from (1-indexed). Default is 1 (start from beginning).
                         type: integer
+                    end_at_line:
+                        description: Optional inclusive line number to stop reading at for direct file reads.
+                        type: integer
                     pattern:
                         description: Optional search pattern. Treated as a Python regular expression by default.
                         type: string
@@ -43,9 +47,12 @@ def read(reads):
                     type: object
                     properties:
                         source:
+                            description: Local UTF-8 text file or folder path. Folders are listed as a compact tree, or searched recursively when pattern is provided.
                             type: string
                         start_at_line:
                             type: integer
+                        end_at_line:
+                            type: integer
                         pattern:
                             type: string
                         regex:
@@ -79,6 +86,7 @@ def apply_file_read(item):
         return read_document_content(
             source,
             start_at_line=item.get("start_at_line", 1),
+            end_at_line=item.get("end_at_line"),
             max_tokens=max_tokens,
             pattern=item.get("pattern"),
             regex=item.get("regex", True),

codex_agent_framework-0.1.27/codex_agent/builtin_plugins/interface/__init__.py

@@ -0,0 +1,53 @@
+"""Built-in local interface plugin."""
+
+from ...plugin import Plugin
+from ...provider import provider
+from ...tool import tool
+from ...tui import current_tui, open_tui_terminal, terminate_tui
+
+
+class InterfacePlugin(Plugin):
+    name = "interface"
+    description = "Open and close the local TUI interface."
+    prefix_tools = False
+
+    @provider
+    def tui_status(self):
+        """Expose whether the local TUI client is currently open."""
+        tui = current_tui()
+        if not tui:
+            return "TUI status: closed."
+        return (
+            "TUI status: open. "
+            f"pid={tui.get('pid')} "
+            f"base_url={tui.get('base_url')} "
+            f"timestamp={tui.get('timestamp')}"
+        )
+
+    @tool(name="open_tui")
+    def open_tui(self):
+        """
+        description: Open the Textual chat TUI client in a separate terminal connected to the local agent server.
+        parameters: {}
+        required: []
+        """
+        tui = current_tui()
+        if tui:
+            return {"status": "already_open", "tui": tui}
+        process = open_tui_terminal(base_url=self.agent.config.get("server_url", "http://127.0.0.1:8765"))
+        if process is None:
+            raise RuntimeError("No supported terminal emulator found to open the TUI")
+        return {"status": "opened", "pid": process.pid}
+
+    @tool(name="close_tui")
+    def close_tui(self):
+        """
+        description: Close the currently registered Textual chat TUI client process.
+        parameters: {}
+        required: []
+        """
+        tui = current_tui()
+        if not tui:
+            return {"status": "not_open"}
+        terminate_tui(tui.pid)
+        return {"status": "closed", "tui": tui}

{codex_agent_framework-0.1.26 → codex_agent_framework-0.1.27}/codex_agent/status.py

@@ -1,6 +1,7 @@
 from modict import modict
 
 from .image import ImageMessage
+from .message import ToolResultWrapper
 from .utils import sort, truncate
 
 
@@ -32,6 +33,7 @@ class StatusManager:
         max_images = self.agent.config.get("max_images", 10)
         context_manager = self.agent.context_manager
         context_manager.prune_orphaned_session_tool_outputs()
+        all_session_messages = list(self.agent.session.messages) if self.agent.session else []
         session_messages = sort(
             msg for msg in self.agent.session.context_messages()
             if context_manager.is_message_visible_in_context(msg)
@@ -58,7 +60,9 @@ class StatusManager:
                 history_start = len(truncated_others) - i - 1
             else:
                 break
-        visible_history_count = len(truncated_others[max(0, history_start):])
+        included_history_start = max(0, history_start)
+        visible_history_count = len(truncated_others[included_history_start:])
+        included_others = others[included_history_start:]
         sent_session_messages = visible_history_count + len(images)
         total_session_messages = len(self.agent.session.messages) if self.agent.session else 0
         persistent_session_messages = sum(
@@ -69,6 +73,39 @@ class StatusManager:
             1 for msg in session_messages
             if isinstance(msg.get("turns_left", -1), int) and msg.get("turns_left", -1) > 0
         )
+        wrappers = [msg for msg in all_session_messages if isinstance(msg, ToolResultWrapper)]
+        active_wrappers = [
+            msg for msg in wrappers
+            if isinstance(msg.get("turns_left", -1), int) and msg.get("turns_left", -1) > 0
+        ]
+        vanished_wrappers = [msg for msg in wrappers if msg.get("turns_left", -1) == 0]
+
+        def wrapper_token_count(messages):
+            total = 0
+            for msg in messages:
+                msg_copy = msg.copy()
+                if msg_copy.get("content") and isinstance(msg_copy.content, str):
+                    msg_copy.content = truncate(msg_copy.content, max_tokens=max_input_tokens, model=self.agent.config.model)
+                total += context_manager.response_input_token_count([msg_copy], response_tools=[])
+            return total
+
+        active_context_wrappers = [msg for msg in included_others if isinstance(msg, ToolResultWrapper)]
+        active_wrapper_tokens = wrapper_token_count(active_context_wrappers)
+        vanished_wrapper_tokens = wrapper_token_count(vanished_wrappers)
+        base_context_tokens = max(0, current_count - active_wrapper_tokens)
+        if self.agent.session:
+            compaction_plan = self.agent.session.compaction_plan(
+                max_input_tokens=max_input_tokens,
+                model=self.agent.config.model,
+                max_compacted_turns=None,
+            )
+            compactable_turns = compaction_plan.completed_turn_count
+            compactable_messages = compaction_plan.compacted_message_count
+            compactable_tokens = compaction_plan.compacted_token_count
+        else:
+            compactable_turns = 0
+            compactable_messages = 0
+            compactable_tokens = 0
         percent = (current_count / input_limit * 100) if input_limit else 0
         status = modict(
             used_tokens=current_count,
@@ -84,6 +121,15 @@ class StatusManager:
             sent_session_message_percent=(sent_session_messages / total_session_messages * 100) if total_session_messages else 0,
             persistent_session_messages=persistent_session_messages,
             temporary_session_messages=temporary_session_messages,
+            active_wrapper_messages=len(active_wrappers),
+            vanished_wrapper_messages=len(vanished_wrappers),
+            total_wrapper_messages=len(wrappers),
+            base_context_tokens=base_context_tokens,
+            active_wrapper_tokens=active_wrapper_tokens,
+            vanished_wrapper_tokens=vanished_wrapper_tokens,
+            compactable_turns=compactable_turns,
+            compactable_messages=compactable_messages,
+            compactable_tokens=compactable_tokens,
             context_session_messages=len(session_messages),
             image_messages=len(images),
             pending_messages=len(self.agent.mainloop_manager.pending),
@@ -116,6 +162,15 @@ class StatusManager:
             sent_session_message_percent=estimated.sent_session_message_percent,
             persistent_session_messages=estimated.get("persistent_session_messages", 0),
             temporary_session_messages=estimated.get("temporary_session_messages", 0),
+            active_wrapper_messages=estimated.get("active_wrapper_messages", 0),
+            vanished_wrapper_messages=estimated.get("vanished_wrapper_messages", 0),
+            total_wrapper_messages=estimated.get("total_wrapper_messages", 0),
+            base_context_tokens=estimated.get("base_context_tokens", estimated.used_tokens),
+            active_wrapper_tokens=estimated.get("active_wrapper_tokens", 0),
+            vanished_wrapper_tokens=estimated.get("vanished_wrapper_tokens", 0),
+            compactable_turns=estimated.get("compactable_turns", 0),
+            compactable_messages=estimated.get("compactable_messages", 0),
+            compactable_tokens=estimated.get("compactable_tokens", 0),
             quota_5h_percent=None,
             quota_7d_percent=None,
             model=self.agent.config.get("model") or "gpt-5.4",
@@ -143,6 +198,15 @@ class StatusManager:
                 sent_session_message_percent=estimated.sent_session_message_percent,
                 persistent_session_messages=estimated.get("persistent_session_messages", 0),
                 temporary_session_messages=estimated.get("temporary_session_messages", 0),
+                active_wrapper_messages=estimated.get("active_wrapper_messages", 0),
+                vanished_wrapper_messages=estimated.get("vanished_wrapper_messages", 0),
+                total_wrapper_messages=estimated.get("total_wrapper_messages", 0),
+                base_context_tokens=estimated.get("base_context_tokens", estimated.used_tokens),
+                active_wrapper_tokens=estimated.get("active_wrapper_tokens", 0),
+                vanished_wrapper_tokens=estimated.get("vanished_wrapper_tokens", 0),
+                compactable_turns=estimated.get("compactable_turns", 0),
+                compactable_messages=estimated.get("compactable_messages", 0),
+                compactable_tokens=estimated.get("compactable_tokens", 0),
                 model=self.agent.config.get("model") or "gpt-5.4",
                 busy=self.agent.mainloop_manager.busy,
                 current_turn_id=self.agent.mainloop_manager.current_turn_id,
@@ -167,6 +231,15 @@ class StatusManager:
             sent_session_message_percent=estimated.sent_session_message_percent,
             persistent_session_messages=estimated.get("persistent_session_messages", 0),
             temporary_session_messages=estimated.get("temporary_session_messages", 0),
+            active_wrapper_messages=estimated.get("active_wrapper_messages", 0),
+            vanished_wrapper_messages=estimated.get("vanished_wrapper_messages", 0),
+            total_wrapper_messages=estimated.get("total_wrapper_messages", 0),
+            base_context_tokens=estimated.get("base_context_tokens", estimated.used_tokens),
+            active_wrapper_tokens=estimated.get("active_wrapper_tokens", 0),
+            vanished_wrapper_tokens=estimated.get("vanished_wrapper_tokens", 0),
+            compactable_turns=estimated.get("compactable_turns", 0),
+            compactable_messages=estimated.get("compactable_messages", 0),
+            compactable_tokens=estimated.get("compactable_tokens", 0),
             model=self.agent.config.get("model") or "gpt-5.4",
             busy=self.agent.mainloop_manager.busy,
             current_turn_id=self.agent.mainloop_manager.current_turn_id,
@@ -193,6 +266,15 @@ class StatusManager:
             sent_session_message_percent=context_status.get("sent_session_message_percent", 0),
             persistent_session_messages=context_status.get("persistent_session_messages", 0),
             temporary_session_messages=context_status.get("temporary_session_messages", 0),
+            active_wrapper_messages=context_status.get("active_wrapper_messages", 0),
+            vanished_wrapper_messages=context_status.get("vanished_wrapper_messages", 0),
+            total_wrapper_messages=context_status.get("total_wrapper_messages", 0),
+            base_context_tokens=context_status.get("base_context_tokens", max(0, input_tokens)),
+            active_wrapper_tokens=context_status.get("active_wrapper_tokens", 0),
+            vanished_wrapper_tokens=context_status.get("vanished_wrapper_tokens", 0),
+            compactable_turns=context_status.get("compactable_turns", 0),
+            compactable_messages=context_status.get("compactable_messages", 0),
+            compactable_tokens=context_status.get("compactable_tokens", 0),
             quota_5h_percent=wham.quota_5h_percent,
             quota_7d_percent=wham.quota_7d_percent,
             model=model or self.agent.config.get("model") or "gpt-5.4",

{codex_agent_framework-0.1.26 → codex_agent_framework-0.1.27}/codex_agent/tui/chat.py

@@ -801,20 +801,34 @@ class Chat:
         context_style = cls._percent_style(percent)
         used = cls._format_ktok(status.get("context_current_tokens") or 0)
         limit = cls._format_ktok(status.get("context_limit_tokens") or 0)
+        context_segments = cls._context_token_status_segments(status, used, limit)
         quota_5h = cls._format_percent(status.get("quota_5h_percent"))
         quota_7d = cls._format_percent(status.get("quota_7d_percent"))
         sent_messages = int(status.get("sent_session_messages") or 0)
         persistent_messages = status.get("persistent_session_messages")
         temporary_messages = status.get("temporary_session_messages")
+        active_wrapper_messages = status.get("active_wrapper_messages")
+        vanished_wrapper_messages = status.get("vanished_wrapper_messages")
         total_messages = int(status.get("total_session_messages") or 0)
+        compactable_turns = int(status.get("compactable_turns") or 0)
         model = status.get("model") or "-"
-        message_segments = cls._message_status_segments(sent_messages, persistent_messages, temporary_messages, total_messages)
+        message_segments = cls._message_status_segments(
+            sent_messages,
+            persistent_messages,
+            temporary_messages,
+            total_messages,
+            active_wrapper_messages=active_wrapper_messages,
+            vanished_wrapper_messages=vanished_wrapper_messages,
+        )
         return Text.assemble(
             (" ctx ", "bold #c9d1d9 on #161b22"),
-            (f"{used}/{limit} ktok ", "#8b949e on #161b22"),
+            *context_segments,
+            (" ", "#8b949e on #161b22"),
             (f"{percent:.1f}%", f"{context_style} on #161b22"),
             ("  msg ", "#6e7681 on #161b22"),
             *message_segments,
+            ("  cmp ", "#6e7681 on #161b22"),
+            (str(compactable_turns), "#c9d1d9 on #161b22"),
             ("  5h ", "#6e7681 on #161b22"),
             (quota_5h, f"{cls._percent_style(status.get('quota_5h_percent'))} on #161b22"),
             ("  7d ", "#6e7681 on #161b22"),
@@ -823,18 +837,41 @@ class Chat:
             (str(model), "#c9d1d9 on #161b22"),
         )
 
+    @classmethod
+    def _context_token_status_segments(cls, status, used, limit):
+        if "base_context_tokens" not in status and "active_wrapper_tokens" not in status and "vanished_wrapper_tokens" not in status:
+            return ((f"{used}/{limit} ktok", "#8b949e on #161b22"),)
+        base = cls._format_ktok(status.get("base_context_tokens") or 0)
+        active_wrappers = cls._format_ktok(status.get("active_wrapper_tokens") or 0)
+        vanished_wrappers = cls._format_ktok(status.get("vanished_wrapper_tokens") or 0)
+        return (
+            (base, "#c9d1d9 on #161b22"),
+            (f"+{active_wrappers}", "italic #f0883e on #161b22"),
+            (f"+{vanished_wrappers}", "italic #6e7681 on #161b22"),
+            (f"/{limit} ktok", "#8b949e on #161b22"),
+        )
+
     @staticmethod
-    def _message_status_segments(sent_messages, persistent_messages, temporary_messages, total_messages):
-        if persistent_messages is None and temporary_messages is None:
+    def _message_status_segments(sent_messages, persistent_messages, temporary_messages, total_messages, *, active_wrapper_messages=None, vanished_wrapper_messages=None):
+        if persistent_messages is None and temporary_messages is None and active_wrapper_messages is None and vanished_wrapper_messages is None:
             return ((f"{sent_messages}/{total_messages}", "#c9d1d9 on #161b22"),)
         try:
             persistent = int(persistent_messages or 0)
-            temporary = int(temporary_messages or 0)
+            if active_wrapper_messages is None and vanished_wrapper_messages is None:
+                temporary = int(temporary_messages or 0)
+                return (
+                    (str(persistent), "#c9d1d9 on #161b22"),
+                    (f"+{temporary}", "italic #f0883e on #161b22"),
+                    (f"/{total_messages}", "#c9d1d9 on #161b22"),
+                )
+            active_wrappers = int(active_wrapper_messages or 0)
+            vanished_wrappers = int(vanished_wrapper_messages or 0)
         except Exception:
             return ((f"{sent_messages}/{total_messages}", "#c9d1d9 on #161b22"),)
         return (
             (str(persistent), "#c9d1d9 on #161b22"),
-            (f"+{temporary}", "italic #f0883e on #161b22"),
+            (f"+{active_wrappers}", "italic #f0883e on #161b22"),
+            (f"+{vanished_wrappers}", "italic #6e7681 on #161b22"),
             (f"/{total_messages}", "#c9d1d9 on #161b22"),
         )
 

{codex_agent_framework-0.1.26 → codex_agent_framework-0.1.27}/codex_agent/utils.py

@@ -105,18 +105,21 @@ def add_line_numbers(text: str, start_line: int = 1, total_lines: int | None = N
     return _number_lines(text.splitlines(), start_line=start_line, total_lines=total_lines)
 
 
-def pattern_snippets(text: str, pattern, context_lines: int = 10, regex_pattern: bool = True) -> str:
+def pattern_line_numbers(text: str, pattern, regex_pattern: bool = True) -> list[int]:
     pattern_text = str(pattern)
     lines = text.splitlines()
-    total_lines = len(lines)
     if regex_pattern:
         try:
             compiled_pattern = re.compile(pattern_text)
         except re.error as exc:
             raise ValueError(f"Invalid regex pattern {pattern_text!r}: {exc}") from exc
-        matches = [index for index, line in enumerate(lines, start=1) if compiled_pattern.search(line)]
-    else:
-        matches = [index for index, line in enumerate(lines, start=1) if pattern_text in line]
+        return [index for index, line in enumerate(lines, start=1) if compiled_pattern.search(line)]
+    return [index for index, line in enumerate(lines, start=1) if pattern_text in line]
+
+
+def _numbered_snippets_for_matches(text: str, matches: list[int], context_lines: int = 10) -> str:
+    lines = text.splitlines()
+    total_lines = len(lines)
     if not matches:
         return _number_lines(lines, start_line=1, total_lines=total_lines)
 
@@ -139,6 +142,14 @@ def pattern_snippets(text: str, pattern, context_lines: int = 10, regex_pattern:
         )
     return "\n\n".join(parts)
 
+
+def pattern_snippets(text: str, pattern, context_lines: int = 10, regex_pattern: bool = True) -> str:
+    return _numbered_snippets_for_matches(
+        text,
+        pattern_line_numbers(text, pattern, regex_pattern=regex_pattern),
+        context_lines=context_lines,
+    )
+
 def short_id(length=8):
     return "".join(random.choices(string.ascii_letters,k=length))
 
@@ -461,14 +472,45 @@ class Logger:
         with open(file,'w',encoding="utf-8") as f:
             f.write(str(content)+'\n')
 
-def _render_numbered_read_text(text: str, start_at_line=1, max_tokens=8000, pattern=None, pattern_context_lines=10, regex=True):
-    effective_start_at_line = int(start_at_line or 1)
+def _render_numbered_read_text(text: str, start_at_line=1, end_at_line=None, max_tokens=8000, pattern=None, pattern_context_lines=10, regex=True):
+    effective_start_at_line = max(1, int(start_at_line or 1))
     total_lines = len(text.splitlines())
     if pattern:
         text = pattern_snippets(text, pattern, context_lines=pattern_context_lines, regex_pattern=regex)
         if max_tokens > 0:
             text = truncate(text, max_tokens=max_tokens, start_line=1)
         return text
+
+    if end_at_line is not None:
+        effective_end_at_line = int(end_at_line)
+        if effective_end_at_line < effective_start_at_line:
+            raise ValueError("end_at_line must be greater than or equal to start_at_line")
+        lines = text.splitlines(keepends=True)
+        if effective_start_at_line > len(lines):
+            text = ""
+        else:
+            selected_lines = lines[effective_start_at_line - 1:effective_end_at_line]
+            if max_tokens > 0:
+                result_lines = []
+                current_tokens = 0
+                for line in selected_lines:
+                    line_tokens = token_count(line)
+                    if current_tokens + line_tokens <= max_tokens:
+                        result_lines.append(line)
+                        current_tokens += line_tokens
+                    else:
+                        break
+                text = ''.join(result_lines)
+                if len(result_lines) < len(selected_lines):
+                    if not text.endswith('\n'):
+                        text += '\n'
+                    first_truncated = effective_start_at_line + len(result_lines)
+                    last_truncated = effective_start_at_line + len(selected_lines) - 1
+                    text += f"\n...\n\n[Lines {first_truncated}-{last_truncated} truncated]\n"
+            else:
+                text = ''.join(selected_lines)
+        return add_line_numbers(text, start_line=effective_start_at_line, total_lines=total_lines)
+
     # Apply pagination and truncation - truncate function handles smart chunking internally
     if max_tokens > 0:
         text = truncate(text, max_tokens=max_tokens, start_line=effective_start_at_line)
@@ -502,24 +544,114 @@ def _view_search_snippets(text: str, search_query, context_lines: int = 10) -> s
     return "\n\n".join(parts)
 
 
-def read_document_content(source, start_at_line=1, max_tokens=8000, pattern=None, pattern_context_lines=10, regex=True):
-    """Strictly read a local UTF-8 text file without extraction, URL fetching, or directory traversal."""
+READ_DIRECTORY_EXCLUDES = {
+    ".git",
+    ".hg",
+    ".svn",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".tox",
+    ".venv",
+    "__pycache__",
+    "build",
+    "dist",
+    "node_modules",
+}
+
+
+def _directory_entries(path):
+    try:
+        entries = list(os.scandir(path))
+    except OSError as exc:
+        raise OSError(f"failed to list directory {path}: {exc}") from exc
+    entries = [entry for entry in entries if entry.name not in READ_DIRECTORY_EXCLUDES]
+    return sorted(entries, key=lambda entry: (not entry.is_dir(follow_symlinks=False), entry.name.lower()))
+
+
+def _render_directory_tree(path, max_tokens=8000):
+    root = os.path.abspath(path)
+    lines = [f"{os.path.basename(root) or root}/"]
+    entries = _directory_entries(root)
+    for index, entry in enumerate(entries):
+        is_last = index == len(entries) - 1
+        connector = "└── " if is_last else "├── "
+        child_prefix = "    " if is_last else "│   "
+        suffix = "/" if entry.is_dir(follow_symlinks=False) else ""
+        lines.append(f"{connector}{entry.name}{suffix}")
+        if entry.is_dir(follow_symlinks=False):
+            children = _directory_entries(entry.path)
+            for child_index, child in enumerate(children):
+                child_connector = "└── " if child_index == len(children) - 1 else "├── "
+                child_suffix = "/" if child.is_dir(follow_symlinks=False) else ""
+                lines.append(f"{child_prefix}{child_connector}{child.name}{child_suffix}")
+    text = "\n".join(lines)
+    if max_tokens > 0:
+        text = truncate(text, max_tokens=max_tokens, start_line=1)
+    return text
+
+
+def _iter_directory_files(path):
+    for root, dirnames, filenames in os.walk(path):
+        dirnames[:] = sorted(
+            [dirname for dirname in dirnames if dirname not in READ_DIRECTORY_EXCLUDES],
+            key=str.lower,
+        )
+        for filename in sorted(filenames, key=str.lower):
+            yield os.path.join(root, filename)
+
+
+def _read_utf8_text_file(path):
+    with open(path, "rb") as f:
+        data = f.read()
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise UnicodeDecodeError(exc.encoding, exc.object, exc.start, exc.end, f"{exc.reason}. read requires UTF-8 text files; use view for extracted content.") from exc
+
+
+def _directory_pattern_search(path, pattern, max_tokens=8000, pattern_context_lines=10, regex=True):
+    pattern_text = str(pattern)
+    parts = []
+    skipped = 0
+    for file_path in _iter_directory_files(path):
+        try:
+            text = _read_utf8_text_file(file_path)
+        except UnicodeDecodeError:
+            skipped += 1
+            continue
+        matches = pattern_line_numbers(text, pattern_text, regex_pattern=regex)
+        if not matches:
+            continue
+        snippet = _numbered_snippets_for_matches(text, matches, context_lines=pattern_context_lines)
+        rel_path = os.path.relpath(file_path, path)
+        parts.append(f"--- file: {rel_path} ---\n{snippet}")
+    if not parts:
+        result = f"No matches for pattern: {pattern_text!r}"
+    else:
+        result = "\n\n".join(parts)
+        if skipped:
+            result += f"\n\n[Skipped {skipped} non-UTF-8 file(s)]"
+    if max_tokens > 0:
+        result = truncate(result, max_tokens=max_tokens, start_line=1)
+    return result
+
+
+def read_document_content(source, start_at_line=1, end_at_line=None, max_tokens=8000, pattern=None, pattern_context_lines=10, regex=True):
+    """Read local UTF-8 files, list directories, or recursively search directories by pattern."""
     if not isinstance(source, (str, os.PathLike)):
-        raise TypeError("read only accepts a local file path. Use view for objects or extracted document content.")
+        raise TypeError("read only accepts a local file or directory path. Use view for objects or extracted document content.")
     path = os.fspath(source)
     if path.startswith(("http://", "https://")):
-        raise ValueError("read only accepts local UTF-8 text files. Use view for URLs.")
+        raise ValueError("read only accepts local UTF-8 files or directories. Use view for URLs.")
     if os.path.isdir(path):
-        raise ValueError("read only accepts local UTF-8 text files. Use view for directories.")
+        if pattern:
+            return _directory_pattern_search(path, pattern, max_tokens=max_tokens, pattern_context_lines=pattern_context_lines, regex=regex)
+        return _render_directory_tree(path, max_tokens=max_tokens)
     if not os.path.isfile(path):
         raise FileNotFoundError(f"File not found: {path}")
-    with open(path, "rb") as f:
-        data = f.read()
-    try:
-        text = data.decode("utf-8")
-    except UnicodeDecodeError as exc:
-        raise UnicodeDecodeError(exc.encoding, exc.object, exc.start, exc.end, f"{exc.reason}. read requires UTF-8 text files; use view for extracted content.") from exc
-    return _render_numbered_read_text(text, start_at_line=start_at_line, max_tokens=max_tokens, pattern=pattern, pattern_context_lines=pattern_context_lines, regex=regex)
+    text = _read_utf8_text_file(path)
+    return _render_numbered_read_text(text, start_at_line=start_at_line, end_at_line=end_at_line, max_tokens=max_tokens, pattern=pattern, pattern_context_lines=pattern_context_lines, regex=regex)
 
 
 def view_document_content(source, start_at_line=1, max_tokens=8000, search_query=None, search_context_lines=10):

codex_agent_framework-0.1.27/codex_agent/version.py

@@ -0,0 +1 @@
+__version__ = "0.1.27"