nanoPyCodeAgent 0.4.0__tar.gz → 0.5.0__tar.gz

{nanopycodeagent-0.4.0 → nanopycodeagent-0.5.0}/.gitignore

@@ -216,3 +216,5 @@ __marimo__/
 
 # Streamlit
 .streamlit/secrets.toml
+
+references/

nanopycodeagent-0.5.0/.ignore

@@ -0,0 +1 @@
+!references/

nanopycodeagent-0.5.0/.zed/debug.json

@@ -0,0 +1,20 @@
+[
+  {
+    "label": "nanoPyCodeAgent: CLI",
+    "adapter": "Debugpy",
+    "request": "launch",
+    "program": "$ZED_WORKTREE_ROOT/.venv/bin/nanoPyCodeAgent",
+    "cwd": "$ZED_WORKTREE_ROOT",
+    "console": "integratedTerminal",
+    "justMyCode": true
+  },
+  {
+    "label": "nanoPyCodeAgent: all tests",
+    "adapter": "Debugpy",
+    "request": "launch",
+    "module": "pytest",
+    "args": ["-q"],
+    "cwd": "$ZED_WORKTREE_ROOT",
+    "justMyCode": true
+  }
+]

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nanoPyCodeAgent
-Version: 0.4.0
+Version: 0.5.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.5.0/docs/changelogs/0.5.x.md

@@ -0,0 +1,35 @@
+# Changelog — 0.5.x
+
+All notable changes in the **0.5.x** release series are documented here.
+
+## [Unreleased]
+
+## [0.5.0] - 2026-07-29
+
+### Added
+- A dedicated `read` tool for viewing files: it returns the content with
+  1-based line numbers, `cat -n` style, and takes `offset`/`limit` to read a
+  window of a large file. Output is capped at 2000 lines and 50000 characters
+  per call, truncated only at line boundaries; a truncated result names the
+  range returned, the file's total line count, and the offset to continue
+  from. Files over 10 MB, binary files, and non-regular files (directories,
+  FIFOs, device files) are rejected, and every error message points at the
+  next action to take.
+
+### Changed
+- The startup banner now prints the installed package version, so it is clear
+  which version is running.
+- The system prompt now tells the model to prefer the `read` tool for viewing
+  files and to use `bash` for running commands and searching with `grep`.
+
+<!--
+When cutting a release, copy the relevant items from [Unreleased] into a new
+version section above it, e.g.:
+
+## [0.5.0] - YYYY-MM-DD
+
+### Added
+### Changed
+### Fixed
+### Removed
+-->

nanopycodeagent-0.5.0/docs/dev_notes/en/0.5.x.md

@@ -0,0 +1,57 @@
+# Development Notes — 0.5.x
+
+> Generated from the Chinese source [`../zh-CN/0.5.x.md`](../zh-CN/0.5.x.md). Do not edit by hand.
+
+## 0.5.0 - 2026.07.29
+
+### Printing the version
+
+When the tool starts up without printing its version, I sometimes cannot tell which version I am actually running. So let's build that first.
+
+### Built-in tools in common code agents
+
+For a survey of the built-in tools of mainstream code agents, see [Built-in Tools in Common Code Agents](../../research/agent_tools.md) (Chinese).
+
+### Designing the built-in tools
+
+As the survey shows, beyond the core file/command tools that something like pi offers, the other agents have grown a large number of tools around subagent orchestration, task management, scheduling, user interaction, and so on. For our nano code agent, though, let's start expanding from the most basic category of all: file operations.
+
+#### The read tool
+
+We also surveyed the [read tool](../../research/read_tool.md) (Chinese): apart from codex, every code agent has a dedicated read tool. pi and opencode are model-agnostic, and you can see it in their read tools — their limits are line counts and file sizes, with no token limit. The other, model-specific code agents all have token limits; presumably because they only support their own vendor's models, where tokens are easier to count?
+
+Functionally, read and bash both seem able to satisfy the need to read a file. Even accounting for files that may exceed a size limit, bash can still read them fine. Take codex: in actual testing, whatever the size of the file, it always starts with a `sed -n '1,260p' foo.md`, and then, if it finds there is more, it may follow up with `wc -l foo.md && sed -n '1,260p' foo.md` — reading chunk by chunk, which looks a lot like the `limit` of a dedicated read tool. But I'm not sure whether, for any given model, reading files is better done with a dedicated tool or with `bash`.
+
+Another advantage of the read tool is that it makes it easy to constrain the agent to read-only operations, whereas bash is less directly controllable at the tool layer — which means control has to happen somewhere else, in a sandbox for instance. While testing the programmatic APIs of claude code, pi, and codex, I found that claude code and pi only need to be configured to use the read tool to be restricted to read-only operations, while codex needs a sandbox (`codex --sandbox read_only`).
+
+OpenAI's 2024 paper [SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering](https://arxiv.org/abs/2405.15793) argues that designing a dedicated tool set works better than using bash alone. But that is 2024 work, and models are certainly more capable now, so I don't know whether plain bash is in fact better (codex reads files with bash itself). We can't verify any of this for now, though — we probably need our set of basic tools to be a bit more complete before it can be tested. For the moment we can start by implementing basic tool capabilities similar to pi's.
+
+Here is what read implements today:
+
+**Interface**
+
+- **Parameters**: `path` (required, absolute or relative, `~` is expanded), `offset` (which line to start from, 1-based, default 1), `limit` (how many lines to return at most; omit it to read up to the line cap, and larger values are clamped to it). The line cap is interpolated into the schema description straight from the constant, because `limit` is the parameter the model can actively control — let it pick the right window size in one shot, instead of passing 5000, being silently cut to 2000, and only realizing after the fact from the truncation hint. The character cap, by contrast, is not mentioned in `limit`'s description: the model has no corresponding parameter to tune, so knowing the number would not change how it calls the tool; when it is hit, the runtime truncation hint and error messages explain it more effectively.
+- **Output format**: `cat -n` style, with a 1-based line number in front of every line (width 6 plus a tab), so it looks just like `cat -n` in bash and the model can cite line numbers directly.
+
+**Caps and truncation**
+
+- **Two output caps**: at most 2000 lines and 50000 characters per call, truncating at whichever is hit first, and **only at line boundaries** — a line is never cut in half. This way a single file cannot flood the context in one go.
+- **Continuation hint**: when the window stops short of the end of the file, the output ends with `[showing lines a-b of N; continue with offset=x]`, telling the model both the total line count and where to resume next time, so it doesn't need another `wc -l`.
+
+**Handling file content**
+
+- **Encoding**: decoded as UTF-8, with invalid bytes falling back to the replacement character (`errors="replace"`), matching the bash tool's tolerance.
+- **Splitting lines**: on `\n` alone, not with `splitlines()` — that one also breaks on `\x0c`, `\x0b`, `\x85` and U+2028, which puts the line numbers out of step with `sed`, `grep -n` and the editor; and the over-long-line error hands over exactly a `sed -n 'Np'`, which would then slice the wrong line. A trailing `\r` is dropped, so CRLF files read like LF ones.
+- **Binary rejection**: a `\x00` in the first 8KB marks the file as binary and it is rejected, to avoid stuffing garbage into the context.
+
+**Error handling**
+
+- **One return convention**: every error path returns `is_error=True`, covering `offset < 1`, `limit < 1`, a missing file, a path that is a directory or any other non-regular file, other `OSError`s, binary files, an `offset` past the total line count, and a single line over the character cap. An empty file returns `(empty file)`.
+- **Only regular files are opened**: a FIFO blocks until something writes to it, and a device file like `/dev/zero` never ends — and read has no timeout to escape that the way the bash tool does, so the type check has to come before the read.
+- **Error messages name the next action**: the message says not just "what went wrong" but "what to do next". For example, when `offset` is past the end of the file, it reports how many lines the file actually has; when a line is longer than the character cap, it hands over a bash command for the model to slice it itself (`sed -n 'Np' -- file | cut -c 1-2000`). That command is meant to be run, so the path in it is expanded first (quoting would stop the shell from expanding `~` itself), then escaped with `shlex.quote` and placed behind `--` — a space, a `$(...)` or a leading `-` in a filename should never get to reshape the command.
+
+**Division of labor with bash, and implementation trade-offs**
+
+- **The tool description steers the division of labor**: it tells the model to prefer read over bash's `cat`/`sed` for viewing files, while searching (`grep`) and slicing over-long lines still go through bash.
+- **The whole file is read into memory**: good enough for source and config files, and the output caps already bound what actually reaches the context, so there is no streaming read. The cost is that the line and character caps only get their turn once the whole file has been loaded, so there is one more gate in front of the read: a 10 MB byte cap, over which the file is turned away and the model is pointed at bash to slice it, so a multi-gigabyte log cannot blow up the process. That number is far more generous than the output caps because a small window may well sit deep inside a large file — it only has to stop files that should never be loaded at all.
+- **Call display**: the agent prints `[read] <path>` when executing, keeping the same style as the bash tool's call display.

nanopycodeagent-0.5.0/docs/dev_notes/zh-CN/0.5.x.md

@@ -0,0 +1,56 @@
+# 开发笔记 — 0.5.x
+
+> 本文件为**手写中文源文件**(source of truth);英文版 [`../en/0.5.x.md`](../en/0.5.x.md) 由其生成。
+
+## 0.5.0 - 2026.07.29
+
+### 打印版本号
+工具启动时，如果不打印版本号，有时候自己分辨不出来是哪个版本。先开发一下这个功能。
+
+### 常见 code agent 内置工具
+主流 Code Agent 的内置工具调研见 [《常见 Code Agent 内置工具》](../../research/agent_tools.md)。
+
+### 内置工具设计
+
+可以看出，除了 pi 那样的核心文件/命令工具外，其他 agent 还围绕子代理编排、任务管理、定时调度、用户交互等场景扩展了大量工具。不过对我们的 nano code agent 来说，先从文件操作这一类最基础的工具开始扩展。
+
+#### read 工具
+
+我们对 [read工具](../../research/read_tool.md) 也做了调研，除了 codex 外，其他 code agent 都有专门的 read 工具。pi 和 opencode 是模型无关的，可以看出他们的 read 工具，limit 除了行数，还有文件大小，并没有 token 限制。而其他专用的 code agent，都有 token 限制，大概是只支持自家模型，token 更方便计算？
+
+功能上讲，似乎 read 和 bash 都能实现读文件需求。即使考虑文件大小可能超出限制，bash 也能正常读取。例如 codex，实际测试中发现 codex 读文件的操作，不管读什么大小文件，他都会先来个 `sed -n '1,260p' foo.md`，之后如果发现还有内容，可能会 `wc -l foo.md && sed -n '1,260p' foo.md`,相当于一块一块读，和专用 read 工具的 limit 似乎差不多。但不太确定各个模型，在读文件的时候，是用专用工具好，还是用 `bash` 更好。
+
+另外， read 工具的好处是可以方便地控制 agent 进行只读操作，而 bash 可能在工具层控制起来不那么直接，这样可能就需要在其他层面做控制，例如，沙箱。我在测试 claude code, pi, codex 的程序化方式调用时就发现，claude code 和 pi 只需要设定只使用 read 工具就可以限制只读操作，但 codex 要用沙箱才行(`codex --sandbox read_only`)。
+
+在 OpenAI 2024 年的论文 [SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering
+](https://arxiv.org/abs/2405.15793) 中提到了设计专有工具集比只用 bash 效果要好，但这是 2024 年的工作，现在模型的能力肯定更强了，不知道单纯用 bash 是不是更好（codex 自己读文件就用 bash)。不过，这些我们目前似乎无法验证，可能需要我们的基础工具集完善一点后，才好测试。目前可以先实现类似 pi 的基础工具能力。
+
+对于 read，目前实现的功能有：
+
+**接口**
+
+- **参数**：`path`(必填，绝对或相对路径，支持 `~` 展开)、`offset`(从第几行开始，1 起，默认 1)、`limit`(最多返回多少行，不传就读到行数上限为止，超过上限会被 clamp)。行数上限这个数字直接从常量插值进 schema 描述里，因为 `limit` 是模型能主动控制的参数——让它一次就选对窗口大小，而不是传了个 5000 被静默截到 2000、只能靠事后的截断提示反应过来。字符上限则没写进 `limit` 的描述：模型没有对应的参数可调，知道了也改变不了调用方式，撞上时由运行时的截断提示和错误消息说明更有效。
+- **输出格式**：`cat -n` 风格，每行前面带 1 起的行号(宽度 6 + 制表符)，和 bash 里 `cat -n` 的观感一致，方便模型直接引用行号。
+
+**上限与截断**
+
+- **两道输出上限**：一次调用最多 2000 行、50000 字符，哪个先到按哪个截断，并且**只在行边界截断**，不会把一行切成两半。这样单个文件不会一次性淹没上下文。
+- **续读提示**：窗口没读到文件末尾时，结尾追加 `[showing lines a-b of N; continue with offset=x]`，直接告诉模型总行数和下一次该从哪行接着读，不用再去 `wc -l`。
+
+**文件内容处理**
+
+- **编码**：按 UTF-8 解码，非法字节用替换字符兜底(`errors="replace"`)，和 bash 工具的容忍度保持一致。
+- **行的切分**：只按 `\n` 切，不用 `splitlines()`——后者还会在 `\x0c`、`\x0b`、`\x85`、U+2028 处断行，行号就和 `sed`、`grep -n`、编辑器对不上了；而超长行的错误消息里恰好给了一条 `sed -n 'Np'`，对不上就会切到错误的行。行尾的 `\r` 会去掉，CRLF 文件读起来和 LF 一样。
+- **二进制拒绝**：前 8KB 里出现 `\x00` 就判定为二进制文件并拒绝，避免把乱码塞进上下文。
+
+**错误处理**
+
+- **统一返回**：所有错误路径都返回 `is_error=True`，覆盖 `offset < 1`、`limit < 1`、文件不存在、路径是目录或其他非普通文件、其他 `OSError`、二进制文件、`offset` 超出文件总行数、单行超过字符上限。空文件返回 `(empty file)`。
+- **只打开普通文件**：FIFO 会一直阻塞到有人写入，`/dev/zero` 这类设备文件则永远读不完，而 read 不像 bash 工具那样有超时可以脱身，所以类型检查必须放在读之前。
+- **错误信息带下一步动作**：消息里不只说"哪里错了"，还说"接下来该怎么办"。比如 `offset` 超过文件总行数时会报出文件实际有多少行；某一行长度超过字符上限时，会直接给出一条 bash 命令让模型自己切片(`sed -n 'Np' -- file | cut -c 1-2000`)。这条命令是要交给模型去执行的，所以里面的路径先展开 `~`(引号会挡住 shell 自己的 `~` 展开)，再 `shlex.quote` 转义，并放在 `--` 之后——文件名里的空格、`$(...)` 或开头的 `-` 都不该有机会改变这条命令的形状。
+
+**与 bash 的分工、实现取舍**
+
+- **工具描述里做了分工引导**：告诉模型查看文件优先用 read 而不是 bash 里的 `cat`/`sed`，但搜索(`grep`)和切超长行仍然走 bash。
+- **一次性读入内存**：对源码、配置这类文件足够用，而且输出上限已经限定了真正进入上下文的量，所以没有做流式读取。代价是行数和字符上限都要等整个文件读完才轮得到它们生效，所以读之前还有一道 10 MB 的字节闸门：超过就直接拒绝并让模型改用 bash 切片，免得一个几 GB 的日志把进程撑爆。这个数字比输出上限宽松得多，因为一个小窗口完全可能落在大文件的深处，它只需要挡住"整个文件根本不该被载入"的情况。
+- **调用展示**：agent 侧执行时打印 `[read] <path>`，和 bash 工具的调用展示保持同一种风格。

nanopycodeagent-0.5.0/docs/research/README.md

@@ -0,0 +1,14 @@
+# Research
+
+Notes from surveying how other projects solve a problem, written before
+building the equivalent here. Unlike changelogs and dev notes, these are not
+tied to a release series — each file stands on its own, and the decisions they
+feed into are recorded in [`../dev_notes/`](../dev_notes/).
+
+These notes are **written and maintained in Chinese**; each file says so at the
+top.
+
+- [`agent_tools.md`](agent_tools.md) — the built-in tools of Pi, Claude Code,
+  Codex, OpenCode and Grok Build.
+- [`read_tool.md`](read_tool.md) — how five agent projects read files, and what
+  a dedicated read tool buys over plain bash.

nanopycodeagent-0.5.0/docs/research/agent_tools.md

@@ -0,0 +1,154 @@
+# 常见 Code Agent 内置工具
+
+> 本文明确指定使用中文编写和维护。
+
+目前 nanoPyCodeAgent 只有 Bash 工具，但主流 Code Agent 通常还会提供其他内置工具。本文调研 Pi、Claude Code、Codex、OpenCode 和 Grok Build 的工具设计。
+
+## Pi
+
+Pi 的核心工具比较少。[Pi Quick Start](https://pi.dev/docs/latest/quickstart#first-session)介绍了四个核心工具：
+
+- `read`：读文件
+- `write`：创建或覆盖文件
+- `edit`：编辑文件
+- `bash`：运行 Shell 命令
+
+除此之外，还有三个可选扩展工具：`grep`、`find`、`ls`。
+
+## Claude Code
+
+Claude Code 提供的工具更多。[Claude Code 工具参考](https://code.claude.com/docs/en/tools-reference)介绍了以下主要工具。
+
+### 文件操作
+
+- `Read`：读取文件内容，支持文本、图片、PDF、Jupyter Notebook
+- `Write`：创建或整体覆盖文件
+- `Edit`：对文件做精确字符串替换式的局部修改
+- `NotebookEdit`：按 cell 修改 Jupyter Notebook
+
+### 搜索与代码智能
+
+- `Glob`：按文件名模式查找文件
+- `Grep`：按内容模式搜索文件，基于 ripgrep
+- `LSP`：通过语言服务器提供代码智能，例如跳转定义、查找引用、报告类型错误
+
+### 命令执行
+
+- `Bash`：在环境中执行 Shell 命令
+- `PowerShell`：原生执行 PowerShell 命令，主要面向 Windows
+- `Monitor`：在后台运行命令并逐行回传输出，用于监控日志、轮询状态、订阅 WebSocket 事件
+
+### Web 访问
+
+- `WebFetch`：抓取 URL 内容，转换成 Markdown 后用小模型按 prompt 提取信息
+- `WebSearch`：执行网络搜索，返回结果标题和链接
+
+### 子代理与编排
+
+- `Agent`：派生一个拥有独立上下文窗口的子代理去完成任务
+- `SendMessage`：给 Agent Team 队友发消息，或按 ID 恢复某个子代理
+- `Workflow`：运行动态工作流脚本，在后台编排多个子代理并返回汇总结果
+- `Skill`：在主对话中执行一个 Skill，即可复用的提示词工作流
+
+### 任务管理
+
+- `TaskCreate`、`TaskGet`、`TaskList`、`TaskUpdate`：创建、查询、列出、更新任务列表
+- `TaskOutput`：获取后台任务输出；已不推荐，改用 `Read` 读取输出文件
+- `TaskStop`：按 ID 停止后台任务
+- `TodoWrite`：管理会话任务清单；默认已禁用，被 `Task*` 系列取代
+
+### 计划与工作区
+
+- `EnterPlanMode`、`ExitPlanMode`：进入计划模式设计方案，提交计划供批准并退出
+- `EnterWorktree`、`ExitWorktree`：创建并切入隔离的 Git worktree，退出后返回原目录
+
+### 定时与调度
+
+- `CronCreate`、`CronDelete`、`CronList`：在当前会话内创建、取消、列出定时任务
+- `ScheduleWakeup`：为自适应节奏的 `/loop` 安排下一次迭代时间
+- `RemoteTrigger`：创建和管理 claude.ai 上的 Routines，即云端定时代理
+
+### 用户交互与输出
+
+- `AskUserQuestion`：向用户提多选题以澄清需求
+- `Artifact`：把 HTML 或 Markdown 文件发布为 claude.ai 上的 Artifact 页面
+- `PushNotification`：发送桌面或手机推送通知
+- `SendUserFile`：把会话中的报告、截图等文件直接发送到用户设备
+- `ReportFindings`：以结构化列表上报 Code Review 发现的问题
+- `ShareOnboardingGuide`：上传 `ONBOARDING.md` 并生成团队分享链接
+
+### MCP 相关
+
+- `ListMcpResourcesTool`、`ReadMcpResourceTool`：列出、读取 MCP Server 暴露的资源
+- `ToolSearch`：按需搜索并加载延迟加载的工具，需要开启 Tool Search
+- `WaitForMcpServers`：等待仍在后台连接中的 MCP Server 就绪
+
+## Codex
+
+Codex 与 Pi 和 Claude Code 不太一样，没有单独的 `Read`、`Glob`、`Grep`；读取和搜索由 `exec_command` 调用 `rg`、`sed` 等命令完成。除[官方工具文档](https://developers.openai.com/api/docs/guides/tools)外，本文也参考了开源的 [Codex](https://github.com/openai/codex) 源码。
+
+标准本地 Coding Turn 常见的工具有：
+
+- `exec_command`：执行 Shell 命令
+- `write_stdin`：向长时间运行的命令继续输入或轮询
+- `apply_patch`：用结构化 Patch 修改文件
+- `update_plan`：更新任务计划
+- `view_image`：查看本地图片
+- `web_search`，或新式命名空间下的 `web.run`：搜索网页
+
+条件性工具还包括：
+
+- 交互：`request_user_input`
+- MCP 资源：`list_mcp_resources`、`list_mcp_resource_templates`、`read_mcp_resource`
+- 权限：`request_permissions`
+- 多代理：`spawn_agent`、`send_message`、`followup_task`、`wait_agent`、`interrupt_agent`、`list_agents`
+- 搜索工具发现：`tool_search`
+- 图片生成：`image_gen.imagegen`
+- MCP、Apps、插件注入的动态工具
+
+## OpenCode
+
+[OpenCode](https://github.com/anomalyco/opencode) v1.18.3 的内置工具有：
+
+### 文件与执行
+
+- `bash`：执行 Shell 命令
+- `read`：读取文本、图片或列出目录内容
+- `write`：创建或覆盖文件
+- `edit`：精确字符串替换
+- `apply_patch`：用 Patch 批量新增、修改、删除文件
+- `glob`：按文件名模式查找文件
+- `grep`：用正则搜索文件内容
+
+### Web 访问
+
+- `webfetch`：获取指定 URL 内容
+- `websearch`：搜索互联网
+
+### 用户交互
+
+- `question`：在执行过程中向用户提问
+
+### 技能与任务管理
+
+- `skill`：加载 `SKILL.md`
+- `todowrite`：创建和更新任务列表
+
+## Grok Build
+
+刚开源的 [Grok Build](https://github.com/xai-org/grok-build) 内置工具有：
+
+- 文件与执行：`run_terminal_command`、`read_file`、`search_replace`、`write`、`list_dir`、`grep`、`lsp`
+- 后台任务与子代理：`spawn_subagent`、`get_command_or_subagent_output`、`wait_commands_or_subagents`、`kill_command_or_subagent`、`monitor`
+- 任务管理：`todo_write`、`update_goal`
+- 定时任务：`scheduler_create`、`scheduler_delete`、`scheduler_list`
+- Plan 模式：`enter_plan_mode`、`exit_plan_mode`、`ask_user_question`
+- Web：`web_search`、`web_fetch`
+- MCP 元工具：`search_tool`、`use_tool`
+- Memory：`memory_search`、`memory_get`
+- 媒体：`image_gen`、`image_to_video`、`reference_to_video`
+
+运行时还可能动态加入：
+
+- `image_edit`
+- 服务端 `x_search`