nanoPyCodeAgent 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

nanopycodeagent/agent.py

@@ -2,8 +2,9 @@
 
 Run the program, type a message, and Agent replies. The full conversation is
 kept in memory so each turn has context. The model can call a ``read`` tool
-to view files and a ``bash`` tool to run shell commands; every call and its
-output are echoed to the terminal as they happen. Type ``/exit`` to quit.
+to view files, a ``write`` tool to create or overwrite them, and a ``bash``
+tool to run shell commands; every call and its output are echoed to the
+terminal as they happen. Type ``/exit`` to quit.
 
 The loop handles only the happy path: anything unexpected — a network error,
 a Ctrl-C mid-turn — crashes the session, and restarting it is the recovery.
@@ -14,13 +15,24 @@ preserved at the ``hardened-agent-loop`` tag.
 import os
 from importlib.metadata import PackageNotFoundError, version
 
+try:
+    # Importing readline routes input() through a line editor that redraws the
+    # whole line. Without it the tty erases one column per backspace, which
+    # leaves half of a double-width character (CJK, emoji) on screen even
+    # though it is gone from the buffer. Editing and history come along for
+    # the ride. Not available on every platform, so the import is optional.
+    import readline  # noqa: F401
+except ImportError:  # pragma: no cover - platform without readline
+    pass
+
 import anthropic
 from anthropic.types import MessageParam, ToolResultBlockParam, ToolUseBlock
 
 from .bash_tool import BASH_TOOL, run_bash
 from .read_tool import READ_TOOL, run_read
 from .settings import load_settings_env
-from .terminal import print_tool
+from .terminal import Spinner, print_tool_output, print_tool_use
+from .write_tool import WRITE_TOOL, content_preview, run_write
 
 # The model used when ANTHROPIC_MODEL is set in neither the environment nor
 # the config file.
@@ -28,13 +40,14 @@ DEFAULT_MODEL = "claude-sonnet-4-6"
 MAX_TOKENS = 8192
 SYSTEM_PROMPT = (
     "You are nanoPyCodeAgent, a concise and helpful coding assistant. "
-    "Prefer the read tool for viewing files. Use the bash tool to run "
-    "commands, search with grep, and complete tasks that need real command "
-    "output instead of guessing."
+    "Prefer the read tool for viewing files and the write tool for creating "
+    "files or rewriting them whole. Use the bash tool to run commands, "
+    "search with grep, and complete tasks that need real command output "
+    "instead of guessing."
 )
 
 # Every tool offered to the model on each request.
-TOOLS = [READ_TOOL, BASH_TOOL]
+TOOLS = [READ_TOOL, WRITE_TOOL, BASH_TOOL]
 
 
 def _package_version() -> str:
@@ -55,17 +68,25 @@ def _run_one_tool(block: ToolUseBlock) -> ToolResultBlockParam:
     """Execute one ``tool_use`` block, echoing the call and its output."""
     if block.name == "read":
         path = block.input["path"]
-        print_tool(f"[read] {path}")
+        print_tool_use(f"[read] {path}")
         output, is_error = run_read(
             path,
             offset=block.input.get("offset", 1),
             limit=block.input.get("limit"),
         )
+    elif block.name == "write":
+        path = block.input["path"]
+        content = block.input["content"]
+        # The echo folds the content: the terminal shows where the write
+        # goes and how it starts, not hundreds of lines.
+        print_tool_use(f"[write] {path}\n{content_preview(content)}")
+        output, is_error = run_write(path, content)
     else:  # bash — the only other tool offered
         command = block.input["command"]
-        print_tool(f"[bash]$ {command}")
-        output, is_error = run_bash(command)
-    print_tool(output)
+        print_tool_use(f"[bash]$ {command}")
+        with Spinner("Running..."):
+            output, is_error = run_bash(command)
+    print_tool_output(output)
     return {
         "type": "tool_result",
         "tool_use_id": block.id,
@@ -105,7 +126,11 @@ def run() -> None:
     messages: list[MessageParam] = []
     while True:
         try:
-            user_input = input("\nYou> ").strip()
+            # The blank line before the prompt is printed separately: readline
+            # measures the prompt to place the cursor, and a newline inside it
+            # throws that off.
+            print()
+            user_input = input("You> ").strip()
         except (EOFError, KeyboardInterrupt):
             print()
             break
@@ -118,10 +143,13 @@ def run() -> None:
         # The model may ask to run tools; keep streaming replies and feeding
         # results back until it finishes a reply without tool calls.
         while True:
-            print("\nAgent> ", end="", flush=True)
+            # A spinner marks the wait for the reply; the first streamed
+            # token replaces it with the Agent> prompt. A tool-only reply
+            # streams no text, so the prompt is skipped for it entirely.
+            replied = False
             # Stream the reply so text shows up as it is generated, then grab
             # the accumulated message for the conversation history.
-            with client.messages.stream(
+            with Spinner() as spinner, client.messages.stream(
                 model=model,
                 max_tokens=MAX_TOKENS,
                 system=SYSTEM_PROMPT,
@@ -129,9 +157,14 @@ def run() -> None:
                 messages=messages,
             ) as stream:
                 for text in stream.text_stream:
+                    if not replied:
+                        spinner.stop()
+                        print("\nAgent> ", end="", flush=True)
+                        replied = True
                     print(text, end="", flush=True)
                 message = stream.get_final_message()
-            print()
+            if replied:
+                print()
 
             messages.append({"role": "assistant", "content": message.content})
             if message.stop_reason != "tool_use":

nanopycodeagent/terminal.py

@@ -1,11 +1,17 @@
-"""Background shading for tool activity in the terminal."""
+"""Terminal presentation: tool-activity shading and a wait spinner."""
 
+import itertools
 import os
 import sys
+import threading
 
-# Dark gray from the 256-color palette, so echoed commands and their output
-# read apart from the user's prompts and the model's prose.
-_TOOL_BG = "\x1b[48;5;236m"
+# Grays from the 256-color palette. The echoed call sits on a lighter shade
+# than its output so the two read apart at a glance, and both read apart
+# from the user's prompts and the model's prose. The output keeps the
+# darker shade: it stays subdued while remaining visible on common dark
+# terminal backgrounds.
+_USE_BG = "\x1b[48;5;238m"
+_OUTPUT_BG = "\x1b[48;5;236m"
 _RESET = "\x1b[0m"
 
 
@@ -14,8 +20,8 @@ def _use_color() -> bool:
     return sys.stdout.isatty() and not os.environ.get("NO_COLOR")
 
 
-def print_tool(text: str) -> None:
-    """Print tool activity (an echoed command or its output) shaded.
+def _print_shaded(text: str, bg: str) -> None:
+    """Print ``text`` with every line shaded in ``bg``.
 
     Each line carries its own set-background / erase-to-EOL / reset, so the
     shading spans the full terminal width and never leaks past a line
@@ -23,7 +29,68 @@ def print_tool(text: str) -> None:
     disrupt the shading — a cosmetic trade for staying simple.
     """
     if _use_color():
-        text = "\n".join(
-            f"{_TOOL_BG}{line}\x1b[K{_RESET}" for line in text.split("\n")
-        )
+        text = "\n".join(f"{bg}{line}\x1b[K{_RESET}" for line in text.split("\n"))
     print(text, flush=True)
+
+
+def print_tool_use(text: str) -> None:
+    """Print an echoed tool call (e.g. ``[bash]$ ls``) on the lighter shade."""
+    _print_shaded(text, _USE_BG)
+
+
+def print_tool_output(text: str) -> None:
+    """Print a tool's output on the darker shade."""
+    _print_shaded(text, _OUTPUT_BG)
+
+
+# The classic braille "dots" spinner: one glyph per frame, different dots
+# raised in each, cycled fast enough to read as rotation.
+_SPINNER_FRAMES = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
+_SPINNER_INTERVAL = 0.08
+
+
+class Spinner:
+    """Animate ``⠋ Working...`` in place on one line until stopped.
+
+    A background thread redraws the line with carriage returns while the
+    caller blocks on slow work, and erases it on stop, so the spinner
+    leaves no trace in the transcript. When stdout is not a terminal (or
+    NO_COLOR is set) nothing is printed at all. ``stop`` is idempotent:
+    stopping early — say, when the first streamed token arrives — and
+    again on context-manager exit is fine.
+    """
+
+    def __init__(self, text: str = "Working..."):
+        self._text = text
+        self._stop_event = threading.Event()
+        self._thread: threading.Thread | None = None
+
+    def start(self) -> None:
+        if not _use_color():
+            return
+        self._thread = threading.Thread(target=self._spin, daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        if self._thread is None:
+            return
+        self._stop_event.set()
+        self._thread.join()
+
+    def __enter__(self) -> "Spinner":
+        self.start()
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.stop()
+
+    def _spin(self) -> None:
+        # Draw a frame, then sleep on the stop event so stop() interrupts
+        # the pause instead of waiting out the full interval.
+        for frame in itertools.cycle(_SPINNER_FRAMES):
+            sys.stdout.write(f"\r{frame} {self._text}")
+            sys.stdout.flush()
+            if self._stop_event.wait(_SPINNER_INTERVAL):
+                break
+        sys.stdout.write("\r\x1b[K")  # erase the spinner line
+        sys.stdout.flush()

nanopycodeagent/write_tool.py

@@ -0,0 +1,153 @@
+"""The ``write`` tool: its definition and its execution.
+
+Each call writes a whole UTF-8 text file from a structured
+``{path, content}`` input: the content lands on disk as data, never
+passing through shell expansion, heredoc delimiters or quoting, which is
+what makes a heredoc silently corrupt a file while exiting 0.
+"""
+
+import shlex
+from pathlib import Path
+
+from anthropic.types import ToolParam
+
+# The terminal echo folds the content to this many lines, and any one line
+# to this many characters, so a large write does not flood the terminal the
+# way the heredoc it replaces would. The full content reaches the file (and
+# the model already holds it); only the echo is folded.
+WRITE_PREVIEW_LINES = 10
+WRITE_PREVIEW_LINE_CHARS = 200
+
+WRITE_TOOL: ToolParam = {
+    "name": "write",
+    "description": (
+        "Write a UTF-8 text file: create it if missing (parent directories "
+        "included), or replace its entire content if it exists. The result "
+        "says which of the two happened. Use this for new files and "
+        "whole-file rewrites instead of shell redirection or heredocs; use "
+        "bash to append or to transform many files at once. The write is a "
+        "plain overwrite — last writer wins, with no check that the file "
+        "was read first or is unchanged since."
+    ),
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "path": {
+                "type": "string",
+                "description": (
+                    "Path to the file, absolute or relative to the agent's "
+                    "working directory. A leading ~ is expanded."
+                ),
+            },
+            "content": {
+                "type": "string",
+                "description": (
+                    "The complete file content, written exactly as given — "
+                    "no newline or whitespace normalization."
+                ),
+            },
+        },
+        "required": ["path", "content"],
+    },
+}
+
+
+def _logical_lines(content: str) -> list[str]:
+    """Split ``content`` into the lines read would number.
+
+    The split is on ``\\n`` alone, and the newline ending the last line
+    starts no new one — so ``"a\\nb\\n"`` is two lines, not three.
+    """
+    lines = content.split("\n")
+    if lines and lines[-1] == "":
+        lines.pop()
+    return lines
+
+
+def content_preview(content: str) -> str:
+    """Fold ``content`` for the terminal echo of a write call.
+
+    The first few lines are shown, over-long lines are cut short, and a
+    closing note counts the hidden lines, so the echo reads as "where the
+    write goes and how it starts" rather than the whole file.
+    """
+    lines = _logical_lines(content)
+    if not lines:
+        return "(empty)"
+    shown = [
+        line
+        if len(line) <= WRITE_PREVIEW_LINE_CHARS
+        else line[:WRITE_PREVIEW_LINE_CHARS] + "..."
+        for line in lines[:WRITE_PREVIEW_LINES]
+    ]
+    hidden = len(lines) - len(shown)
+    if hidden > 0:
+        shown.append(f"... (+{hidden} more lines)")
+    return "\n".join(shown)
+
+
+def run_write(path_str: str, content: str) -> tuple[str, bool]:
+    """Write ``content`` to the file whole and return ``(output, is_error)``.
+
+    The file is created when missing — parent directories included — and
+    replaced entirely when it exists; the result names which of the two
+    happened, plus the byte and line counts the model can check its intent
+    against. ``is_error`` is true when the target is a directory or any
+    other non-regular file, or when the write itself fails. A FIFO is
+    refused because opening one for writing blocks until a reader appears,
+    with no timeout here to escape that; a device file is refused because
+    writing to one changes the machine, not the workspace. A symlink to a
+    regular file is followed: the write lands in its target.
+
+    Content is encoded as UTF-8 and written as given — no newline or
+    whitespace normalization, no trailing-newline fix-up. The write is a
+    plain overwrite: nothing checks that the file was read first or is
+    unchanged since, and there is no atomic-replace step. In this agent's
+    single-threaded loop those guards would only be pretend safety, so the
+    semantics are stated plainly instead: last writer wins.
+    """
+    path = Path(path_str).expanduser()
+    if path.is_dir():
+        return (
+            f"[{path_str} is a directory, not a file; give a path to a file "
+            f"inside it]",
+            True,
+        )
+    existed = path.exists()
+    if existed and not path.is_file():
+        # Opening a FIFO for writing blocks until a reader shows up, and a
+        # device file must not be overwritten as if it were text. Same
+        # check as read's, from the writing side.
+        return (
+            f"[{path_str} is not a regular file; write refuses FIFOs and "
+            f"device files — if it really is the target, write it with "
+            f"bash, whose timeout escapes a blocked open]",
+            True,
+        )
+    try:
+        data = content.encode("utf-8")
+    except UnicodeEncodeError as exc:
+        # A lone surrogate cannot reach disk as UTF-8; writing a replacement
+        # instead would corrupt the file silently — the heredoc failure mode
+        # this tool exists to remove.
+        return f"[content is not encodable as UTF-8: {exc}; resend it]", True
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(data)
+    except OSError as exc:
+        # ``exc`` names the OS reason — permission denied, a file sitting
+        # in the parent path, a full disk. The hint points at the usual
+        # first suspect, following read's bash-hint conventions: expanded
+        # path, quoted, behind -- so it cannot read as an option.
+        return (
+            f"[cannot write {path_str}: {exc}; inspect the parent with "
+            f"bash, e.g. ls -ld -- {shlex.quote(str(path.parent))}]",
+            True,
+        )
+
+    verb = "overwrote" if existed else "created"
+    return (
+        f"[{verb} {path_str}: {len(data)} bytes, "
+        f"{len(_logical_lines(content))} lines]",
+        False,
+    )

{nanopycodeagent-0.5.0.dist-info → nanopycodeagent-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: nanoPyCodeAgent
-Version: 0.5.0
+Version: 0.6.0
 Summary: A nano code agent built from scratch in pure Python.
 Project-URL: Homepage, https://github.com/minixalpha/nanoPyCodeAgent
 Project-URL: Repository, https://github.com/minixalpha/nanoPyCodeAgent

nanopycodeagent-0.6.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+nanopycodeagent/__init__.py,sha256=pYFCw7WNkZsGXbqNLkXituX4iBy86RJ4LKKAr78XwM8,70
+nanopycodeagent/agent.py,sha256=4HC6ZXm3zMKso1-VS9VYH4bIrFcR33U_gIbBcrfsnX4,7219
+nanopycodeagent/bash_tool.py,sha256=fTaGz4gfFpBykBaw4jyYeKgibOKrIfJMKqBYoBEE4og,2958
+nanopycodeagent/read_tool.py,sha256=4AddoZ8uHGzPNKMFagrskjmOWv5nhpk3oJbG8eBBgcM,7374
+nanopycodeagent/settings.py,sha256=Tn9si3uRTt2IioP4GTYJGuCYVBCyTTJErq9FmuTs0pw,1296
+nanopycodeagent/terminal.py,sha256=jSe0CXayttR25RBt_qmCsFURVDW0uha391hBKgW3XwQ,3340
+nanopycodeagent/write_tool.py,sha256=dnHoNGT6HpQvJXQvxXPQcS4yBTtfwCkSV4hLAn9_YgY,6168
+nanopycodeagent-0.6.0.dist-info/METADATA,sha256=x0dali3scKdug_qwwMy2XzPxNpZh3pPv5oIwbPD9VLg,3028
+nanopycodeagent-0.6.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+nanopycodeagent-0.6.0.dist-info/entry_points.txt,sha256=4gU7YNzQaf2RKlOdfebOWYNYIUk2LDoyhu3G4Vgole8,57
+nanopycodeagent-0.6.0.dist-info/licenses/LICENSE,sha256=g24TppoiLdeF_1_-Y7H2H_eOavKseWA5utuK83Vq1sA,1067
+nanopycodeagent-0.6.0.dist-info/RECORD,,

{nanopycodeagent-0.5.0.dist-info → nanopycodeagent-0.6.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.31.0
+Generator: hatchling 1.32.0
 Root-Is-Purelib: true
 Tag: py3-none-any

nanopycodeagent-0.5.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-nanopycodeagent/__init__.py,sha256=pYFCw7WNkZsGXbqNLkXituX4iBy86RJ4LKKAr78XwM8,70
-nanopycodeagent/agent.py,sha256=AAOnt1q-6FQgcAOODxHv2iM0UwlbqSnPD8kmtPGPo68,5452
-nanopycodeagent/bash_tool.py,sha256=fTaGz4gfFpBykBaw4jyYeKgibOKrIfJMKqBYoBEE4og,2958
-nanopycodeagent/read_tool.py,sha256=4AddoZ8uHGzPNKMFagrskjmOWv5nhpk3oJbG8eBBgcM,7374
-nanopycodeagent/settings.py,sha256=Tn9si3uRTt2IioP4GTYJGuCYVBCyTTJErq9FmuTs0pw,1296
-nanopycodeagent/terminal.py,sha256=ZkRvKbGQGiu7SI8Pe40THVYR1-4CMBEMVEgAH8h8Ytw,995
-nanopycodeagent-0.5.0.dist-info/METADATA,sha256=Bep9XESPN7PJ34J9zPvh4YtXdfQ1h2Yeh1Ht5uZdG9E,3028
-nanopycodeagent-0.5.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-nanopycodeagent-0.5.0.dist-info/entry_points.txt,sha256=4gU7YNzQaf2RKlOdfebOWYNYIUk2LDoyhu3G4Vgole8,57
-nanopycodeagent-0.5.0.dist-info/licenses/LICENSE,sha256=g24TppoiLdeF_1_-Y7H2H_eOavKseWA5utuK83Vq1sA,1067
-nanopycodeagent-0.5.0.dist-info/RECORD,,