nanoPyCodeAgent 0.5.1__tar.gz → 0.7.0__tar.gz

{nanopycodeagent-0.5.1 → nanopycodeagent-0.7.0}/.agents/skills/land-pr/SKILL.md

@@ -5,16 +5,18 @@ description: >
   Makes the PR self-contained: rewrites the PR description from the PR's own
   contents, appends a changelog [Unreleased] entry when warranted, regenerates the
   English dev notes from the Chinese source when touched, and keeps the bilingual
-  README in sync. Then — only after explicit maintainer confirmation — merges the
-  PR. Does NOT tag or publish. Triggers on
+  README in sync. It also checks bilingual research notes and reminds the maintainer
+  when their English version needs refreshing. Then — only after explicit maintainer
+  confirmation — merges the PR. Does NOT tag or publish. Triggers on
   "合并 PR / land PR / 合并这个 PR / merge this PR".
 ---
 
 # Land a PR
 
 Merge a feature/bugfix PR into `main`, making the PR **self-contained** first:
-its code, changelog entry, dev notes (zh + en), and README (zh + en) all in sync
-within the PR. This skill never tags or publishes — that is the `release` skill's job.
+its code, changelog entry, dev notes (zh + en), research-note translation status,
+and README (zh + en) all accounted for within the PR. This skill never tags or
+publishes — that is the `release` skill's job.
 
 ## Prerequisites
 
@@ -31,38 +33,46 @@ file, e.g. `docs/changelogs/0.1.x.md` / `docs/dev_notes/{zh-CN,en}/0.1.x.md`.
 - `git status --porcelain` — empty (clean tree).
 - current branch is **not** `main` (`git branch --show-current`).
 
-### 2. Ensure a PR exists
+### 2. Check English research notes before PR creation
+If the branch modified any `docs/research/zh-CN/<name>.md`, check the
+corresponding `docs/research/en/<name>.md`. Explicitly remind the maintainer
+that the English version must also be translated or refreshed, and report
+whether it is in sync. Do this even when the English file was already updated.
+If it is missing or stale, surface that clearly before opening or landing the
+PR; do not silently treat the Chinese-only change as complete.
+
+### 3. Ensure a PR exists
 ```bash
 gh pr view --json number,url 2>/dev/null || gh pr create --fill
 ```
 Note the PR number for later steps.
 
-### 3. Append a changelog entry (when warranted)
+### 4. Append a changelog entry (when warranted)
 Inspect `git diff main...HEAD`. If the changes are worth recording for users, add
 an entry under `## [Unreleased]` in `<series>` (changelogs) in the right group
 (Added / Changed / Fixed / Removed). Purely internal/tooling changes may need
 **no** entry — decide, and surface the decision at the gate.
 
-### 4. Sync English dev notes (if the Chinese source changed)
+### 5. Sync English dev notes (if the Chinese source changed)
 If this PR modified `docs/dev_notes/zh-CN/<series>.md`, regenerate the whole
 `docs/dev_notes/en/<series>.md` by translating the Chinese source. The English
 file is generated — do not hand-edit beyond this regeneration.
 
-### 5. Keep the bilingual README in sync
+### 6. Keep the bilingual README in sync
 If this PR changed only one of `README.md` / `README.zh-CN.md`, mirror the change
 into the other (translate/align) so the pair stays consistent. Both READMEs are
 hand-written sources — propose the synced change and let the maintainer adjust the
 wording at the gate; do not blindly overwrite. If both were already changed, skip.
 
-### 6. Commit and push the sync changes
-Commit any changes from steps 3–5 to the feature branch and push:
+### 7. Commit and push the sync changes
+Commit any changes from steps 4–6 to the feature branch and push:
 ```bash
 git commit -am "docs: sync changelog/dev-notes/README for this PR"
 git push
 ```
-(Skip if steps 3–5 produced no changes.)
+(Skip if steps 4–6 produced no changes.)
 
-### 7. Rewrite the PR description from scratch
+### 8. Rewrite the PR description from scratch
 Build the description **only** from the PR's actual contents — commits, changed
 files, `gh pr diff`. **Do not read or extend the old description** (it may be
 stale). Update via the GitHub API (`gh pr edit` can fail on deprecated Projects
@@ -71,13 +81,14 @@ Classic):
 gh api repos/{owner}/{repo}/pulls/{number} -X PATCH -f body="..." --silent
 ```
 
-### 8. ⛔ Confirmation gate (mandatory)
+### 9. ⛔ Confirmation gate (mandatory)
 Present to the maintainer: the rewritten **PR description**, the **changelog
 entry** added (or "none, because …"), and any **dev notes / README sync** done
-(or a README drift warning). **Wait for explicit confirmation** (e.g. "确认 / go").
-Do not merge until approved.
+(or a README drift warning), plus the **English research-note sync status** when
+applicable. **Wait for explicit confirmation** (e.g. "确认 / go"). Do not merge
+until approved.
 
-### 9. Merge
+### 10. Merge
 ```bash
 gh pr merge --merge
 ```

{nanopycodeagent-0.5.1 → nanopycodeagent-0.7.0}/AGENTS.md

@@ -37,6 +37,19 @@ The **only** exception is documentation explicitly designated as Chinese:
 Everything outside that list — including code under `src/`, this file, and all
 other docs — is English.
 
+### Bilingual research notes
+
+Research notes are bilingual:
+
+- `docs/research/zh-CN/` contains the hand-written Chinese sources of truth.
+- `docs/research/en/` contains English versions generated from the Chinese
+  sources; regenerate the whole corresponding file instead of hand-editing it.
+
+When a change to a Chinese research source is headed into a pull request, the
+agent MUST remind the user that the corresponding English version also needs to
+be translated or refreshed. Before opening or landing the PR, report whether
+the English version is in sync, even when it has already been updated.
+
 ## Commits & PRs
 
 All agents working in this repo MUST follow

{nanopycodeagent-0.5.1 → nanopycodeagent-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: nanoPyCodeAgent
-Version: 0.5.1
+Version: 0.7.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.7.0/docs/changelogs/0.6.x.md

@@ -0,0 +1,37 @@
+# Changelog — 0.6.x
+
+All notable changes in the **0.6.x** release series are documented here.
+
+## [Unreleased]
+
+## [0.6.0] - 2026-08-13
+
+### Added
+- A `write` tool creates a file or replaces its entire content from a
+  structured `{path, content}` call. Content lands on disk as data instead
+  of passing through shell quoting and heredocs, which could silently
+  corrupt it; missing parent directories are created, directories and
+  non-regular files (FIFOs, device files) are refused as targets, and the
+  result states whether the file was created or overwritten. The terminal
+  echoes the target path with the content folded to its first lines.
+- A spinner animates while waiting for the model's reply or a running bash
+  command, so long waits no longer look like a frozen terminal. It draws
+  only when stdout is a terminal (and `NO_COLOR` is unset) and erases
+  itself once output arrives, leaving no trace in the transcript.
+
+### Changed
+- Echoed tool calls (`[bash]$ ...`, `[read] ...`) now sit on a lighter
+  background shade than their output, so the command and what it printed
+  read apart at a glance.
+
+<!--
+When cutting a release, copy the relevant items from [Unreleased] into a new
+version section above it, e.g.:
+
+## [0.6.0] - YYYY-MM-DD
+
+### Added
+### Changed
+### Fixed
+### Removed
+-->

nanopycodeagent-0.7.0/docs/changelogs/0.7.x.md

@@ -0,0 +1,32 @@
+# Changelog — 0.7.x
+
+All notable changes in the **0.7.x** release series are documented here.
+
+## [Unreleased]
+
+## [0.7.0] - 2026-08-17
+
+### Added
+- An `edit` tool that replaces an exact stretch of an existing text file,
+  so changing a few lines no longer means rewriting the whole file. The
+  match is literal — no regex, no whitespace or similarity guessing — and
+  must be unique unless `replace_all` is set, so a call that no longer fits
+  the file fails with a message saying how to recover instead of editing
+  the wrong place. A UTF-8 BOM and a CRLF file's line endings are handled
+  for you; creating a file and rewriting one whole stay with `write`.
+- English translations for all research notes, organized alongside their
+  hand-written Chinese sources of truth. Development notes now link to the
+  matching research language, and the pull-request workflow reports whether
+  English research translations are in sync when Chinese sources change.
+
+<!--
+When cutting a release, copy the relevant items from [Unreleased] into a new
+version section above it, e.g.:
+
+## [0.7.0] - YYYY-MM-DD
+
+### Added
+### Changed
+### Fixed
+### Removed
+-->

{nanopycodeagent-0.5.1 → nanopycodeagent-0.7.0}/docs/dev_notes/en/0.5.x.md

@@ -10,7 +10,7 @@ When the tool starts up without printing its version, I sometimes cannot tell wh
 
 ### 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).
+For a survey of the built-in tools of mainstream code agents, see [Built-in Tools in Common Code Agents](../../research/en/agent_tools.md).
 
 ### Designing the built-in tools
 
@@ -18,7 +18,7 @@ As the survey shows, beyond the core file/command tools that something like pi o
 
 #### 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?
+We also surveyed the [read tool](../../research/en/read_tool.md): 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`.
 

nanopycodeagent-0.7.0/docs/dev_notes/en/0.6.x.md

@@ -0,0 +1,48 @@
+# Development Notes — 0.6.x
+
+> Generated from the Chinese source [`../zh-CN/0.6.x.md`](../zh-CN/0.6.x.md). Do not edit by hand.
+
+## 0.6.0 - 2026.08.13
+
+### Tool output polish
+
+Before continuing with the write tool, let's first add some improvements to how the agent presents its output: tool use and tool output now get separate background colors, so it is easier to tell at a glance which part is the tool use and which is the tool use result. Down the road we may want to emit something like an execution trace into a jsonl file; for now this will do.
+
+I also tried the animated ASCII indicator pi shows while waiting for the agent's reply: `⠋ Working`. To my surprise, the animated characters turn out to be a few Braille glyphs displayed in rotation — and they are fairly easy to implement, so let's just build it.
+
+### The write tool
+
+This version implements the write tool. Today the agent writes files like this:
+
+````text
+You> write a python version hello world to hello.py
+
+Agent>
+[bash]$ cat > hello.py << 'EOF'
+print("Hello, World!")
+EOF
+cat hello.py
+python3 hello.py
+print("Hello, World!")
+Hello, World!
+
+Agent> I created `hello.py` with the following content:
+
+```python
+print("Hello, World!")
+```
+
+Running it outputs: `Hello, World!`
+````
+
+Based on the revised conclusion of the [write tool research](../../research/en/write_tool.md), the write tool should implement:
+
+- Structured `{path, content}` input: the content lands on disk as data, never passing through shell expansion, heredoc delimiters, or quote escaping — eliminating the whole class of failures where a heredoc silently corrupts a file;
+- Create the file when it does not exist, overwrite it whole when it does, and state which of the two happened in the result;
+- Path handling identical to read's: absolute or relative to the working directory, with a leading `~` expanded;
+- Automatically create missing parent directories;
+- Refuse directories and non-regular files (FIFOs, device files) as write targets — opening a FIFO for writing blocks without a timeout and hangs the session, and a device file could be written by mistake; read already performs the same check on its targets, and write follows the same approach;
+- Write the content exactly as given, as UTF-8 text, with no newline or whitespace normalization;
+- Error messages state what to do next, in read's style;
+- The terminal echoes the target path and a content preview folded to the first few lines, consistent with the tool output shading presentation;
+- The tool description limits its purpose to new files and whole-file rewrites (appending and bulk transforms still go through bash) and claims no safety whatsoever: no prior-Read check, no mtime/revision staleness guard, no atomic replace — the semantics are last-writer-wins.

nanopycodeagent-0.7.0/docs/dev_notes/en/0.7.x.md

@@ -0,0 +1,230 @@
+# Development Notes — 0.7.x
+
+> Generated from the Chinese source [`../zh-CN/0.7.x.md`](../zh-CN/0.7.x.md). Do not edit by hand.
+
+## 0.7.0 - 2026.08.17
+
+This version builds the edit tool. It starts from a survey of the edit tools of mainstream code agents, see [edit tool research](../../research/en/edit_tool.md).
+
+There are two basic motivations for building an edit tool.
+
+First, when changing a few lines of code, sending just the small stretch of old text and its replacement is enough — there is no need to make the model regenerate the entire file. That saves output tokens, and it keeps a full copy of the file from occupying the context for a long time.
+
+Second, a whole-file rewrite easily changes places nobody asked it to change, whereas a unique `old_text` match is itself a verifiable precondition — when the old content is no longer there the call simply fails and the model re-reads, instead of overwriting unconditionally.
+
+Of course, partial edits can also be made through bash, but at agent runtime it is hard to reliably derive from a dynamic shell snippet which file was changed, what old content it assumed, and what diff it actually produced. A dedicated tool also fails in a structured way (no match / N matches / the file has changed), which is easier to recover from than a chunk of shell stderr.
+
+I tested what happens without an edit tool: I first wrote a `quick_sort.py`, then asked for comments to be added. nanoPyCodeAgent 0.6.x called the write tool and rewrote the whole file — confirming that without an edit tool the context grows.
+
+Based on the research, here is what this round's edit tool implements.
+
+### The edit tool contract
+
+**Input** (`input_schema`, in the same style as `read`/`write`):
+
+```text
+path         string   required   File path, absolute or relative to the agent's working directory; a leading ~ is expanded
+old_text     string   required   The text to replace, character for character as it appears in the file; must not be empty
+new_text     string   required   The replacement text; an empty string means deleting old_text exactly
+replace_all  boolean  optional   Defaults to false; when true, replaces every non-overlapping match
+```
+
+**Output**: like `read`/`write`, it returns a single stretch of plain text plus an `is_error` flag, not a structured object. On success it returns a one-line summary and does not feed the file's content back to the model:
+
+```text
+[edited src/app.py: replaced 1 occurrence at line 42]
+[edited src/app.py: replaced 3 occurrences, first at line 12]
+```
+
+On failure `is_error=true`, and every kind of failure has to state both what happened and what to do next:
+
+```text
+[no match for old_text in src/app.py; read the file again and copy the text exactly — the CRLF retry was already tried]
+[old_text matches 3 times in src/app.py; add surrounding context to make it unique, or set replace_all=true]
+[old_text and new_text are identical: nothing to change]
+[old_text is empty; use write to create a file or replace it whole]
+[file not found: src/app.py]
+[src/app.py is a directory, not a file]
+[src/app.py is not valid UTF-8; edit is text-only]
+[src/app.py is 12000000 bytes, over the 10000000 limit; edit it with bash]
+```
+
+In the terminal the call shows up as `[edit] src/app.py` plus a folded little old/new diff. The full `old_text`/`new_text` is no longer fed back through the tool result — it is already in the tool input of that assistant message.
+
+### Other implementation points for the edit tool
+
+- **Field naming follows this project**: use `path` and snake_case, consistent with the existing `read`/`write`. Claude Code's `old_string` and OpenCode's `filePath`/`oldString` are deliberately not copied — a clear tool description is enough to teach the model, and there is no reason to fracture this project's naming just to align with some other product.
+- **Unique match, fail outright when it is not**: by default `old_text` has to occur exactly once in the file; zero matches fails, and multiple matches without `replace_all` also fails and reports the match count. With `replace_all=True` it replaces every non-overlapping match and returns the actual count. Better to make the model retry once more than to guess a location.
+- **Exact only, no fuzzy matching**: no regex, and no fallbacks such as trimming, indentation flexibility, similarity scoring or Unicode normalization. The only input conversions allowed are the BOM and line endings — both directional, both enumerable in scope, and both of which must be stated honestly in the tool description. Unlike OpenCode V1 and Pi, we must not claim "exact" to the model while the real matching boundary is wider.
+- **Draw a clear line against `write`**: it only edits regular files that already exist; creating new files and rewriting whole ones stay with `write`. `old_text` must not be empty, and `old_text == new_text` fails. `new_text=""` means an exact deletion, with no hidden semantics like "and also take the following newline with it."
+- **Strict UTF-8 and BOM handling**: files that are not valid UTF-8, and files containing NUL, are refused — `read` displays bad bytes as replacement characters to make them inspectable, and if edit round-tripped that view it would corrupt the original bytes for good. A UTF-8 BOM is stripped before matching and restored on write; otherwise an `old_text` aimed at the first line would mysteriously fail to match because of one invisible character.
+- **Match `read`'s newline view with one directional CRLF retry**: first do a raw exact pass on `old_text` as given. Only when that finds nothing, and the file contains `\r\n`, and `old_text` contains `\n` but no `\r`, is its LF→CRLF form retried once — with `new_text` converted along with it. The two passes are never unioned: uniqueness and counting both happen in whichever pass actually matched. In a file with mixed line endings, a fragment in the other style simply does not match this time; that is a deliberate fail-closed, and the error message has to say that the CRLF retry was already tried.
+- **File size reuses `MAX_READ_BYTES`, a 10 MB cap**: the implementation is a whole-file read-compute-write, so anything over the cap is refused outright with a suggestion to use bash or a dedicated script instead.
+- **Paths, symlinks and error style align with `read`/`write`**: `~` expansion, the regular-file check and the error format all stay consistent. The first version writes back directly and explicitly offers no mtime check, no CAS and no atomic replace — do not pretend in the copy to have guarantees that do not exist.
+- **The tool description has to teach the model how to choose**: prefer edit for ordinary partial changes, write for new files or whole-file rewrites, bash for bulk mechanical transforms. `old_text` has to be character-for-character identical, two to four lines is usually enough, it must not carry read's line-number prefix, and the model must not splice in `\r` itself.
+- **Test matrix**: unique replacement / deletion / Unicode / no-op; not-found, repeated matches and `replace_all` counting; untouched content keeping its exact bytes under LF, CRLF, no trailing newline and mixed line endings; BOM stripping and restoration; invalid UTF-8 and NUL refusal; missing files, directories, FIFOs, over-cap files; `~` and relative paths, symlink behavior consistent with `write`; the folded terminal display and the `is_error` setting; several edits in one reply taking effect in order.
+
+Explicitly out of scope for this version: no enforced prior Read (there is no read revision registry today, and a unique `old_text` is already a local precondition), no `edits[]` batching, no `apply_patch`, no local imitation of a formatter / LSP / history / approval UI, and no per-file queue (tool calls currently execute single-threaded and in order). These wait until parallel calls, approvals and remote filesystems genuinely show up, at which point they all get upgraded together into a mutation core shared by write and edit.
+
+### QA
+
+What follows are questions and answers from discussions with the agent: I asked the questions, the agent organized the answers, providing the explanation the material above needs.
+
+#### Q: What exactly are the fallbacks mentioned under "exact only, no fuzzy matching"? What do "supporting regex" and "supporting trim" look like as code behavior?
+
+First, a baseline: **exact means taking `old_text`'s byte sequence and finding an identical substring in the file**. The four spaces in `"    return x\n"`, the `\n` at the end of the line, whether each quote is straight or curly — all of it has to line up. Every item below opens a hole in that baseline, and each one happens *after* exact matching fails, answering the question "should we try again with a relaxed standard?"
+
+**1. Regex**
+
+"Supporting regex" = treating `old_text` as a pattern instead of a literal:
+
+```python
+content.find(old_text)              # literal matching (what we want)
+re.sub(old_text, new_text, content) # regex matching (what we do not want)
+```
+
+The difference is that `. * + ? ( ) [ ] { } | ^ $ \` become **metacharacters**: the model wants to delete `foo(bar)` from the source, and the regex reads it as "foo followed by a capture group bar", actually matching `foobar`; `a.b` matches `axb`. These symbols are extremely dense in code, and the model would have to escape each one to express "I mean this literal text" — which it frequently forgets. Conversely, regex can express bulk patterns like `def \w+\(`, but that is bash's job (`sed`/`perl`). None of the five surveyed projects does regex in edit; this rule keeps sed's mindset out.
+
+**2. Trim (comparing after stripping whitespace per line / on both sides)**
+
+"Supporting trim" = after exact fails, split both sides into lines, `strip()` the leading and trailing whitespace off each, and compare line by line:
+
+```text
+The line in the file (two trailing spaces):  "    return x  "
+The old_text the model submitted:            "    return x"
+```
+
+Exact does not match (two trailing spaces missing); with per-line trim on, both sides strip down to `"return x"` and it counts as a hit, then that whole line in the file is replaced. Codex's `seek_sequence` does "ignore trailing whitespace → trim both sides" (`en/edit_tool.md:273`), Pi does per-line trailing-whitespace normalization (`en/edit_tool.md:170`), and OpenCode V1 has a dedicated trim replacer (`en/edit_tool.md:224`).
+
+Why they do it: trailing whitespace is especially easy to lose in transit. Claude Code's API message normalization silently strips non-Markdown per-line trailing whitespace from `new_string` (`en/edit_tool.md:208`), so the model never gets a chance to submit accurate trailing whitespace at all.
+
+Why we do not: first, the matched range stops being equal to the bytes the model wrote (it thinks it is changing `"    return x"`, while what actually gets changed is `"    return x  "`). Second, **what to write back** becomes another question that has to be settled — keep the file's original trailing whitespace, or erase it per the model's version? Two trailing spaces in Markdown are a hard line break, and erasing them changes the meaning. Once this hole is open, the sentence "the tool changes exactly what the model submitted" is no longer true.
+
+**3. Indentation flexibility**
+
+"Supporting indentation flexibility" = allowing `old_text` as a whole to be one level less (or more) indented than the file, and after matching, re-indenting `new_text` to the file's original indentation:
+
+```text
+In the file (inside a function, 8-space indent):   The old_text the model submitted (flush left):
+        if x:                                      if x:
+            return 1                                   return 1
+```
+
+With this level enabled, the tool notices every line is missing the same 8-space prefix, decides it is the same block, and adds the 8 spaces back to each line of `new_text` when replacing. OpenCode V1 has this replacer (`en/edit_tool.md:224`). It addresses the model's habit of rewriting from memory rather than copying, at the cost that in a language like Python — where indentation *is* syntax — getting the level wrong while re-indenting is a silent semantic error, and what the model receives is "success".
+
+**4. Similarity (block anchor + Levenshtein)**
+
+The widest level of all: use only `old_text`'s first and last lines as anchors to locate the region, and require the lines in between not to be identical but merely "similar". OpenCode V1 finds candidate regions by the first/last lines, computes a Levenshtein edit distance over the middle content to get a similarity score between 0 and 1, and **accepts anything ≥ 0.65**, taking the highest-scoring candidate and keeping the first on a tie (`en/edit_tool.md:224-225`):
+
+```text
+The old_text the model submitted:   What is actually in the file:
+def run(x):                         def run(x):
+    y = x + 1                           y = x * 2      ← the middle lines all differ
+    z = y * 3                           z = y - 7
+    return z                            log(z)
+                                        return z
+```
+
+The ends line up, the middle clears the similarity bar, and the tool deletes those 5 lines from the file as a block and swaps in `new_text` — **the old content the model quoted and the content actually deleted are not the same thing**, and the reply it gets is "replaced 1 occurrence". OpenCode V1 has to add an extra guard for this ("reject when the matched span is far larger than `old_text`", `en/edit_tool.md:224`). It can afford this because V1 has a human approval diff as a backstop before anything reaches disk (`en/edit_tool.md:226`); our first version has no approval UI, so there is nothing here to catch what falls through this hole.
+
+**5. Unicode normalization**
+
+"Supporting" it = folding characters that "look alike but have different code points" into the same thing before comparing:
+
+| Category | What the model submitted | What is actually in the file |
+| --- | --- | --- |
+| smart quotes | `"hello"` (U+201C/U+201D) | `"hello"` (U+0022) |
+| dash | `a – b` (en dash) | `a - b` (hyphen) |
+| special spaces | NBSP (U+00A0) | ordinary space (U+0020) |
+| NFKC | `（` fullwidth parenthesis, `fi` ligature | `(`, `fi` |
+
+Model output passes through rendering and the tokenizer, which easily turns straight quotes into curly ones, so all five projects implement some version of this level: Grok has optional confusable normalization (`en/edit_tool.md:116`), Pi does NFKC + punctuation + special spaces (`en/edit_tool.md:170`), Claude Code does only quote normalization plus a fixed desanitize set (`en/edit_tool.md:202`), and Codex normalizes punctuation and spaces (`en/edit_tool.md:273`). The crucial difference is what gets written back: Grok maps the matched position back to the original UTF-8 bytes and fails closed when the mapping is not clean; Pi replaces on the normalized text and copies back only the lines it did not touch, so **the lines it did touch incidentally undergo NFKC / punctuation / trailing-whitespace changes**, producing modifications the model never asked for (`en/edit_tool.md:307`).
+
+**So why do the BOM and line-ending conversions we kept not count as fuzzy?**
+
+| | The five levels above | BOM / line endings |
+| --- | --- | --- |
+| Cause | Guessing the model copied it wrong | Caused by our own `read` view |
+| Direction | Two-way folding, both sides change | One-way conversion, only the `old_text` side changes |
+| Trigger | Heuristic scoring | Can be written as a single if |
+| Matched range | May be larger than the literal the model submitted | Strictly equal |
+
+`read` drops the `\r` of CRLF when displaying, so multi-line original text in the model's hands necessarily has LF only — it could not produce `\r` even if it wanted to. That is not the model copying it wrong, it is a mismatch our own view created, so the tool supplies the conversion: the file contains `\r\n`, `old_text` contains `\n` and no `\r`, and the first pass came up empty — only when all three hold does one LF→CRLF retry happen. The BOM is the same story: `read` does not strip U+FEFF, so an invisible character hangs at the start of the first line, and without stripping it the match fails mysteriously. Both can be written into the tool description in one sentence for the model to verify; a similarity threshold of 0.65 cannot, and even if written down the model would have no way to judge which stretch was actually matched.
+
+**The trade-off in one sentence**: fuzzy matching raises the first-try success rate, and what it costs is that the range the tool is actually authorized to modify becomes larger than the range the model expressed. Products with a human approval diff can afford that cost; our first version has no approval, no undo and no checkpoint, so one wrong replacement lands straight on disk. So we choose fail closed — the cost of failure is only that the model reads the file once more and retries, and that happens to be what agents are best at.
+
+#### Q: What are the mechanisms behind those five items under "explicitly out of scope for this version", and why not do them now?
+
+**1. No enforced prior Read (read-before-edit)**
+
+"What it looks like if done": the agent keeps a table in the session recording, for each file, **whether it has been read in this session and which version was read** (a timestamp or content hash). Before an edit runs, it consults that table: never read means refuse outright and make the model read first; read but the file's mtime is newer than that read means someone changed it in the meantime, so refuse as well.
+
+Claude Code does the heaviest version of this among the five projects: it does not merely suggest reading in the tool description, it enforces session read state at runtime, and a system-injected partial view does not count. Before writing it re-reads the current metadata synchronously to double-check, and deliberately inserts no `await` between the check and the write, squeezing the race window into a single event loop tick (`en/edit_tool.md:200`).
+
+Why not now: we do not have that table, and building one means first building a read revision registry — and `read` supports `offset`/`limit` anyway, so what it returns is often just a window onto the file, which makes "has been read" an ambiguous state to begin with. More importantly, a unique `old_text` match **is itself a precondition**: if the old content is gone, the call fails, and that already covers the main scenario of "the file changed, so do not blind-write". Recording mtime only narrows the window; it does not eliminate TOCTOU (between the check and the actual write another process can still cut in), while adding a pile of state to carry (`en/edit_tool.md:367`).
+
+When to add it: once there is undo/checkpoint or an approval UI and we need an explicit answer to "which version was the model's judgment based on".
+
+**2. No `edits[]` batching**
+
+"What it looks like if done": the schema goes from a single old/new to an array, submitting several changes to the same file in one call:
+
+```text
+path: string
+edits: [ {old_text, new_text}, {old_text, new_text}, ... ]
+```
+
+Pi has exactly this shape: every `old_text` matches against **the same original file** (not against the result of the previous item), everything is validated first, overlapping ranges are rejected, and then they are applied in reverse order with a single write to disk (`en/edit_tool.md:149-177`). The benefit is one read, one write, a group of changes that logically all hold or all fail together, and fewer tool round trips.
+
+Why not now: our agent loop is single-threaded and sequential — multiple `tool_use` blocks in one assistant reply are executed one at a time in the order the model gave them (`src/nanopycodeagent/agent.py:172-179`), so the model can already fire several edits in one turn, with each seeing the previous one's result. Batching would only save a few I/O operations, in exchange for overlap detection, per-item validation, and the question of how to report partial failure (`en/edit_tool.md:368`).
+
+There is one more lesson from Pi: it once supported both a single old/new and `edits[]`, and the model kept mixing the two and producing invalid calls; in the end only the array survived, with the old shape demoted to a runtime input-migration layer (`en/edit_tool.md:161`, `en/edit_tool.md:315`). So if we ever do upgrade, only one public schema can remain — the two cannot coexist.
+
+When to add it: when tool round-trip latency, or "many changes to one file", becomes a measured bottleneck.
+
+**3. No `apply_patch`**
+
+"What it looks like if done": instead of old/new strings, the call carries a whole patch text, expressing additions, deletions, changes and moves across several files at once:
+
+```text
+*** Begin Patch
+*** Update File: src/app.py
+@@ def run():
+-    old line
++    new line
+*** Add File: src/new.py
++content
+*** Delete File: src/old.py
+*** End Patch
+```
+
+Codex has only this one file-modification tool; even creating a file is expressed with `*** Add File`, and no whole-file write is exposed (`en/edit_tool.md:246-267`). It is the most expressive option, with one parser and one permission entry point shared across files.
+
+Why not now: it means writing a parser for a patch language, handling error recovery when a hunk fails to locate, facing partial commits where **the first few files write successfully and a later one fails** during a multi-file sequential submission (Codex itself does not roll back either, `en/edit_tool.md:277`), and redefining which set of paths permissions apply to. All of that would significantly inflate the core of a nano agent. Besides, the default model is Claude Sonnet, which is more familiar with the old/new form of Edit (`en/edit_tool.md:369`); OpenCode simply dispatches by model — `apply_patch` for the GPT family, `edit` + `write` for everything else (`en/edit_tool.md:218`).
+
+When to add it: when a single call needs to express something atomically across several files (a rename plus updating all references, say), or when adapting to a model whose training distribution is patch-shaped.
+
+**4. No local imitation of a formatter / LSP / history / approval UI**
+
+These four are an entire lifecycle mature agents hang around "writing to disk". One at a time:
+
+- **formatter**: after writing, automatically run something like prettier/black, then **recompute the diff from the formatted result** before returning it to the model. OpenCode V1 does this (`en/edit_tool.md:222`); the cost is that what finally lands on disk may be larger than the diff shown at approval time.
+- **LSP**: after writing, notify the language server to re-analyze and stuff the newly produced diagnostics (type errors, undefined variables) into the tool result, so the model sees on the spot whether it broke something. OpenCode V1 has it, and Claude Code has it when an IDE is connected (`en/edit_tool.md:206`, `en/edit_tool.md:222`).
+- **history / undo**: save a snapshot before every write, supporting rewind to a given step. Grok's `FileWritten` event carries previous/new content precisely to feed the hunk tracker and rewind (`en/edit_tool.md:120`).
+- **approval UI**: put the diff in front of a human before writing, and only write once approved. OpenCode V1/V2's `edit` permission is exactly this (`en/edit_tool.md:222`, `en/edit_tool.md:238`).
+
+Why not now: these are **not capabilities of the edit tool but of the whole mutation / exec control plane**. Adding a layer only on edit is bypassed by one `sed -i` in bash — approval, snapshots, path protection, all of it: as long as bash can still write arbitrary files, the defense has a hole (`en/edit_tool.md:370`). A half-installed security boundary is more dangerous than none, because it makes people believe there is one.
+
+When to add it: once bash and the file tools land inside the same OS / container / VM filesystem boundary, build it as a whole then, rather than simulating one on edit first.
+
+**5. No per-file queue**
+
+"What it looks like if done": take an in-process lock keyed by the file's canonical path (the real path with symlinks resolved), serializing the whole "read current content → compute new content → write back" stretch, so two mutations of the same file cannot interleave while different files still run in parallel. Pi uses a mutation queue keyed by `realpath` (`en/edit_tool.md:177`); OpenCode V2 goes further and does `writeIfUnchanged(expectedBytes)` inside that lock — comparing the current bytes against the bytes read at approval time and declaring it stale if they differ (`en/edit_tool.md:238-242`).
+
+What it prevents is a **lost update**: two changes run concurrently, A reads the old content, B reads the old content, A writes, B writes, and A's change is silently overwritten by B.
+
+Why not now: we have no concurrency at all. Tool calls are dispatched sequentially in a single while loop (`src/nanopycodeagent/agent.py:172-179`), only one edit runs at any moment, and an in-process lock would always be available and never contended (`en/edit_tool.md:333`, `en/edit_tool.md:371`). And to be clear: this kind of lock **can only coordinate the tools that participate in it** — external editors and bash subprocesses can still cut in between the read and the write, so it was never a cross-writer CAS (`en/edit_tool.md:242`).
+
+When to add it: the day parallel tool calls actually arrive — at which point the whole read-compute-write stretch goes into a shared queue keyed by canonical path, rather than locking only the write itself.
+
+**The shared logic behind these five**: either they address **a problem that does not exist yet** under the current architecture (concurrency, batching round trips), or they **cannot be solved at all** under the current architecture (approval and snapshots are bypassed by bash), or they **would inflate the core for unclear benefit** (a patch parser, a revision registry). The closing line of the research puts it well: first solve the token and accidental-overwrite problems of partial edits with a unique old-text precondition, and wait until the architecture genuinely develops concurrency, approval and remote needs before upgrading the mutation core — rather than simulating safety ahead of time (`en/edit_tool.md:412`).

{nanopycodeagent-0.5.1 → nanopycodeagent-0.7.0}/docs/dev_notes/zh-CN/0.5.x.md

@@ -8,7 +8,7 @@
 工具启动时，如果不打印版本号，有时候自己分辨不出来是哪个版本。先开发一下这个功能。
 
 ### 常见 code agent 内置工具
-主流 Code Agent 的内置工具调研见 [《常见 Code Agent 内置工具》](../../research/agent_tools.md)。
+主流 Code Agent 的内置工具调研见 [《常见 Code Agent 内置工具》](../../research/zh-CN/agent_tools.md)。
 
 ### 内置工具设计
 
@@ -16,7 +16,7 @@
 
 #### read 工具
 
-我们对 [read工具](../../research/read_tool.md) 也做了调研，除了 codex 外，其他 code agent 都有专门的 read 工具。pi 和 opencode 是模型无关的，可以看出他们的 read 工具，limit 除了行数，还有文件大小，并没有 token 限制。而其他专用的 code agent，都有 token 限制，大概是只支持自家模型，token 更方便计算？
+我们对 [read工具](../../research/zh-CN/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` 更好。
 

nanopycodeagent-0.7.0/docs/dev_notes/zh-CN/0.6.x.md

@@ -0,0 +1,46 @@
+# 开发笔记 — 0.6.x
+
+> 本文件为**手写中文源文件**(source of truth);英文版 [`../en/0.6.x.md`](../en/0.6.x.md) 由其生成。
+
+## 0.6.0 - 2026.08.13
+### 工具输出优化
+继续开发 write tool 之前，先加一些 Agent 输出方式相关的优化，tool use 和 tool output 背景颜色分开，更容易看出哪里是 tool use ，哪里是 tool use result。后续可能需要输出类似执行轨迹的东西，放 jsonl 里，目前暂时先这样处理。
+
+另外，尝试了一下 pi 里等待 Agent 回复时的 ascii 动态字符: `⠋ Working`，没想到动态字符居然是几个交替显示的盲文，实现起来也比较容易，就先实现吧。
+
+### write 工具
+
+这一版本实现 write 相关工具，当前这个 agent 对文件的写入方式是这样：
+
+````text
+You> write a python version hello world to hello.py
+
+Agent>
+[bash]$ cat > hello.py << 'EOF'
+print("Hello, World!")
+EOF
+cat hello.py
+python3 hello.py
+print("Hello, World!")
+Hello, World!
+
+Agent> I created `hello.py` with the following content:
+
+```python
+print("Hello, World!")
+```
+
+Running it outputs: `Hello, World!`
+````
+
+基于 [write 工具调研](../../research/zh-CN/write_tool.md)修正后的结论，write 工具要实现的功能：
+
+- 结构化 `{path, content}` 入参：内容作为数据直接落盘，不经过 shell 展开、heredoc delimiter 和引号转义，消除 heredoc 静默写坏文件这一整类失败；
+- 文件不存在则创建，存在则整文件覆盖，并在结果中说明是哪一种；
+- 路径处理与 read 一致：绝对路径或相对工作目录，展开开头的 `~`；
+- 自动创建缺失的父目录；
+- 拒绝目录和非常规文件（FIFO、设备文件）作为写入目标——对 FIFO 的写打开会无超时阻塞挂死会话，设备文件则可能被误写；read 对读取目标已有同样的检查，write 沿用同一做法；
+- 内容按给定原样写入，UTF-8 文本，不做换行或空白归一化；
+- 错误信息按 read 的风格指出下一步该怎么做；
+- 终端回显目标路径和折叠到前几行的内容预览，与 tool output shading 的展示风格一致；
+- 工具描述限定用途为新建文件和整文件重写（追加、批量变换仍走 bash），并且不宣称任何安全性：没有先 Read 检查、没有 mtime/revision 防陈旧、没有原子替换——语义就是 last-writer-wins。