nanoPyCodeAgent 0.7.0__tar.gz → 0.8.0__tar.gz

{nanopycodeagent-0.7.0 → nanopycodeagent-0.8.0}/.gitignore

@@ -218,3 +218,6 @@ __marimo__/
 .streamlit/secrets.toml
 
 references/
+
+# Harbor benchmark results
+/jobs/

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

@@ -37,11 +37,15 @@ 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.
 
+Do not label a document as `hand-written` unless its contents are actually
+authored and maintained by humans. For agent-authored source-of-truth documents,
+use wording such as `Chinese source` instead.
+
 ### Bilingual research notes
 
 Research notes are bilingual:
 
-- `docs/research/zh-CN/` contains the hand-written Chinese sources of truth.
+- `docs/research/zh-CN/` contains the 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.
 
@@ -52,6 +56,28 @@ the English version is in sync, even when it has already been updated.
 
 ## Commits & PRs
 
+### Branch and pull request workflow
+
+All non-release changes MUST be made on a dedicated branch and merged into
+`main` through a GitHub pull request.
+
+- Before modifying repository files, agents MUST verify that the current branch
+  is not `main`. If it is `main`, create or switch to a dedicated branch first.
+- Agents MUST NOT commit directly to `main` or push non-release commits to
+  `origin/main`.
+- Open a pull request targeting `main`, and use the `land-pr` skill to merge it.
+  Do not merge without the skill's mandatory maintainer confirmation.
+- If work was accidentally started on `main`, move the changes to a dedicated
+  branch before committing or pushing them.
+
+The sole exception is the release workflow in `.agents/skills/release/SKILL.md`.
+Only when the maintainer explicitly requests a release may that skill commit and
+push its release-only changes directly to `main`, and only after its mandatory
+confirmation gate. Documentation, chores, hotfixes, and all other work still
+require a branch and pull request.
+
+### Commit and PR title format
+
 All agents working in this repo MUST follow
 [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)
 for **commit messages** and **PR titles** (squash-merge often uses the PR

nanopycodeagent-0.8.0/CONTEXT.md

@@ -0,0 +1,65 @@
+# Code Agent Runtime
+
+This glossary defines the runtime artifacts produced and maintained by a code agent so that public output, diagnostics, evaluation data, and resumable state remain distinct.
+
+## Language
+
+**Agent Run**:
+A bounded execution that starts with an instruction and ends when the agent stops autonomous work.
+_Avoid_: Session, turn
+
+**Run Output**:
+The public result or event protocol that one agent run emits to its caller.
+_Avoid_: Trace, transcript
+
+**Run Result Object**:
+A single public object that summarizes how one Agent Run ended, including its final result and optional usage metadata.
+_Avoid_: Trajectory, session export
+
+**Public Event Stream**:
+A caller-facing Run Output that exposes a stable, selected sequence of Agent Run events as they occur.
+_Avoid_: Internal event bus, execution trace
+
+**Source Record**:
+An agent-specific record observed at a CLI, SDK, or protocol boundary and consumed by an adapter; it may already be a projection of the agent's internal state.
+_Avoid_: Native event, journal entry
+
+**Native Event**:
+An agent-independent runtime fact accepted by the core directly or normalized from a Source Record.
+_Avoid_: Source record, public event record, trajectory step
+
+**Journal Entry**:
+A Native Event together with the identity, ordering, and recording metadata required for durable history.
+_Avoid_: Persistence envelope, trajectory step
+
+**Event Journal**:
+A durable append-only sequence of Journal Entries for an Agent Run from which derived artifacts can be rebuilt.
+_Avoid_: Trajectory, session, public event stream
+
+**Partial Content**:
+An unfinished representation of a message, reasoning block, or tool input that is exposed before the logical content is complete.
+_Avoid_: Final message, completed event
+
+**Content Delta**:
+The incremental fragment or change relative to content already emitted for the same logical item.
+_Avoid_: Partial snapshot, final message
+
+**Terminal Event**:
+The final Public Event Stream record that explicitly states how an Agent Run ended.
+_Avoid_: EOF, last message
+
+**Execution Trace**:
+A diagnostic record of runtime activity retained to explain failures, timing, and internal behavior.
+_Avoid_: Run output, trajectory
+
+**Trajectory**:
+A task-scoped record of observations, actions, results, and outcome prepared for evaluation or offline analysis.
+_Avoid_: Execution trace, session, transcript
+
+**ATIF Trajectory**:
+A Trajectory represented by the Agent Trajectory Interchange Format and exposed as the runtime's public trajectory contract.
+_Avoid_: Event journal, native trajectory
+
+**Session**:
+Durable agent state that can span multiple runs and supports continuing or branching prior work.
+_Avoid_: Agent run, trajectory, transcript

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nanoPyCodeAgent
-Version: 0.7.0
+Version: 0.8.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
@@ -14,6 +14,7 @@ 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
@@ -49,6 +50,46 @@ 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"
+nanoPyCodeAgent --prompt-file task.md
+printf "%s" "$TASK" | nanoPyCodeAgent
+```
+
+The task is carried out in the current directory. `--max-turns N` caps how
+many model replies one run may spend (50 by default).
+
+Add `--trajectory PATH` to save that headless Agent Run as one complete
+[ATIF-v1.7](https://www.harborframework.com/docs/agents/trajectory-format)
+JSON document without changing stdout:
+
+```bash
+nanoPyCodeAgent -p "read README.md and summarize it" \
+  --trajectory ./trajectory.json
+```
+
+The option creates the requested file with owner-only permissions (`0600`)
+after the run reaches a terminal state. It refuses to overwrite an existing
+path. Trajectories may contain the task, model replies, tool arguments, and
+tool results, so treat them as sensitive data.
+
+A run like this exits `0` whenever the agent actually ran — including when it
+gave up or ran out of turns with the task unfinished, which is for whatever
+checks the result to judge. A non-zero exit means the run could not happen at
+all: `1` for missing credentials or an API that kept refusing, `2` for a
+misused command line.
+
+Every Agent Run also writes a replayable internal Event Journal under
+`~/.nanoPyCodeAgent/journals/`. These JSONL files can contain prompts, model
+replies, repository content, and tool results, so treat them as sensitive;
+the directory is user-only (`0700`) and each file is `0600`. Journals are not
+public run output or trajectories, and they are not rotated automatically yet.
+
 #### Run a branch or tagged version
 
 Run an unreleased branch or a specific release tag straight from GitHub:
@@ -75,6 +116,7 @@ put the values under an `env` object. Empty or whitespace-only values are ignore
 {
   "env": {
     "ANTHROPIC_API_KEY": "",
+    "ANTHROPIC_AUTH_TOKEN": "",
     "ANTHROPIC_BASE_URL": "",
     "ANTHROPIC_MODEL": ""
   }
@@ -83,7 +125,8 @@ put the values under an `env` object. Empty or whitespace-only values are ignore
 
 | Variable | Required | Default | Description |
 | --- | --- | --- | --- |
-| `ANTHROPIC_API_KEY` | Yes | — | Your Anthropic API key, or the key for a third-party / proxy service. |
+| `ANTHROPIC_API_KEY` | One credential required | — | Your Anthropic API key, or an API key accepted by a third-party service. |
+| `ANTHROPIC_AUTH_TOKEN` | One credential required | — | A bearer token used instead of `ANTHROPIC_API_KEY`; OpenRouter recommends this mode for its Anthropic-compatible endpoint. |
 | `ANTHROPIC_BASE_URL` | No | `https://api.anthropic.com` | Point the SDK at a non-official / proxy endpoint. Leave it unset to use the official API — an empty value breaks requests. |
 | `ANTHROPIC_MODEL` | No | `claude-sonnet-4-6` | Override the model. An empty or whitespace-only value falls back to the default. |
 

{nanopycodeagent-0.7.0 → nanopycodeagent-0.8.0}/README.md

@@ -31,6 +31,46 @@ 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"
+nanoPyCodeAgent --prompt-file task.md
+printf "%s" "$TASK" | nanoPyCodeAgent
+```
+
+The task is carried out in the current directory. `--max-turns N` caps how
+many model replies one run may spend (50 by default).
+
+Add `--trajectory PATH` to save that headless Agent Run as one complete
+[ATIF-v1.7](https://www.harborframework.com/docs/agents/trajectory-format)
+JSON document without changing stdout:
+
+```bash
+nanoPyCodeAgent -p "read README.md and summarize it" \
+  --trajectory ./trajectory.json
+```
+
+The option creates the requested file with owner-only permissions (`0600`)
+after the run reaches a terminal state. It refuses to overwrite an existing
+path. Trajectories may contain the task, model replies, tool arguments, and
+tool results, so treat them as sensitive data.
+
+A run like this exits `0` whenever the agent actually ran — including when it
+gave up or ran out of turns with the task unfinished, which is for whatever
+checks the result to judge. A non-zero exit means the run could not happen at
+all: `1` for missing credentials or an API that kept refusing, `2` for a
+misused command line.
+
+Every Agent Run also writes a replayable internal Event Journal under
+`~/.nanoPyCodeAgent/journals/`. These JSONL files can contain prompts, model
+replies, repository content, and tool results, so treat them as sensitive;
+the directory is user-only (`0700`) and each file is `0600`. Journals are not
+public run output or trajectories, and they are not rotated automatically yet.
+
 #### Run a branch or tagged version
 
 Run an unreleased branch or a specific release tag straight from GitHub:
@@ -57,6 +97,7 @@ put the values under an `env` object. Empty or whitespace-only values are ignore
 {
   "env": {
     "ANTHROPIC_API_KEY": "",
+    "ANTHROPIC_AUTH_TOKEN": "",
     "ANTHROPIC_BASE_URL": "",
     "ANTHROPIC_MODEL": ""
   }
@@ -65,7 +106,8 @@ put the values under an `env` object. Empty or whitespace-only values are ignore
 
 | Variable | Required | Default | Description |
 | --- | --- | --- | --- |
-| `ANTHROPIC_API_KEY` | Yes | — | Your Anthropic API key, or the key for a third-party / proxy service. |
+| `ANTHROPIC_API_KEY` | One credential required | — | Your Anthropic API key, or an API key accepted by a third-party service. |
+| `ANTHROPIC_AUTH_TOKEN` | One credential required | — | A bearer token used instead of `ANTHROPIC_API_KEY`; OpenRouter recommends this mode for its Anthropic-compatible endpoint. |
 | `ANTHROPIC_BASE_URL` | No | `https://api.anthropic.com` | Point the SDK at a non-official / proxy endpoint. Leave it unset to use the official API — an empty value breaks requests. |
 | `ANTHROPIC_MODEL` | No | `claude-sonnet-4-6` | Override the model. An empty or whitespace-only value falls back to the default. |
 

{nanopycodeagent-0.7.0 → nanopycodeagent-0.8.0}/README.zh-CN.md

@@ -31,6 +31,42 @@ uv tool install nanoPyCodeAgent   # 或: pipx install nanoPyCodeAgent
 nanoPyCodeAgent
 ```
 
+#### 一次性任务(非交互)
+
+给它一个任务,它会自己做完退出——不给提示符,也不会停下来等确认,这正是脚本或
+benchmark harness 需要的形态:
+
+```bash
+nanoPyCodeAgent -p "add a --version flag and run the tests"
+nanoPyCodeAgent --prompt-file task.md
+printf "%s" "$TASK" | nanoPyCodeAgent
+```
+
+任务在当前目录下执行。`--max-turns N` 限制一次运行最多花费多少轮模型回复(默认
+50 轮)。
+
+增加 `--trajectory PATH` 可以把这次 headless Agent Run 保存为一份完整的
+[ATIF-v1.7](https://www.harborframework.com/docs/agents/trajectory-format) JSON
+文档,同时不改变 stdout:
+
+```bash
+nanoPyCodeAgent -p "read README.md and summarize it" \
+  --trajectory ./trajectory.json
+```
+
+run 到达终态后,该选项才会以仅当前用户可读写的权限(`0600`)创建目标文件;如果
+目标已存在则拒绝覆盖。trajectory 可能包含任务、模型回复、工具参数和工具结果,
+应按敏感数据处理。
+
+只要 agent 真的跑起来了,退出码就是 `0`——包括它放弃了、或者轮数用尽而任务没做
+完,那该由检查结果的一方去判定。非零退出码表示这次运行根本没能进行:`1` 是缺少
+凭据或 API 持续失败,`2` 是命令行用错了。
+
+每次 Agent Run 还会在 `~/.nanoPyCodeAgent/journals/` 下写入可重放的内部 Event
+Journal。这些 JSONL 文件可能包含提示词、模型回复、仓库内容和工具结果,应按敏感
+数据处理;目录只允许当前用户访问(`0700`),每个文件的权限为 `0600`。Journal 既
+不是公开 run output,也不是 trajectory,目前还不会自动轮转。
+
 #### 运行某个分支或标签版本
 
 直接从 GitHub 运行未发布的分支,或某个具体的发布标签:
@@ -56,6 +92,7 @@ uvx --from "git+https://github.com/minixalpha/nanoPyCodeAgent@v0.1.0" nanoPyCode
 {
   "env": {
     "ANTHROPIC_API_KEY": "",
+    "ANTHROPIC_AUTH_TOKEN": "",
     "ANTHROPIC_BASE_URL": "",
     "ANTHROPIC_MODEL": ""
   }
@@ -64,7 +101,8 @@ uvx --from "git+https://github.com/minixalpha/nanoPyCodeAgent@v0.1.0" nanoPyCode
 
 | 变量 | 是否必填 | 默认值 | 说明 |
 | --- | --- | --- | --- |
-| `ANTHROPIC_API_KEY` | 是 | 无 | 你的 Anthropic API key,或第三方/代理服务的 key。 |
+| `ANTHROPIC_API_KEY` | 两种凭据任选其一 | 无 | 你的 Anthropic API key,或第三方服务接受的 API key。 |
+| `ANTHROPIC_AUTH_TOKEN` | 两种凭据任选其一 | 无 | 代替 `ANTHROPIC_API_KEY` 使用的 bearer token;OpenRouter 的 Anthropic-compatible endpoint 推荐这种方式。 |
 | `ANTHROPIC_BASE_URL` | 否 | `https://api.anthropic.com` | 将 SDK 指向非官方/代理 endpoint。使用官方 API 时保持不设置;留空值会导致请求失败。 |
 | `ANTHROPIC_MODEL` | 否 | `claude-sonnet-4-6` | 覆盖默认模型。空值或纯空白会回退到默认值。 |
 

nanopycodeagent-0.8.0/benchmarks/harbor/README.md

@@ -0,0 +1,68 @@
+# 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"
+```
+
+From the repository root, run Harbor through this workspace and pin the agent
+installed in the task 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 \
+  --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`.
+
+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.
+
+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.
+
+## Test the adapter
+
+```bash
+uv run --project benchmarks/harbor pytest \
+  -c benchmarks/harbor/pyproject.toml \
+  benchmarks/harbor/tests
+```

nanopycodeagent-0.8.0/benchmarks/harbor/README.zh-CN.md

@@ -0,0 +1,61 @@
+# Harbor adapter
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+这个独立 workspace 包含 nanoPyCodeAgent 面向 Terminal-Bench 及其他 Harbor
+评测任务的 adapter。它属于开发基础设施，不是面向普通用户的
+`nanoPyCodeAgent` 软件包的一部分。该 workspace 的 lockfile 将 Harbor 固定在
+0.21.0。
+
+## 运行 benchmark
+
+设置 CLI 使用的连接凭据。使用第三方或代理 endpoint 时，配置 API key 和 base
+URL；模型由下方 Harbor 命令中的 `--model` 选择：
+
+```bash
+export ANTHROPIC_API_KEY="..."
+export ANTHROPIC_BASE_URL="https://gateway.example"
+```
+
+从仓库根目录通过这个 workspace 运行 Harbor，并固定安装到 task 容器中的 agent：
+
+```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 \
+  --env docker \
+  --n-concurrent 1 \
+  --n-attempts 1
+```
+
+如需安装已经发布到 PyPI 的版本，请使用
+`--agent-kwarg version=<released-version>` 代替 `git_ref`。这两个版本参数互斥；
+如果都未提供，adapter 会安装最新发布版本。为了让 benchmark 结果可复现，请始终
+提供其中一个参数。`git_ref` 最好使用完整的 40 位 commit SHA；Harbor 可能把
+`83e6271` 这样的无引号短 SHA 解析成数字。如果需要使用短 revision，请通过
+`--agent-kwarg 'git_ref="83e6271"'` 保留其字符串类型。
+
+adapter 通过 stdin 发送任务指令，在 task 容器的当前目录中运行 agent，并把合并后
+的 stdout/stderr 保存到 `/logs/agent/nanopycodeagent.txt`。它默认沿用 CLI 的 50
+轮限制；可以通过 `--agent-kwarg max_turns=20` 覆盖此设置。
+
+adapter 还会要求 agent 将 ATIF-v1.7 trajectory 直接写入
+`/logs/agent/trajectory.json`。Harbor 会把该文件作为 trial 的原生 ATIF 输出采集，
+并将 prompt、completion、cache token 和 cost 汇总回填到 agent result。trajectory
+缺失、无效或指标不完整时会保留明确诊断；未知 usage 或 cost 不会被记成零。
+
+默认情况下，adapter 会移除 `--model` 中的第一个 provider 前缀，并将结果作为
+`ANTHROPIC_MODEL` 传给 nanoPyCodeAgent。只有自定义 endpoint 要求的实际模型名与
+Harbor 的 `provider/model` 身份不同时，才显式设置 `ANTHROPIC_MODEL`；该覆盖值优先。
+Harbor 原生的 provider 凭证和已经配置的 base URL 也会转换为 nanoPyCodeAgent SDK
+所需的 `ANTHROPIC_*` 变量。
+
+## 测试 adapter
+
+```bash
+uv run --project benchmarks/harbor pytest \
+  -c benchmarks/harbor/pyproject.toml \
+  benchmarks/harbor/tests
+```

nanopycodeagent-0.8.0/benchmarks/harbor/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "nanopycodeagent-harbor-adapter"
+version = "0.1.0"
+description = "Repository-local Harbor adapter for nanoPyCodeAgent benchmarks."
+requires-python = ">=3.13"
+dependencies = [
+    "harbor==0.21.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/harbor_adapter"]
+
+[dependency-groups]
+dev = [
+    "nanopycodeagent",
+    "pytest>=9.1.1",
+]
+
+[tool.uv.sources]
+nanopycodeagent = { path = "../..", editable = true }
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

nanopycodeagent-0.8.0/benchmarks/harbor/src/harbor_adapter/__init__.py

@@ -0,0 +1,5 @@
+"""Public import for the repository-local nanoPyCodeAgent Harbor adapter."""
+
+from .adapter import NanoPyCodeAgent
+
+__all__ = ["NanoPyCodeAgent"]