nanoPyCodeAgent 0.8.0__tar.gz → 0.9.0__tar.gz

{nanopycodeagent-0.8.0 → nanopycodeagent-0.9.0}/.agents/skills/release/scripts/verify-release.sh

@@ -8,8 +8,7 @@
 #
 # Usage: verify-release.sh <version|vVERSION>   e.g. verify-release.sh 0.1.1
 #
-# Smoke test runs the entry point with no args (currently side-effect-free).
-# If the entry point ever gains required args/interaction, adjust step 3.
+# Smoke test uses --version without a task and checks the installed version.
 set -euo pipefail
 
 PACKAGE="nanoPyCodeAgent"
@@ -63,11 +62,12 @@ printf 'OK: GitHub Release %s has wheel + sdist\n' "$tag"
 # --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.
+# metadata can be stale right after a publish. --version exits before task input
+# or credential validation; empty stdin without it is a command-line error.
 log "Smoke-testing uvx ${PACKAGE}@${version}"
 deadline=$(( $(date +%s) + POLL_TIMEOUT ))
-until uvx --refresh --default-index "$PYPI_INDEX" --from "${PACKAGE}@${version}" "$PACKAGE" >/dev/null 2>&1 </dev/null; do
+until reported_version="$(uvx --refresh --default-index "$PYPI_INDEX" --from "${PACKAGE}@${version}" "$PACKAGE" --version 2>/dev/null </dev/null)" \
+  && [[ "$reported_version" == "${PACKAGE} ${version}" ]]; 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.8.0 → nanopycodeagent-0.9.0}/.github/workflows/ci.yml

@@ -39,3 +39,21 @@ jobs:
         # --frozen installs exactly what uv.lock pins and fails if the lock has
         # drifted from pyproject.toml, so CI tests the declared dependencies.
         run: uv run --frozen pytest
+      - name: Test the httpx2 SDK transport
+        run: uv run --with anthropic==1.5.0 pytest
+
+  harbor:
+    name: Harbor workflow contracts
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          python-version: "3.13"
+      - name: Test cache integrity, preflight, and verifier retries
+        run: >-
+          uv run --frozen --project benchmarks/harbor pytest
+          -c benchmarks/harbor/pyproject.toml benchmarks/harbor/tests

{nanopycodeagent-0.8.0 → nanopycodeagent-0.9.0}/AGENTS.md

@@ -19,6 +19,24 @@ the matching one:
 
 See `docs/RELEASING.md` for the release process and prerequisites.
 
+## Benchmarks
+
+For new Harbor benchmark runs, use the standard workflow from the repository
+root: `uv run --project benchmarks/harbor python -m harbor_adapter run --config
+<config.json>`. See `benchmarks/harbor/README.md` for configuration, verified APT
+cache import, and the `--install-only` dependency preflight option.
+
+- Do not create per-job adapter copies or ad hoc bootstrap scripts. Add reusable
+  fixes and reviewed task-revision profiles to `benchmarks/harbor` with tests.
+- Preserve task images, package sources, and official test scripts. Cache hits
+  must match the current package index's filename, size, and SHA256 digest.
+- Run dependency preflight before model work when a task has a registered
+  profile. Record unsupported profiles explicitly; do not claim they passed.
+- Keep setup failures and verifier errors separate from scored failures. Only
+  verifier timeouts may retry, at most three total attempts using the same agent
+  output and the task's original per-attempt time limit.
+
+
 ## Language
 
 Write everything in **English** by default — source code (identifiers,

nanopycodeagent-0.9.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.5
+Name: nanoPyCodeAgent
+Version: 0.9.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
+Project-URL: Issues, https://github.com/minixalpha/nanoPyCodeAgent/issues
+Author: minixalpha
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,code-agent,llm
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.13
+Requires-Dist: anthropic>=0.112.0
+Requires-Dist: httpx>=0.25.0
+Description-Content-Type: text/markdown
+
+# nanoPyCodeAgent
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+A nano code agent built in pure Python.
+
+> "What I cannot create, I do not understand." — Richard Feynman, 1988
+
+## Usage
+
+nanoPyCodeAgent requires Python 3.13 or newer.
+
+### How to Run
+
+There are a few ways to run it — pick whichever fits your workflow.
+
+#### Run without installing
+
+Use `uvx` to run the latest release without installing anything:
+
+```bash
+uvx nanoPyCodeAgent
+```
+
+#### Run after installing
+
+Install it as a persistent command-line tool, then run it from anywhere:
+
+```bash
+uv tool install nanoPyCodeAgent   # or: pipx install nanoPyCodeAgent
+nanoPyCodeAgent
+```
+
+#### Run one task and exit
+
+Give it a task and it works through it on its own, with no prompt and nothing
+to confirm — the shape a script or a benchmark harness needs:
+
+```bash
+nanoPyCodeAgent -p "add a --version flag and run the tests"
+```
+
+The task runs in the current directory and the command exits when the run
+ends. See the [complete CLI reference](docs/user_docs/en/cli_reference.md) for
+all task input methods, options, exit statuses, trajectory output, and Event
+Journal behavior.
+
+#### Run a branch or tagged version
+
+Run an unreleased branch or a specific release tag straight from GitHub:
+
+```bash
+# latest commit on a branch
+uvx --from "git+https://github.com/minixalpha/nanoPyCodeAgent@main" nanoPyCodeAgent
+
+# a specific tag
+uvx --from "git+https://github.com/minixalpha/nanoPyCodeAgent@v0.1.0" nanoPyCodeAgent
+```
+
+### Configuration
+
+Set `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN` before running the agent.
+You can also configure the endpoint and model through environment variables or
+`~/.nanoPyCodeAgent/settings.json`. See the [configuration reference](docs/user_docs/en/configuration.md)
+for supported variables, defaults, file format, precedence, and empty-value
+handling.
+
+### How to Update
+
+Upgrade an installed tool to the latest release:
+
+```bash
+uv tool upgrade nanoPyCodeAgent   # or: pipx upgrade nanoPyCodeAgent
+```
+
+## Releasing
+
+For maintainers: see [docs/RELEASING.md](docs/RELEASING.md) for the release process and prerequisites.

nanopycodeagent-0.9.0/README.md

@@ -0,0 +1,78 @@
+# nanoPyCodeAgent
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+A nano code agent built in pure Python.
+
+> "What I cannot create, I do not understand." — Richard Feynman, 1988
+
+## Usage
+
+nanoPyCodeAgent requires Python 3.13 or newer.
+
+### How to Run
+
+There are a few ways to run it — pick whichever fits your workflow.
+
+#### Run without installing
+
+Use `uvx` to run the latest release without installing anything:
+
+```bash
+uvx nanoPyCodeAgent
+```
+
+#### Run after installing
+
+Install it as a persistent command-line tool, then run it from anywhere:
+
+```bash
+uv tool install nanoPyCodeAgent   # or: pipx install nanoPyCodeAgent
+nanoPyCodeAgent
+```
+
+#### Run one task and exit
+
+Give it a task and it works through it on its own, with no prompt and nothing
+to confirm — the shape a script or a benchmark harness needs:
+
+```bash
+nanoPyCodeAgent -p "add a --version flag and run the tests"
+```
+
+The task runs in the current directory and the command exits when the run
+ends. See the [complete CLI reference](docs/user_docs/en/cli_reference.md) for
+all task input methods, options, exit statuses, trajectory output, and Event
+Journal behavior.
+
+#### Run a branch or tagged version
+
+Run an unreleased branch or a specific release tag straight from GitHub:
+
+```bash
+# latest commit on a branch
+uvx --from "git+https://github.com/minixalpha/nanoPyCodeAgent@main" nanoPyCodeAgent
+
+# a specific tag
+uvx --from "git+https://github.com/minixalpha/nanoPyCodeAgent@v0.1.0" nanoPyCodeAgent
+```
+
+### Configuration
+
+Set `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN` before running the agent.
+You can also configure the endpoint and model through environment variables or
+`~/.nanoPyCodeAgent/settings.json`. See the [configuration reference](docs/user_docs/en/configuration.md)
+for supported variables, defaults, file format, precedence, and empty-value
+handling.
+
+### How to Update
+
+Upgrade an installed tool to the latest release:
+
+```bash
+uv tool upgrade nanoPyCodeAgent   # or: pipx upgrade nanoPyCodeAgent
+```
+
+## Releasing
+
+For maintainers: see [docs/RELEASING.md](docs/RELEASING.md) for the release process and prerequisites.

nanopycodeagent-0.9.0/README.zh-CN.md

@@ -0,0 +1,74 @@
+# nanoPyCodeAgent
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+一个用纯 Python 构建的 Nano 级别的代码智能体。
+
+> “凡我不能创造的,我便未能真正理解。” —— 理查德·费曼,1988
+
+## 使用
+
+nanoPyCodeAgent 需要 Python 3.13 或更高版本。
+
+### 如何运行
+
+有几种运行方式,任选其一即可。
+
+#### 免安装运行
+
+用 `uvx` 直接运行最新发布版,无需安装任何东西:
+
+```bash
+uvx nanoPyCodeAgent
+```
+
+#### 安装后运行
+
+将它作为常驻命令行工具安装,之后可在任意位置运行:
+
+```bash
+uv tool install nanoPyCodeAgent   # 或: pipx install nanoPyCodeAgent
+nanoPyCodeAgent
+```
+
+#### 一次性任务(非交互)
+
+给它一个任务,它会自己做完退出——不给提示符,也不会停下来等确认,这正是脚本或
+benchmark harness 需要的形态:
+
+```bash
+nanoPyCodeAgent -p "add a --version flag and run the tests"
+```
+
+任务在当前目录下执行,run 结束后命令随即退出。全部任务输入方式、选项、退出状态、
+trajectory 输出和 Event Journal 行为请参阅[完整 CLI 参考](docs/user_docs/zh-CN/cli_reference.md)。
+
+#### 运行某个分支或标签版本
+
+直接从 GitHub 运行未发布的分支,或某个具体的发布标签:
+
+```bash
+# 分支上的最新提交
+uvx --from "git+https://github.com/minixalpha/nanoPyCodeAgent@main" nanoPyCodeAgent
+
+# 某个具体 tag
+uvx --from "git+https://github.com/minixalpha/nanoPyCodeAgent@v0.1.0" nanoPyCodeAgent
+```
+
+### 配置
+
+运行前请设置 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`。你也可以通过
+环境变量或 `~/.nanoPyCodeAgent/settings.json` 配置 endpoint 与模型。支持的变量、
+默认值、文件格式、优先级和空值处理请参阅[配置参考](docs/user_docs/zh-CN/configuration.md)。
+
+### 如何更新
+
+将已安装的工具升级到最新发布版:
+
+```bash
+uv tool upgrade nanoPyCodeAgent   # 或: pipx upgrade nanoPyCodeAgent
+```
+
+## 发布
+
+维护者请参阅 [docs/RELEASING.md](docs/RELEASING.md) 了解发布流程与前置条件。

nanopycodeagent-0.9.0/benchmarks/harbor/README.md

@@ -0,0 +1,196 @@
+# Harbor adapter
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+This isolated workspace contains the nanoPyCodeAgent adapter for Terminal-Bench
+and other benchmarks run by Harbor. It is development infrastructure, not part
+of the end-user `nanoPyCodeAgent` package. Harbor is pinned to 0.21.0 in this
+workspace's lockfile.
+
+## Run a benchmark
+
+Set the connection credentials used by the CLI. For a third-party or proxy
+endpoint, configure the API key and base URL; select the model with Harbor's
+`--model` option shown below:
+
+```bash
+export ANTHROPIC_API_KEY="..."
+export ANTHROPIC_BASE_URL="https://gateway.example"
+```
+
+Run new benchmarks through the standard entry point, from the repository root:
+
+```bash
+uv run --project benchmarks/harbor python -m harbor_adapter run \
+  --config benchmarks/harbor/configs/qemu-alpine-ssh.json
+```
+
+This example pins the QEMU task revision and uses `deepseek/deepseek-flash`.
+Set the endpoint and credentials for that model, or copy the configuration and
+change `agents[].model_name`, task selection, and budgets for another run. These
+are ordinary Harbor JSON configurations; the entry point supplies the standard
+verifier and cache policy. It accepts the repository's `NanoPyCodeAgent` adapter
+with budget kwargs; credentials belong in the environment.
+
+The entry point builds the current working tree, including uncommitted changes,
+into a wheel and checks its Python sources against the recorded snapshot. It
+also snapshots the adapter, records source and wheel hashes, and uses that
+snapshot throughout the run. Inputs and logs live in `jobs/<job-name>-input/`;
+Harbor outputs remain in `jobs/<job-name>/`. Existing jobs are never overwritten.
+`summary.json` records scores, setup/preflight status, cache use, and verifier
+attempts. An infrastructure exception has no score; it is not converted to zero.
+The command exits nonzero for execution errors or incomplete results, while a
+completed score of zero is a valid benchmark result.
+
+Use `--job-name <unique-name>` for a readable run name. Add `--prepare-only` to
+build and record inputs without starting containers. Add `--install-only` to
+exercise dependency installation and preflight without calling the model or
+executing the official tests. A full run still performs setup and preflight in
+its own fresh container; an install-only check does not resume into model work.
+
+### Verified dependencies and preflight
+
+The standard adapter automatically uses `.cache/nanopy-harbor/`, shared across
+runs and ignored by Git. Override it with `NANOPY_HARBOR_CACHE` or the entry
+point's `--cache-dir`. On APT systems it refreshes the package index, resolves a
+SHA256 download plan, restores matching cached files, and downloads missing
+ones. Successful downloads are verified and saved before installation, so
+APT cleanup hooks cannot erase the shared copies. A different version or digest
+does not reuse an old cached file. Corrupt files fail setup before model work.
+Other package managers use Harbor's regular dependency installation.
+
+To import previously verified downloads once:
+
+```bash
+uv run --project benchmarks/harbor python -m harbor_adapter import-apt \
+  /path/to/bootstrap-cache/manifest.json
+```
+
+The manifest is a JSON array of objects with `url`, `filename`, `size`, and
+`sha256`, accompanied by `packages/<filename>` files. Import validates every
+file. At use time, the current APT index must independently match each entry.
+Copying the entire shared cache to another machine is also supported. A new
+machine with no matching cache still needs the original downloads to be
+available; this mechanism does not replace package sources or invent missing
+versions.
+
+Verifier dependency profiles are tied to reviewed task revisions in
+`src/harbor_adapter/bootstrap.py`. The current QEMU profile installs `sshpass`
+and warms the original verifier's uv 0.9.5, Python 3.13, pytest 8.4.1, and
+pytest-json-ctrf 0.3.5 dependencies using `pytest --version`. It runs no task
+assertions or solution code. Unknown QEMU revisions fail setup pending profile
+review; tasks without a profile explicitly report `not_configured`. Add a
+profile and regression tests when another task needs verifier preflight.
+
+Every installation writes `agent/bootstrap.json`, including partial progress
+on failure. Preflight failure stops the trial before any model call. The
+official verifier script remains unchanged and may still access the network
+when it runs; a successful preflight is not a guarantee against later outages.
+Full standard runs enable the timeout retry policy below by default, with zero
+whole-trial retries. CI checks these contracts without model calls or Docker.
+
+### Direct Harbor invocation
+
+For adapter development or comparison with published versions, the lower-level
+Harbor interface remains available. Pin the agent installed in the container:
+
+```bash
+uv run --project benchmarks/harbor harbor run \
+  --task terminal-bench/openssl-selfsigned-cert \
+  --agent harbor_adapter:NanoPyCodeAgent \
+  --agent-kwarg git_ref=<commit-sha> \
+  --model anthropic/claude-sonnet-4-6 \
+  --verifier harbor_adapter:RetryingVerifier \
+  --verifier-timeout-multiplier 4 \
+  --env docker \
+  --n-concurrent 1 \
+  --n-attempts 1
+```
+
+Use `--agent-kwarg version=<released-version>` instead of `git_ref` to install a
+published PyPI release. The two pins are mutually exclusive. If neither is
+provided, the adapter installs the latest published release. For reproducible
+benchmark results, always provide one of them. Prefer a full 40-character commit
+SHA for `git_ref`; Harbor may parse an unquoted abbreviated SHA such as `83e6271`
+as a number. To use an abbreviated revision, preserve its string type with
+`--agent-kwarg 'git_ref="83e6271"'`.
+
+The adapter sends the instruction through stdin, runs the agent in the task
+container's current directory, and saves combined stdout/stderr to
+`/logs/agent/nanopycodeagent.txt`. It uses the CLI's 50-turn default; override
+that with `--agent-kwarg max_turns=20`.
+
+Use `--agent-kwarg time_budget_seconds=N` to bound task work and remind the model
+to finalize before either time or replies run out. Choose a budget inside each
+task's native timeout, reserving at least 30 seconds for cost reconciliation
+plus trajectory writing and harness overhead. For example, the 3600-second
+targeted experiments use 3420 seconds; that value does not fit a 900-second task.
+No time budget is inferred automatically by the adapter.
+
+For the per-reply generation limit, pass `--agent-kwarg max_tokens=32768`.
+This becomes `--max-tokens 32768` in the container and overrides the forwarded
+`ANTHROPIC_MAX_TOKENS` environment variable. When omitted, the adapter sends no
+token flag, so the installed agent's environment/settings/default applies
+(32768 in the version introducing this option). Older releases require omitting
+the new option. The effective budget is recorded in the startup log and in
+`agent.extra.max_tokens` in the ATIF trajectory.
+
+The adapter also asks the agent to write an ATIF-v1.7 trajectory directly to
+`/logs/agent/trajectory.json`. Harbor collects that file as the trial's native
+ATIF output and backfills prompt, completion, cache-token, and cost totals into
+the agent result. Missing, invalid, or partial trajectories remain explicitly
+diagnosed; unknown usage or cost is not reported as zero.
+If any costs are estimated, `final_metrics.extra` records
+`cost_is_estimated: true` and the estimated portion in `estimated_cost_usd`.
+The adapter preserves both fields in the agent result's `metadata.trajectory`,
+including for partial totals. Estimates with a generation ID remain eligible
+for billing reconciliation; a successful lookup replaces the estimate.
+
+By default, the adapter strips the first provider prefix from `--model` and
+passes the result to nanoPyCodeAgent as `ANTHROPIC_MODEL`. Set
+`ANTHROPIC_MODEL` only when a custom endpoint requires an actual model name that
+differs from Harbor's `provider/model` identity; this explicit override takes
+precedence. Harbor-native provider credentials and configured base URLs are
+also normalized to the `ANTHROPIC_*` variables expected by nanoPyCodeAgent's
+SDK.
+
+## Retry verifier timeouts
+
+The example above uses `harbor_adapter:RetryingVerifier` for single-step Linux
+tasks. It runs the original test script up to **three times total**, retrying
+only when the script exceeds the task's native `[verifier].timeout_sec`. A
+900-second task therefore gets at most three 900-second attempts. A completed
+verification stops immediately, including a reward of zero. Script errors,
+missing or invalid rewards, and cancellation do not trigger another attempt.
+
+`--verifier-timeout-multiplier 4` gives Harbor's outer watchdog room for all
+three attempts plus test upload, process cleanup, and log collection. It does
+not extend each test-script attempt. Conflicting timeout overrides or caps
+that leave insufficient overall time are rejected. Use
+`--verifier-kwarg max_attempts=2` for two total attempts, or `max_attempts=1` for
+one; values above three are rejected.
+
+The runner reuses the same container, agent output, and dependency caches;
+the agent is run once. Test scripts must tolerate being rerun in that
+environment; verifier-side filesystem changes are not rolled back. Timed-out
+process groups and other members of their Linux session are killed before
+retrying. Each attempt's logs and any reward files are archived under
+`verifier/attempts/1/`, `2/`, and `3/`. The runner clears current verifier
+outputs before the next attempt, so a stale reward cannot determine its score.
+`verifier/retry-summary.json` records each attempt's status, duration, and exit
+code when available. Exhausting the attempts still produces Harbor's
+`VerifierTimeoutError`.
+
+This verifier requires `python3` and `bash` in the container, which the
+nanoPyCodeAgent adapter installs. These options apply to new runs; they cannot
+restore a deleted container or missing task outputs from an old trial.
+Harbor's ordinary `--max-retries` setting reruns the entire trial, including
+the agent, and is independent of these verifier attempts.
+
+## Test the adapter
+
+```bash
+uv run --project benchmarks/harbor pytest \
+  -c benchmarks/harbor/pyproject.toml \
+  benchmarks/harbor/tests
+```