@pencil-agent/nano-pencil 2.0.1 → 2.0.3

package/dist/extensions/builtin/grub/README.md

@@ -1,112 +1,112 @@
-# Grub Extension
-
-`/grub` runs one autonomous long-running task until the agent reports it
-complete, reports it is blocked, the user stops it, or a safety limit is
-reached. The harness design follows the pattern described in Anthropic's
-[Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents):
-a structured on-disk state lets coding agents pick up where they left off
-even across fresh context windows and full process restarts.
-
-## Commands
-
-- `/grub <goal> [--max-iter N] [--max-fail N]` — start one autonomous task
-- `/grub status [--json]` — show the active or last finished grub task
-- `/grub resume` — resume dispatch for an adopted/persisted task
-- `/grub stop` — stop the active grub task
-
-## Harness artifacts
-
-Each task owns a directory at `.grub/<task-id>/`:
-
-| File | Purpose | Who may write |
-|------|---------|---------------|
-| `feature-list.json` | Structured list of end-to-end features | Initializer writes the whole file once; coding agents may only flip `passes` and set `evidence` |
-| `progress-log.md` | Dated notes describing each iteration | Agent, append-only |
-| `init.sh` | Get-bearings + project smoke script run at the start of every iteration | Initializer; later agents may add project-specific smoke commands |
-| `state.json` | Durable `GrubTaskState` snapshot for cross-session resume | Controller, atomic writes |
-
-`feature-list.json` schema (version 1):
-
-```json
-{
-  "version": 1,
-  "goal": "<user goal>",
-  "features": [
-    {
-      "id": "kebab-slug",
-      "category": "functional|verification|polish",
-      "description": "observable behavior",
-      "steps": ["actionable", "verification", "steps"],
-      "passes": false,
-      "evidence": "optional git sha or short proof"
-    }
-  ]
-}
-```
-
-The controller validates every mutation: changing `description`, `steps`,
-`category`, `id`, list length, or reordering counts as a violation. Agents
-are told up front that the only permitted edits are toggling `passes` and
-setting `evidence`.
-
-## How it works
-
-- Each grub iteration is tagged with a `[GRUB:<id>:<n>]` prompt prefix so
-  the extension can recognise its own injected turns.
-- On start, grub creates the harness directory and writes the initial
-  artifacts without creating a git commit. The harness keeps durable state on
-  disk and leaves source changes visible in the working tree, avoiding noisy
-  `grub(...)` commits unless the user explicitly asks for them.
-- Two phase-specialized system prompts are injected via
-  `before_agent_start`:
-  - **Initializer prompt** (first successful turn): expand
-    `feature-list.json` into 15-40 concrete features, harden `init.sh`,
-    seed `progress-log.md`. No broad implementation yet.
-  - **Coding prompt** (remaining turns): run `init.sh`, pick exactly one
-    pending feature, implement + verify end-to-end, flip `passes` +
-    `evidence`, and append to `progress-log.md`.
-- At the end of every grub turn the assistant must emit a single
-  `<loop-state>{"status":"continue|complete|blocked", "summary":"...", "nextStep":"..."}</loop-state>`
-  block. The extension parses it and dispatches the next iteration or
-  stops with a terminal status.
-- **Initializer sanitize-not-fail**: while in the initializer phase, only
-  genuinely unfixable structural problems (feature count out of 15-40,
-  unreplaced placeholder, non-kebab ids, duplicate ids) fail the turn and
-  force a retry. Recoverable hygiene issues are auto-corrected instead of
-  killing the task: a wrong `goal` is restored to the authoritative task goal,
-  pre-marked `passes:true` are reset to `false`, and stray `evidence` is
-  dropped. The sanitized list is written back to disk and becomes the baseline,
-  so the phase always advances once the structure is valid.
-- **Phase-aware failure budget**: the initializer gets a more forgiving budget
-  (default 5) than execution (default 3, via `--max-fail`), because standing up
-  a valid harness is a distinct, retry-friendly activity from execution work.
-- **Mutation guard**: after the initializer creates the first real
-  `feature-list.json`, each subsequent turn is diffed against the persisted
-  baseline. Rewriting feature ids, descriptions, categories, steps, count, or
-  order is rejected and retried; only `passes` and `evidence` may change.
-- **Completion guard**: if the decision says `complete` but
-  `feature-list.json` still has `passes:false` entries, the controller
-  rewrites the decision to `continue` with a synthetic `nextStep`
-  pointing at the first pending feature. The harness will not allow
-  premature "done".
-- **Cross-session resume**: `GrubTaskState` is written atomically to
-  `state.json` on every transition. On the next session, `session_start`
-  calls `discoverActiveTasks()` and adopts the most recent running task
-  without auto-dispatching — the user types `/grub resume` to continue.
-- **Safety limits**: 25 iterations and 3 consecutive failures by default;
-  override with `--max-iter` / `--max-fail`.
-- **Stale harness cleanup**: on extension load, terminal harnesses older
-  than 30 days are pruned from `.grub/`.
-
-## Legacy migration
-
-Earlier versions wrote `feature-checklist.md` (markdown checkboxes). When a
-new iteration starts and `feature-list.json` is missing but the legacy file
-exists, its checkbox items are migrated into the JSON format (category
-defaults to `functional`; `steps` start empty so the initializer can refine
-later).
-
-## Related
-
-For the recurring scheduler that runs prompts or slash commands on an
-interval, see the sibling [`loop` extension](../loop/README.md).
+# Grub Extension
+
+`/grub` runs one autonomous long-running task until the agent reports it
+complete, reports it is blocked, the user stops it, or a safety limit is
+reached. The harness design follows the pattern described in Anthropic's
+[Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents):
+a structured on-disk state lets coding agents pick up where they left off
+even across fresh context windows and full process restarts.
+
+## Commands
+
+- `/grub <goal> [--max-iter N] [--max-fail N]` — start one autonomous task
+- `/grub status [--json]` — show the active or last finished grub task
+- `/grub resume` — resume dispatch for an adopted/persisted task
+- `/grub stop` — stop the active grub task
+
+## Harness artifacts
+
+Each task owns a directory at `.grub/<task-id>/`:
+
+| File | Purpose | Who may write |
+|------|---------|---------------|
+| `feature-list.json` | Structured list of end-to-end features | Initializer writes the whole file once; coding agents may only flip `passes` and set `evidence` |
+| `progress-log.md` | Dated notes describing each iteration | Agent, append-only |
+| `init.sh` | Get-bearings + project smoke script run at the start of every iteration | Initializer; later agents may add project-specific smoke commands |
+| `state.json` | Durable `GrubTaskState` snapshot for cross-session resume | Controller, atomic writes |
+
+`feature-list.json` schema (version 1):
+
+```json
+{
+  "version": 1,
+  "goal": "<user goal>",
+  "features": [
+    {
+      "id": "kebab-slug",
+      "category": "functional|verification|polish",
+      "description": "observable behavior",
+      "steps": ["actionable", "verification", "steps"],
+      "passes": false,
+      "evidence": "optional git sha or short proof"
+    }
+  ]
+}
+```
+
+The controller validates every mutation: changing `description`, `steps`,
+`category`, `id`, list length, or reordering counts as a violation. Agents
+are told up front that the only permitted edits are toggling `passes` and
+setting `evidence`.
+
+## How it works
+
+- Each grub iteration is tagged with a `[GRUB:<id>:<n>]` prompt prefix so
+  the extension can recognise its own injected turns.
+- On start, grub creates the harness directory and writes the initial
+  artifacts without creating a git commit. The harness keeps durable state on
+  disk and leaves source changes visible in the working tree, avoiding noisy
+  `grub(...)` commits unless the user explicitly asks for them.
+- Two phase-specialized system prompts are injected via
+  `before_agent_start`:
+  - **Initializer prompt** (first successful turn): expand
+    `feature-list.json` into 15-40 concrete features, harden `init.sh`,
+    seed `progress-log.md`. No broad implementation yet.
+  - **Coding prompt** (remaining turns): run `init.sh`, pick exactly one
+    pending feature, implement + verify end-to-end, flip `passes` +
+    `evidence`, and append to `progress-log.md`.
+- At the end of every grub turn the assistant must emit a single
+  `<loop-state>{"status":"continue|complete|blocked", "summary":"...", "nextStep":"..."}</loop-state>`
+  block. The extension parses it and dispatches the next iteration or
+  stops with a terminal status.
+- **Initializer sanitize-not-fail**: while in the initializer phase, only
+  genuinely unfixable structural problems (feature count out of 15-40,
+  unreplaced placeholder, non-kebab ids, duplicate ids) fail the turn and
+  force a retry. Recoverable hygiene issues are auto-corrected instead of
+  killing the task: a wrong `goal` is restored to the authoritative task goal,
+  pre-marked `passes:true` are reset to `false`, and stray `evidence` is
+  dropped. The sanitized list is written back to disk and becomes the baseline,
+  so the phase always advances once the structure is valid.
+- **Phase-aware failure budget**: the initializer gets a more forgiving budget
+  (default 5) than execution (default 3, via `--max-fail`), because standing up
+  a valid harness is a distinct, retry-friendly activity from execution work.
+- **Mutation guard**: after the initializer creates the first real
+  `feature-list.json`, each subsequent turn is diffed against the persisted
+  baseline. Rewriting feature ids, descriptions, categories, steps, count, or
+  order is rejected and retried; only `passes` and `evidence` may change.
+- **Completion guard**: if the decision says `complete` but
+  `feature-list.json` still has `passes:false` entries, the controller
+  rewrites the decision to `continue` with a synthetic `nextStep`
+  pointing at the first pending feature. The harness will not allow
+  premature "done".
+- **Cross-session resume**: `GrubTaskState` is written atomically to
+  `state.json` on every transition. On the next session, `session_start`
+  calls `discoverActiveTasks()` and adopts the most recent running task
+  without auto-dispatching — the user types `/grub resume` to continue.
+- **Safety limits**: 25 iterations and 3 consecutive failures by default;
+  override with `--max-iter` / `--max-fail`.
+- **Stale harness cleanup**: on extension load, terminal harnesses older
+  than 30 days are pruned from `.grub/`.
+
+## Legacy migration
+
+Earlier versions wrote `feature-checklist.md` (markdown checkboxes). When a
+new iteration starts and `feature-list.json` is missing but the legacy file
+exists, its checkbox items are migrated into the JSON format (category
+defaults to `functional`; `steps` start empty so the initializer can refine
+later).
+
+## Related
+
+For the recurring scheduler that runs prompts or slash commands on an
+interval, see the sibling [`loop` extension](../loop/README.md).

package/dist/extensions/builtin/link-world/agent-workspace/README.md

@@ -1,16 +1,16 @@
-# Link-world Workspace
-
-This directory is copied to:
-
-```text
-.nanopencil/link-world-workspace/
-```
-
-Use it to store project-local, reusable internet-access knowledge for NanoPencil.
-
-Suggested layout:
-
-- `domain-skills/<site>/...` for durable site-specific notes
-- `notes/` for broader task or provider observations that should not live in the shipped extension
-
-Keep public-safe content only. Do not store secrets, cookies, tokens, or user-specific private data here.
+# Link-world Workspace
+
+This directory is copied to:
+
+```text
+.nanopencil/link-world-workspace/
+```
+
+Use it to store project-local, reusable internet-access knowledge for NanoPencil.
+
+Suggested layout:
+
+- `domain-skills/<site>/...` for durable site-specific notes
+- `notes/` for broader task or provider observations that should not live in the shipped extension
+
+Keep public-safe content only. Do not store secrets, cookies, tokens, or user-specific private data here.

package/dist/extensions/builtin/link-world/internet-search/internet-search.md

@@ -1,65 +1,65 @@
----
-name: internet-search
-description: 当用户需要联网搜索最新信息、新闻、在线内容时使用此技能。包括搜索 Twitter、YouTube、Bilibili、知乎、微博、小红书等平台。
----
-
-# 互联网搜索
-
-## 触发条件
-
-当用户请求以下内容时使用此技能：
-- 搜索互联网、联网搜索、网络搜索
-- 查找最新新闻、资讯、信息
-- 搜索 YouTube、Bilibili、Twitter、小红书、微博等内容
-- 查找某个话题的最新讨论
-- 获取实时信息或热点内容
-
-## 执行步骤
-
-### 步骤 1：检查 agent-reach 是否安装
-
-运行以下命令检查 agent-reach 是否可用：
-
-```bash
-agent-reach --version
-```
-
-### 步骤 2：如果未安装
-
-如果 agent-reach 命令不可用，告知用户需要先安装：
-
-> link-world (agent-reach) 未安装。请先运行 `/link-world` 安装 agent-reach 以支持联网搜索功能。
-
-### 步骤 3：如果已安装
-
-根据用户需求，使用 linkworld.md 中定义的工具进行搜索。
-
-**完整命令参考请查阅：extensions/link-world/linkworld.md**
-
-| 场景 | 推荐工具 | 示例命令 |
-|------|----------|----------|
-| 搜索 Twitter/X 推文 | xreach | `xreach search "关键词" --json` |
-| 解析 YouTube 视频 | yt-dlp | `yt-dlp --dump-json "视频URL"` |
-| 解析 Bilibili 视频 | yt-dlp | `yt-dlp --dump-json "视频URL"` |
-| 搜索 Reddit 帖子 | curl | `curl -s "https://reddit.com/r/xxx/search.json?q=关键词"` |
-| 搜索 GitHub 仓库 | gh | `gh search repos "关键词" --limit 5` |
-| 读取网页内容 | curl + Jina | `curl -s "https://r.jina.ai/网页URL"` |
-| 通用搜索引擎 | Exa (MCP) | `mcporter call 'exa.web_search_exa(query: "关键词", num_results: 5)'` |
-| 搜索小红书笔记 | 小红书 (MCP) | `mcporter call 'xiaohongshu.search_feeds(keyword: "关键词", limit: 5)'` |
-| 解析抖音视频 | 抖音 (MCP) | `mcporter call 'douyin.parse_douyin_video_info(url: "视频URL")'` |
-
-### 步骤 4：返回结果
-
-将搜索结果整理后返回给用户，包括：
-- 来源平台
-- 标题
-- 内容摘要
-- 链接
-
-## 注意事项
-
-1. 遵守平台的 API 使用规范
-2. 如需登录平台的搜索功能，确保用户已配置认证信息
-3. 如果搜索失败，尝试其他平台或告知用户可能的错误原因
-4. YouTube/Bilibili 需要提供具体的视频 URL，不能直接搜索关键词
-5. 详细的配置说明（Cookie、代理等）请参考 linkworld.md
+---
+name: internet-search
+description: 当用户需要联网搜索最新信息、新闻、在线内容时使用此技能。包括搜索 Twitter、YouTube、Bilibili、知乎、微博、小红书等平台。
+---
+
+# 互联网搜索
+
+## 触发条件
+
+当用户请求以下内容时使用此技能：
+- 搜索互联网、联网搜索、网络搜索
+- 查找最新新闻、资讯、信息
+- 搜索 YouTube、Bilibili、Twitter、小红书、微博等内容
+- 查找某个话题的最新讨论
+- 获取实时信息或热点内容
+
+## 执行步骤
+
+### 步骤 1：检查 agent-reach 是否安装
+
+运行以下命令检查 agent-reach 是否可用：
+
+```bash
+agent-reach --version
+```
+
+### 步骤 2：如果未安装
+
+如果 agent-reach 命令不可用，告知用户需要先安装：
+
+> link-world (agent-reach) 未安装。请先运行 `/link-world` 安装 agent-reach 以支持联网搜索功能。
+
+### 步骤 3：如果已安装
+
+根据用户需求，使用 linkworld.md 中定义的工具进行搜索。
+
+**完整命令参考请查阅：extensions/link-world/linkworld.md**
+
+| 场景 | 推荐工具 | 示例命令 |
+|------|----------|----------|
+| 搜索 Twitter/X 推文 | xreach | `xreach search "关键词" --json` |
+| 解析 YouTube 视频 | yt-dlp | `yt-dlp --dump-json "视频URL"` |
+| 解析 Bilibili 视频 | yt-dlp | `yt-dlp --dump-json "视频URL"` |
+| 搜索 Reddit 帖子 | curl | `curl -s "https://reddit.com/r/xxx/search.json?q=关键词"` |
+| 搜索 GitHub 仓库 | gh | `gh search repos "关键词" --limit 5` |
+| 读取网页内容 | curl + Jina | `curl -s "https://r.jina.ai/网页URL"` |
+| 通用搜索引擎 | Exa (MCP) | `mcporter call 'exa.web_search_exa(query: "关键词", num_results: 5)'` |
+| 搜索小红书笔记 | 小红书 (MCP) | `mcporter call 'xiaohongshu.search_feeds(keyword: "关键词", limit: 5)'` |
+| 解析抖音视频 | 抖音 (MCP) | `mcporter call 'douyin.parse_douyin_video_info(url: "视频URL")'` |
+
+### 步骤 4：返回结果
+
+将搜索结果整理后返回给用户，包括：
+- 来源平台
+- 标题
+- 内容摘要
+- 链接
+
+## 注意事项
+
+1. 遵守平台的 API 使用规范
+2. 如需登录平台的搜索功能，确保用户已配置认证信息
+3. 如果搜索失败，尝试其他平台或告知用户可能的错误原因
+4. YouTube/Bilibili 需要提供具体的视频 URL，不能直接搜索关键词
+5. 详细的配置说明（Cookie、代理等）请参考 linkworld.md

package/dist/extensions/builtin/link-world/link-world-agent.md

@@ -1,82 +1,82 @@
----
-name: link-world
-description: Built-in internet access bridge for NanoPencil. Use when a task needs agent-reach backed web search, browsing, or remote internet actions.
----
-
-# Link-world
-
-NanoPencil exposes link-world as first-class tools. Prefer these tools over calling `agent-reach` through `bash`.
-
-## Tool Selection
-
-- Use `web_search` for ordinary search and lightweight web research, but only if the tool is available in the current session.
-- Use `web_fetch` when you already have the target URL and need its content, but only if the tool is available in the current session.
-- Use `link_world_admin` first when you need setup status, version, install help, or diagnostics.
-- Use `link_world_exec` only when you need a lower-level `agent-reach` command that `web_search` does not model.
-- If the task is about interacting with a live page rather than retrieving knowledge, switch to the `browser` tool family instead of forcing link-world.
-- Do not hand-build shell strings for `agent-reach` unless the dedicated tools are unavailable.
-
-## Recommended Flow
-
-1. Check readiness with `link_world_admin` action `status` or `doctor`.
-2. If the runtime is missing, use `link_world_admin` action `install_help` or `/link-world install`.
-3. If `web_search` is available, use it for ordinary search.
-4. If `web_fetch` is available and the exact URL is already known, use it.
-5. If high-level link-world tools are unavailable, call `link_world_exec` with explicit argv-style arguments.
-6. Prefer bundled site or domain skills before inventing a new web workflow.
-
-## Examples
-
-Admin:
-
-```json
-{
-  "action": "status"
-}
-```
-
-Execution:
-
-High-level search:
-
-```json
-{
-  "query": "OpenAI Responses API"
-}
-```
-
-```json
-{
-  "query": "Playwright file upload",
-  "provider": "web",
-  "limit": 5
-}
-```
-
-High-level fetch:
-
-```json
-{
-  "url": "https://example.com/docs"
-}
-```
-
-Lower-level execution:
-
-```json
-{
-  "args": ["doctor"]
-}
-```
-
-```json
-{
-  "args": ["search", "OpenAI Responses API"]
-}
-```
-
-## Notes
-
-- Pass `args` as an array of tokens, not as one shell command string.
-- If `agent-reach` is not installed, the tools will return install guidance.
-- Keep NanoPencil as the integration boundary: diagnostics through `link_world_admin`, search through `web_search`, direct retrieval through `web_fetch`, lower-level execution through `link_world_exec`.
+---
+name: link-world
+description: Built-in internet access bridge for NanoPencil. Use when a task needs agent-reach backed web search, browsing, or remote internet actions.
+---
+
+# Link-world
+
+NanoPencil exposes link-world as first-class tools. Prefer these tools over calling `agent-reach` through `bash`.
+
+## Tool Selection
+
+- Use `web_search` for ordinary search and lightweight web research, but only if the tool is available in the current session.
+- Use `web_fetch` when you already have the target URL and need its content, but only if the tool is available in the current session.
+- Use `link_world_admin` first when you need setup status, version, install help, or diagnostics.
+- Use `link_world_exec` only when you need a lower-level `agent-reach` command that `web_search` does not model.
+- If the task is about interacting with a live page rather than retrieving knowledge, switch to the `browser` tool family instead of forcing link-world.
+- Do not hand-build shell strings for `agent-reach` unless the dedicated tools are unavailable.
+
+## Recommended Flow
+
+1. Check readiness with `link_world_admin` action `status` or `doctor`.
+2. If the runtime is missing, use `link_world_admin` action `install_help` or `/link-world install`.
+3. If `web_search` is available, use it for ordinary search.
+4. If `web_fetch` is available and the exact URL is already known, use it.
+5. If high-level link-world tools are unavailable, call `link_world_exec` with explicit argv-style arguments.
+6. Prefer bundled site or domain skills before inventing a new web workflow.
+
+## Examples
+
+Admin:
+
+```json
+{
+  "action": "status"
+}
+```
+
+Execution:
+
+High-level search:
+
+```json
+{
+  "query": "OpenAI Responses API"
+}
+```
+
+```json
+{
+  "query": "Playwright file upload",
+  "provider": "web",
+  "limit": 5
+}
+```
+
+High-level fetch:
+
+```json
+{
+  "url": "https://example.com/docs"
+}
+```
+
+Lower-level execution:
+
+```json
+{
+  "args": ["doctor"]
+}
+```
+
+```json
+{
+  "args": ["search", "OpenAI Responses API"]
+}
+```
+
+## Notes
+
+- Pass `args` as an array of tokens, not as one shell command string.
+- If `agent-reach` is not installed, the tools will return install guidance.
+- Keep NanoPencil as the integration boundary: diagnostics through `link_world_admin`, search through `web_search`, direct retrieval through `web_fetch`, lower-level execution through `link_world_exec`.