nanoPyCodeAgent 0.2.0__tar.gz → 0.4.0__tar.gz

{nanopycodeagent-0.2.0 → nanopycodeagent-0.4.0}/.agents/skills/release/SKILL.md

@@ -50,12 +50,18 @@ Read the entries under `## [Unreleased]` and propose the next semver `X.Y.Z`:
 **0.x caveat:** on `0.y.z` a minor may still contain breaking changes; treat the
 proposal as a suggestion. The maintainer makes the final call at the gate (step 5).
 
-### 4. Cut the changelog
+### 4. Cut the changelog and date the dev notes
 In `<series>`:
 - rename `## [Unreleased]` to `## [X.Y.Z] - <today YYYY-MM-DD>`, keeping its entries;
 - add a fresh empty `## [Unreleased]` section above it.
 
-Touch no other file — dev notes and README were synced per-PR by `land-pr`.
+In `docs/dev_notes/zh-CN/<series>.md` and `docs/dev_notes/en/<series>.md`,
+replace the `YYYY.MM.DD` placeholder in the `## X.Y.Z - YYYY.MM.DD` heading
+with today's date (dot-separated). Skip if the dev notes have no section for
+this version.
+
+Touch no other file — dev notes content and README were synced per-PR by
+`land-pr`.
 
 ### 5. ⛔ Confirmation gate (mandatory)
 Present to the maintainer: the proposed **version** `X.Y.Z` and the **changelog

{nanopycodeagent-0.2.0 → nanopycodeagent-0.4.0}/.agents/skills/release/scripts/verify-release.sh

@@ -60,9 +60,14 @@ grep -q '\.tar\.gz$' <<<"$assets" || fail "Release ${tag} missing an sdist (.tar
 printf 'OK: GitHub Release %s has wheel + sdist\n' "$tag"
 
 # 3. uvx smoke test (official index, with retries) ------------------------
+# --default-index (not --index): --index only *adds* an index, and uv's
+# first-index strategy would stop at a locally configured mirror that has the
+# package but not the new version yet. --refresh: uv's cached simple-index
+# metadata can be stale right after a publish. </dev/null: the entry point
+# reads stdin; EOF makes it exit immediately instead of hanging interactively.
 log "Smoke-testing uvx ${PACKAGE}@${version}"
 deadline=$(( $(date +%s) + POLL_TIMEOUT ))
-until uvx --index "$PYPI_INDEX" --from "${PACKAGE}@${version}" "$PACKAGE" >/dev/null 2>&1; do
+until uvx --refresh --default-index "$PYPI_INDEX" --from "${PACKAGE}@${version}" "$PACKAGE" >/dev/null 2>&1 </dev/null; do
   (( $(date +%s) >= deadline )) && fail "uvx smoke test failed for ${PACKAGE}@${version} after ${POLL_TIMEOUT}s"
   printf 'uvx not ready (index propagation?); retrying in %ss...\n' "$POLL_INTERVAL"; sleep "$POLL_INTERVAL"
 done

{nanopycodeagent-0.2.0 → nanopycodeagent-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nanoPyCodeAgent
-Version: 0.2.0
+Version: 0.4.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.4.0/docs/changelogs/0.3.x.md

@@ -0,0 +1,22 @@
+# Changelog — 0.3.x
+
+All notable changes in the **0.3.x** release series are documented here.
+
+## [Unreleased]
+
+## [0.3.0] - 2026-07-10
+
+### Changed
+- Agent replies now stream to the terminal as they are generated, instead of appearing all at once after the full response is ready.
+
+<!--
+When cutting a release, copy the relevant items from [Unreleased] into a new
+version section above it, e.g.:
+
+## [0.3.0] - YYYY-MM-DD
+
+### Added
+### Changed
+### Fixed
+### Removed
+-->

nanopycodeagent-0.4.0/docs/changelogs/0.4.x.md

@@ -0,0 +1,34 @@
+# Changelog — 0.4.x
+
+All notable changes in the **0.4.x** release series are documented here.
+
+## [Unreleased]
+
+## [0.4.0] - 2026-07-14
+
+### Added
+- A `bash` tool with a tool-use loop: the model can now run shell commands and
+  read their output. Each command and its result are echoed to the terminal as
+  they happen; long output is truncated and hung commands are killed after a
+  timeout.
+- Tool commands and output are shaded with a background color so they read
+  apart from the agent's own text (skipped when stdout is not a terminal or
+  `NO_COLOR` is set).
+
+### Changed
+- The agent loop now handles only the happy path: anything unexpected — a
+  network error, a Ctrl-C mid-turn, a malformed config file — crashes the
+  session, and restarting it is the recovery. The previous hardened variant is
+  preserved at the `hardened-agent-loop` tag.
+
+<!--
+When cutting a release, copy the relevant items from [Unreleased] into a new
+version section above it, e.g.:
+
+## [0.4.0] - YYYY-MM-DD
+
+### Added
+### Changed
+### Fixed
+### Removed
+-->

{nanopycodeagent-0.2.0 → nanopycodeagent-0.4.0}/docs/dev_notes/README.md

@@ -11,3 +11,8 @@ Notes are bilingual, split by language:
 These are free-form notes — insights, takeaways, and design decisions gathered
 while developing each series, with no fixed structure. User-facing changes live
 in [`../changelogs/`](../changelogs/).
+
+The date in a `## X.Y.Z - YYYY.MM.DD` section heading is the **release date**
+of that version (the same date as the git tag and the changelog entry). While
+the version is unreleased, keep the literal `YYYY.MM.DD` placeholder — it is
+filled in by the release process.

{nanopycodeagent-0.2.0 → nanopycodeagent-0.4.0}/docs/dev_notes/en/0.2.x.md

@@ -2,7 +2,7 @@
 
 > Generated from the Chinese source [`../zh-CN/0.2.x.md`](../zh-CN/0.2.x.md). Do not edit by hand.
 
-## 0.2.0 - 2026.06.29
+## 0.2.0 - 2026.07.09
 
 This release implements a minimally functional chatbot that holds a multi-turn conversation with the LLM through the [Messages](https://platform.claude.com/docs/en/api/python/messages/create) API.
 

nanopycodeagent-0.4.0/docs/dev_notes/en/0.3.x.md

@@ -0,0 +1,49 @@
+# Development Notes — 0.3.x
+
+> Generated from the Chinese source [`../zh-CN/0.3.x.md`](../zh-CN/0.3.x.md). Do not edit by hand.
+
+## 0.3.0 - 2026.07.10
+
+Without a TUI, testing was confusing whenever the output was long: with no streaming, it was easy to wonder whether the API call had failed. So this version switches to streaming output.
+
+I hesitated over whether switching to streaming would introduce unnecessary complexity when tool calling lands in the next version. I had Claude write a demo to find out — it doesn't look like it will: to handle tool calls you have to wait for `stream.get_final_message()` anyway. Streaming output is purely a display-layer concern, designed for user experience; the logic layer still does its processing after `get_final_message()`.
+
+I also learned what `stream.text_stream` is — having a code agent around is really convenient, no time wasted hunting through docs.
+
+
+> Layer 1: what travels over the network is an event stream (SSE)
+>
+> The API's streaming response is not plain text but a sequence of structured events:
+>
+> ```text
+> message_start → content_block_start → content_block_delta × N
+> → content_block_stop → message_delta → message_stop
+> ```
+>
+> Text, thinking, and tool-call arguments are all mixed into content_block_delta events, distinguished by delta.type (text_delta / input_json_delta / thinking_delta).
+>
+> Layer 2: the MessageStream returned by messages.stream() is a wrapper around this event stream
+>
+> It forwards events to you while quietly accumulating state internally — which is why get_final_message() can return the complete message at the end.
+>
+> Layer 3: text_stream is filter + map syntactic sugar over this event stream
+>
+> These two snippets are equivalent:
+>
+> ```python
+> # Convenient form
+> for text in stream.text_stream:
+>     print(text, end="", flush=True)
+>
+> # What it actually means, expanded
+> for event in stream:
+>     if event.type == "content_block_delta" and event.delta.type == "text_delta":
+>         print(event.delta.text, end="", flush=True)
+> ```
+>
+> It yields only the string contents of text_delta events; the other events (block boundaries, tool arguments, thinking deltas) are silently skipped — but not lost: they still flow through the internal accumulator, so after exhausting text_stream, get_final_message() still contains every tool_use block.
+>
+> Two key points:
+>
+> - It is a lazy generator: iterating it is what actually drives the network reads — no iteration, no download.
+> - `for event in stream` and `for text in stream.text_stream` consume the same underlying stream, so only one of them can be the main loop; the difference is one of perspective: "all events" vs "text only".

nanopycodeagent-0.4.0/docs/dev_notes/en/0.4.x.md

@@ -0,0 +1,68 @@
+# Development Notes — 0.4.x
+
+> Generated from the Chinese source [`../zh-CN/0.4.x.md`](../zh-CN/0.4.x.md). Do not edit by hand.
+
+## 0.4.0 - 2026.07.14
+
+### The bash tool
+
+This version adds tool use, starting with a single bash tool. The bash tool can do almost anything — powerful yet simple — and it makes a good base to gradually split other tools out of, which will make it easy to compare having more tools against having just the one bash tool.
+
+Also, with no test environment for the other systems, Linux is the only platform that can be fully tested. Mac's bash is probably fairly similar to Linux's?
+
+### Background color for tool output
+
+I tried giving tool output a background color so it stands apart from the agent's text output, similar to the pi code agent's implementation.
+
+Along the way I learned how changing the terminal background color actually works:
+
+```
+1. Terminal colors are "in-band control": styling is mixed into the data stream
+
+Between a program and the terminal there is only one byte stream — no separate
+styling channel. To change how things look, you insert control sequences
+starting with ESC (\x1b) into the stream. The \x1b[<params>m family is called
+SGR (Select Graphic Rendition); it changes the terminal's current "brush"
+state — every character printed afterwards is written into its screen cell
+with the current brush attributes, until the brush changes again. The byte
+stream for each output line is really:
+
+\x1b[48;5;236m  [bash]$ ls ...  \x1b[K   \x1b[0m  \n
+└─ set bg color ─┘ └── text ──┘ └erase to EOL┘ └reset┘
+
+2. 48;5;236: dark gray from the 256-color palette
+
+48;5;N means "background color = entry N of the 256-color palette". The
+palette has three segments: 0–15 basic colors, 16–231 the color cube, 232–255
+the grayscale ramp. Entry 236 is a dark gray (about #303030). Picking the
+grayscale ramp over the basic background colors 41–47 is deliberate: basic
+colors get remapped by the user's terminal theme and can be harsh on the eyes,
+while grays stay "just a bit lighter than the base color" under any theme —
+exactly right for visual layering.
+
+3. \x1b[K makes the color block fill the whole line
+
+Background color only applies to cells where characters were actually
+printed; the blank space at the end of a line keeps the default background,
+so the block hugs the text with a ragged right edge. \x1b[K (Erase in Line)
+erases from the cursor to the end of the line, and mainstream terminals
+implement BCE (Background Color Erase): erased cells are filled with the
+current background color. So emitting \x1b[K before resetting the brush
+amounts to "painting the rest of this line dark gray" — which is why the
+blocks in the screenshot are clean rectangles.
+```
+
+### From production hardening back to the core
+
+The implementation had come to feel somewhat complex: the edge-case handling was crowding out the core. Those edge cases matter in a production-grade application, but for now, as long as normal use is unaffected, they hardly seem necessary.
+
+With that in mind, I stripped out the production hardening wholesale and kept only the core flow. The design principle moves from "repair history and survive on error" to "crash on the unexpected, restart to recover":
+
+- **Agent loop**: the per-moment Ctrl-C history repair, the API-error rollback (`ran_tools` / `turn_start`), patching `tool_result`s for truncated replies, and the per-turn request budget (`MAX_REQUESTS_PER_TURN`) are all deleted; the loop handles only the happy path.
+- **bash tool**: switched to `subprocess.run`; temp-file capture, process-group kill, capped per-stream reads, and NUL protection are all removed. Known trades: a background child (`some_server &`) blocks until the timeout; the timeout kills bash itself, with no guarantee of killing the whole process tree; and text mode translates `\r` in output to `\n`.
+- **terminal**: only this version's new tool-output background shading remains; control-character stripping and the stdout encoding fallback are removed.
+- **settings**: happy path only — a missing file is normal, a corrupt file simply raises.
+
+What stays is what genuinely belongs to agent design itself: the tool_use / tool_result pairing protocol, output truncation (protecting the context window), the command timeout, and `is_error` meaning only tool failure (the exit code goes into the result text, so the model can tell a negative answer from a failed execution).
+
+The source drops from 544 lines to 262, with agent.py going from 250 to 116 — the main loop now fits on one screen. How each edge case was discovered is recorded in the git history; the hardened version before the trim is preserved under the `hardened-agent-loop` tag.

{nanopycodeagent-0.2.0 → nanopycodeagent-0.4.0}/docs/dev_notes/zh-CN/0.2.x.md

@@ -2,7 +2,7 @@
 
 > 本文件为**手写中文源文件**(source of truth);英文版 [`../en/0.2.x.md`](../en/0.2.x.md) 由其生成。
 
-## 0.2.0 - 2026.06.29
+## 0.2.0 - 2026.07.09
 
 这个版本实现了一个最小功能的 chatbot，使用 [Message](https://platform.claude.com/docs/en/api/python/messages/create) 接口，完成与 LLM 的多轮对话。
 

nanopycodeagent-0.4.0/docs/dev_notes/zh-CN/0.3.x.md

@@ -0,0 +1,49 @@
+# 开发笔记 — 0.3.x
+
+> 本文件为**手写中文源文件**(source of truth);英文版 [`../en/0.3.x.md`](../en/0.3.x.md) 由其生成。
+
+## 0.3.0 - 2026.07.10
+
+由于没做 TUI，测试时候，如果输出内容长，没有流式输出，就会令人困惑，觉得是不是调用失败了，因此这一版本改为流式输出。
+
+犹豫了一下改流式输出会不会在下一版本引入工具调用时，引起不必要的复杂性。让 claude 尝试写了个 demo，看起来不会，处理工具调用，反正也要调用 `stream.get_final_message()` 后才处理。流式输出，只是显示层，为用户体验而设计的。逻辑层还是需要 `get_final_message()` 后处理。
+
+另外，学习了 `stream.text_stream` 是什么，感觉有 code agent 真是方便，不用花时间找文档了。
+
+
+> 第一层：网络上传输的是事件流（SSE）
+>
+> API 的流式响应不是纯文本，而是一串结构化事件：
+>
+> ```text
+> message_start → content_block_start → content_block_delta × N
+> → content_block_stop → message_delta → message_stop
+> ```
+>
+> 文本、思考过程、工具调用参数，全都混在 content_block_delta 事件里，靠 delta.type（text_delta / input_json_delta / thinking_delta）区分。
+>
+> 第二层：messages.stream() 返回的 MessageStream 是这个事件流的包装器
+>
+> 它一边把事件转给你，一边在内部悄悄累积状态——这就是为什么最后能 get_final_message() 拿到完整消息。
+>
+> 第三层：text_stream 就是在这个事件流上做了 filter + map 的语法糖
+>
+> 这两段代码等价：
+>
+> ```python
+> # 便捷写法
+> for text in stream.text_stream:
+>     print(text, end="", flush=True)
+>
+> # 展开后的实际含义
+> for event in stream:
+>     if event.type == "content_block_delta" and event.delta.type == "text_delta":
+>         print(event.delta.text, end="", flush=True)
+> ```
+>
+> 它只产出 text_delta 的字符串内容，其余事件（块边界、工具参数、思考增量）被静默跳过——但没有丢，它们照样流经内部累积器，所以迭代完 text_stream 后 get_final_message() 里工具调用块一个不少。
+>
+> 两个要点：
+>
+> - 它是惰性生成器：迭代它才真正驱动网络读取，不迭代就不下载。
+> - for event in stream 和 for text in stream.text_stream 消费的是同一条流，只能选一个当主循环，是“看全部事件”还是“只看文本”的视角区别。

nanopycodeagent-0.4.0/docs/dev_notes/zh-CN/0.4.x.md

@@ -0,0 +1,49 @@
+# 开发笔记 — 0.4.x
+
+> 本文件为**手写中文源文件**(source of truth);英文版 [`../en/0.4.x.md`](../en/0.4.x.md) 由其生成。
+
+## 0.4.0 - 2026.07.14
+
+### bash 工具
+
+此版本增加 tool use 功能，首先增加一个 bash 工具，bash 工具几乎可以做任何事，功能强大又简单，可以以此为基础，再逐步拆分出其他工具，方便对比增加其他工具后与单一 bash 工具的区别。
+
+另外，由于其他系统无测试环境，能完全测试的只有 Linux。Mac 与 Linux 的 bash 可能比较类似？
+
+### 工具输出背景色
+
+尝试给工具输出增加背景颜色，这样方便与 agent 的文本输出有区分，类似 pi code agent 的实现。
+
+另外，学习了终端改背景色的原理：
+
+```
+1. 终端颜色是"带内控制"：样式混在数据流里
+
+程序和终端之间只有一条字节流，没有独立的样式通道。想改变显示效果，就往流里插入以 ESC（\x1b）开头的控制序列。\x1b[<参数>m 这一族叫 SGR（Select Graphic Rendition），它修改终端当前的"画笔"状态——之后打印的每个字符都带着当前画笔属性写进屏幕单元格，直到画笔再次被改。每行输出的字节流实际是：
+
+\x1b[48;5;236m  [bash]$ ls ...  \x1b[K   \x1b[0m  \n
+└─ 设背景色 ─┘  └── 文字 ──┘  └擦到行尾┘ └重置┘
+
+2. 48;5;236：256 色调色板里的深灰
+
+48;5;N 表示"背景色 = 256 色调色板第 N 号"。调色板分三段：0–15 基本色、16–231 色立方、232–255 灰阶梯。236 号是深灰（约 #303030）。选灰阶而不选 41–47 基本背景色，是因为基本色会被用户终端主题重映射、容易刺眼；灰阶在各种主题下都只是"比底色浅一点"，做层次区分正合适。
+
+3. \x1b[K 让色块铺满整行
+
+背景色只作用于实际打印了字符的单元格，行尾空白仍是默认背景，色块会紧贴文字、右缘参差。\x1b[K（Erase in Line）从光标擦到行尾，而主流终端实现了 BCE（Background Color Erase）：擦除时用当前背景色填充。所以在重置画笔前发一个 \x1b[K，等于"用深灰刷满本行剩余部分"——这就是截图里色块是整齐矩形的原因。
+```
+
+### 从生产级加固回到核心
+
+我觉得目前的实现，似乎有些复杂，边界条件的处理反而让核心内容不够明显。这些边界条件在生产级应用时有用，但目前如果不影响正常使用，似乎并无必要。
+
+基于这个想法，把生产级加固整体剥离，只保留核心流程。设计原则从「出错时修复历史并存活」改为「意外即崩溃，重启即恢复」：
+
+- **agent 循环**：Ctrl-C 分时刻的历史修复、API 错误回滚（`ran_tools` / `turn_start`）、截断回复补 `tool_result`、每轮请求预算（`MAX_REQUESTS_PER_TURN`）全部删除，循环只处理快乐路径。
+- **bash 工具**：改用 `subprocess.run`，临时文件捕获、进程组击杀、分流限量读、NUL 防护全部移除。已知取舍：后台子进程（`some_server &`）会阻塞到超时；超时只杀 bash 本体，不保证杀掉整棵进程树；文本模式会把输出中的 `\r` 转成 `\n`。
+- **terminal**：只保留本版新增的工具输出背景色，控制字符剥离和 stdout 编码兜底移除。
+- **settings**：只保留快乐路径 —— 文件缺失属正常，文件损坏直接抛异常。
+
+保留下来的是真正属于 agent 设计本身的部分：tool_use / tool_result 的配对协议、输出截断（保护上下文窗口）、命令超时、`is_error` 只表示工具失败（退出码写进正文，让模型区分「否定答案」和「执行失败」）。
+
+源码从 544 行降到 262 行，其中 agent.py 从 250 行降到 116 行，主循环可以一屏读完。这些边界条件的发现过程记录在 git 历史里；精简前的加固版打了 tag `hardened-agent-loop` 留档。

nanopycodeagent-0.4.0/src/nanopycodeagent/agent.py

@@ -0,0 +1,116 @@
+"""A minimal agent loop built on the Anthropic Python SDK.
+
+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 single ``bash``
+tool to run shell commands; every command 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.
+That trade keeps the core flow readable; the hardened variant it replaced is
+preserved at the ``hardened-agent-loop`` tag.
+"""
+
+import os
+
+import anthropic
+from anthropic.types import MessageParam, ToolResultBlockParam, ToolUseBlock
+
+from .bash_tool import BASH_TOOL, run_bash
+from .settings import load_settings_env
+from .terminal import print_tool
+
+# The model used when ANTHROPIC_MODEL is set in neither the environment nor
+# the config file.
+DEFAULT_MODEL = "claude-sonnet-4-6"
+MAX_TOKENS = 8192
+SYSTEM_PROMPT = (
+    "You are nanoPyCodeAgent, a concise and helpful coding assistant. "
+    "Use the bash tool to inspect files, run code, and complete tasks that "
+    "need real command output instead of guessing."
+)
+
+
+def _run_one_tool(block: ToolUseBlock) -> ToolResultBlockParam:
+    """Execute one ``tool_use`` block, echoing the command and its output."""
+    command = block.input["command"]
+    print_tool(f"[bash]$ {command}")
+    output, is_error = run_bash(command)
+    print_tool(output)
+    return {
+        "type": "tool_result",
+        "tool_use_id": block.id,
+        "content": output,
+        "is_error": is_error,
+    }
+
+
+def run() -> None:
+    """Start the read → ask → answer loop until the user types ``/exit``.
+
+    A reply may include bash tool calls; they are executed and their results
+    fed back to the model until it finishes the turn without tool use.
+    """
+    # Fill any unset ANTHROPIC_* keys from the config file (environment
+    # variables take precedence), then let the SDK read credentials from
+    # os.environ.
+    load_settings_env()
+    client = anthropic.Anthropic()
+    if client.api_key is None and client.auth_token is None:
+        print(
+            "No API credentials found. Set the ANTHROPIC_API_KEY environment variable."
+        )
+        print(
+            "If you use a third-party / proxy service, also set ANTHROPIC_BASE_URL "
+            "to point at its endpoint."
+        )
+        return
+
+    model = os.environ.get("ANTHROPIC_MODEL", "").strip() or DEFAULT_MODEL
+    print(f"nanoPyCodeAgent — model {model} (set ANTHROPIC_MODEL to override).")
+    print("Type a message to chat, or /exit to quit.")
+
+    messages: list[MessageParam] = []
+    while True:
+        try:
+            user_input = input("\nYou> ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            break
+        if not user_input:
+            continue
+        if user_input == "/exit":
+            break
+
+        messages.append({"role": "user", "content": user_input})
+        # 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)
+            # Stream the reply so text shows up as it is generated, then grab
+            # the accumulated message for the conversation history.
+            with client.messages.stream(
+                model=model,
+                max_tokens=MAX_TOKENS,
+                system=SYSTEM_PROMPT,
+                tools=[BASH_TOOL],
+                messages=messages,
+            ) as stream:
+                for text in stream.text_stream:
+                    print(text, end="", flush=True)
+                message = stream.get_final_message()
+            print()
+
+            messages.append({"role": "assistant", "content": message.content})
+            if message.stop_reason != "tool_use":
+                break
+            # Every tool_use block needs a matching tool_result in the next
+            # user message, or the API rejects the request.
+            results = [
+                _run_one_tool(block)
+                for block in message.content
+                if block.type == "tool_use"
+            ]
+            messages.append({"role": "user", "content": results})
+
+    print("Bye!")

nanopycodeagent-0.4.0/src/nanopycodeagent/bash_tool.py

@@ -0,0 +1,77 @@
+"""The ``bash`` tool: its definition and its execution.
+
+Each call runs a command with ``bash -c`` in a fresh shell and returns one
+result string: stdout, then labelled stderr, then the exit code when non-zero.
+"""
+
+import subprocess
+
+from anthropic.types import ToolParam
+
+# Guardrails for the bash tool: a hung command is killed after this many
+# seconds, and results are truncated so one command cannot flood the context.
+BASH_TIMEOUT_SECONDS = 120
+MAX_TOOL_OUTPUT_CHARS = 20_000
+
+BASH_TOOL: ToolParam = {
+    "name": "bash",
+    "description": (
+        "Run a command with `bash -c` on the user's machine and return its "
+        "output: stdout, then stderr (labelled), then the exit code when "
+        "non-zero. Each call is a fresh shell in the agent's working "
+        "directory, so environment variables and `cd` do not persist between "
+        "calls. Long output is truncated and long-running commands are killed "
+        "after a timeout."
+    ),
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "command": {
+                "type": "string",
+                "description": "The bash command to run.",
+            }
+        },
+        "required": ["command"],
+    },
+}
+
+
+def run_bash(command: str) -> tuple[str, bool]:
+    """Run ``command`` with ``bash -c`` and return ``(output, is_error)``.
+
+    ``is_error`` is true only when the tool itself failed — here, a timeout.
+    A command that ran to completion is a successful tool call whatever its
+    exit code: the code is reported in the output text, where the model can
+    tell a negative answer (``grep`` finding nothing) from a failure.
+    Non-UTF-8 output bytes are replaced rather than raising, and stdin is
+    ``/dev/null`` so a command that prompts sees EOF instead of eating the
+    user's keystrokes.
+
+    Known trades for simplicity: a background child inherits the output
+    pipes, so ``some_server &`` blocks until the timeout; the timeout kills
+    bash itself, not necessarily everything it forked; and text mode
+    translates ``\\r`` in output to ``\\n`` (universal newlines).
+    """
+    try:
+        process = subprocess.run(
+            ["bash", "-c", command],
+            capture_output=True,
+            text=True,
+            errors="replace",
+            stdin=subprocess.DEVNULL,
+            timeout=BASH_TIMEOUT_SECONDS,
+        )
+    except subprocess.TimeoutExpired:
+        return f"[command timed out after {BASH_TIMEOUT_SECONDS} seconds]", True
+
+    parts = []
+    if stdout := process.stdout.rstrip("\n"):
+        parts.append(stdout)
+    if stderr := process.stderr.rstrip("\n"):
+        parts.append("[stderr]\n" + stderr)
+    if process.returncode != 0:
+        parts.append(f"[exit code: {process.returncode}]")
+    output = "\n".join(parts) or "(no output)"
+    if len(output) > MAX_TOOL_OUTPUT_CHARS:
+        output = output[:MAX_TOOL_OUTPUT_CHARS] + "\n[... output truncated ...]"
+    return output, False

nanopycodeagent-0.4.0/src/nanopycodeagent/settings.py

@@ -0,0 +1,35 @@
+"""User-level configuration for nanoPyCodeAgent.
+
+The config file at ``~/.nanoPyCodeAgent/settings.json`` may carry an ``env``
+mapping that supplies ``ANTHROPIC_*`` values for keys that are not already set
+in the environment (environment variables win).
+"""
+
+import json
+import os
+from pathlib import Path
+
+SETTINGS_PATH = Path.home() / ".nanoPyCodeAgent" / "settings.json"
+
+
+def load_settings_env(path: Path | None = None) -> None:
+    """Apply the ``env`` mapping from the config file into ``os.environ``.
+
+    Only ``ANTHROPIC_*`` keys that are not already present are set, so
+    environment variables take precedence over the config file and unrelated
+    variables are never injected. Empty, whitespace-only, and non-string
+    values are skipped (the documented example ships the keys as empty-string
+    placeholders). A missing file is normal; a malformed one raises — fix or
+    delete it.
+    """
+    if path is None:
+        path = SETTINGS_PATH
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return
+    for key, value in json.loads(raw).get("env", {}).items():
+        if not key.startswith("ANTHROPIC_"):
+            continue
+        if isinstance(value, str) and value.strip():
+            os.environ.setdefault(key, value.strip())

nanopycodeagent-0.4.0/src/nanopycodeagent/terminal.py

@@ -0,0 +1,29 @@
+"""Background shading for tool activity in the terminal."""
+
+import os
+import sys
+
+# 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"
+_RESET = "\x1b[0m"
+
+
+def _use_color() -> bool:
+    """Whether to emit ANSI colors: a real terminal, and NO_COLOR unset."""
+    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.
+
+    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
+    boundary. Escape sequences inside ``text`` are printed as-is and may
+    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")
+        )
+    print(text, flush=True)

nanopycodeagent-0.4.0/tests/conftest.py

@@ -0,0 +1,31 @@
+"""Shared fixtures for the test suite."""
+
+import os
+
+import pytest
+
+from nanopycodeagent import settings
+
+_MANAGED_ENV = ("ANTHROPIC_API_KEY", "ANTHROPIC_BASE_URL", "ANTHROPIC_MODEL")
+
+
+@pytest.fixture(autouse=True)
+def _isolate_config(monkeypatch, tmp_path):
+    """Keep every test off the real config file and ambient ANTHROPIC_* vars.
+
+    ``settings.SETTINGS_PATH`` is redirected into an empty temp dir (so tests
+    never read the developer's ~/.nanoPyCodeAgent/settings.json), and the
+    managed env vars are cleared up front and restored afterwards —
+    ``load_settings_env`` writes to ``os.environ`` directly, which monkeypatch
+    would not roll back on its own.
+    """
+    monkeypatch.setattr(settings, "SETTINGS_PATH", tmp_path / "settings.json")
+    saved = {key: os.environ.pop(key, None) for key in _MANAGED_ENV}
+    try:
+        yield
+    finally:
+        for key, value in saved.items():
+            if value is None:
+                os.environ.pop(key, None)
+            else:
+                os.environ[key] = value