@armadra/agent 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ English · [简体中文](CHANGELOG.zh-CN.md)
 > This file is in English starting with 0.6.0. Release notes for 0.1 through 0.5.1 are in Chinese in
 > [CHANGELOG.zh-CN.md](CHANGELOG.zh-CN.md). New entries go into both files.
 
+## 0.11.0 (2026-10-30)
+
+### Tools and permissions
+
+- **`web_fetch`**: a new built-in tool in the `default` preset that GETs one public http(s) URL and returns its main content as Markdown (HTML, zero-dependency converter), pretty JSON or plain text; binaries are not parsed. Output is cut at `maxChars` (50 000 by default) with `offset` to continue, the full text goes to `outputs/`, and the first line marks the content as untrusted. Same-host redirects are followed (≤ 5, re-checked per hop), cross-host ones are reported. 30 s total / 15 s first byte / 5 MB body. Search is not included (#232).
+- **Permission class `network`**: `web_fetch` asks in Manual / Accept edits (the second option becomes "allow `<host>` for this session"), asks in Plan, is denied under `-p` unless an allow rule matches, goes to the classifier in Auto and is allowed in Bypass. Rules `web_fetch(<pattern>)` match `host/path`; a bare domain covers its subdomains. Whatever the mode, local host names, private, link-local and cloud-metadata addresses (every resolved address, IPv4-mapped forms included) are refused and the connection is pinned to the checked address. No new config keys: turn it off with `tools.disabled: ["web_fetch"]`, `tools.default: ["-web_fetch"]` or `permission.deny`. The exported `ToolPermission` type gains `"network"`; protocol constants are unchanged.
+- **Hooks**: matcher `web_fetch(...)` matches against the `url`.
+- **Commands follow capabilities**: `/memory` is listed only when memory is enabled and `/tasks` only when task can be called (directly or from codemode), in `/help`, completion and RPC `get_commands`; typing them still answers as before. A new contract test (`src/cli/capability-off.test.ts`) locks that switching off memory, codemode, task, todo or `web_fetch` removes it from the tool table, prompt sections and rules, codemode `ALL_TOOLS`, the command list and sub-session tools, and that the request prefix is byte-identical to a build without it (#232).
+- **Prompt budgets**: `default` grows by about 120 tokens (≈ 1 600 with codemode); the `codemode-only` limit rises from 1 775 to 1 900 (measured 1 835, the `web_fetch` declaration is inlined) and `default` + task gets its own 2 150 limit (measured 2 116). Sessions resumed from an older version miss the cache once.
+
+### Host adapter
+
+- **Runner done event (host-api 1.1)**: `HostApi.runners.onDone(handler)` is called with a `RunnerDoneEvent` (`runner`, `taskId?`, `sessionId`, `round`, `status`, `isError`, `text?` / `error?`, `startedAt`, `endedAt`, `durationMs`) whenever a round of a host-injected runner ends, so hosts no longer need to poll for task completion; handlers only observe and a throw is just logged. Adds the minor version `HOST_API_MINOR = 1` and `api.minor`; `HOST_API_VERSION` stays 1, existing hosts are unaffected, and hosts detect the feature with `typeof api.runners?.onDone === "function"`. Docs: docs/reference/host-api.md "Versioning" and "Runner done event" (#226).
+
+### Docs
+
+- docs/guides/hooks.md gains "Scope" (task sub-sessions do not fire SessionStart / SessionEnd; calls inside external agents bypass hooks) and "Hooking up each capability" (which event and matcher `web_fetch`, sub-agent start / end, background tasks, external agents and codemode orchestration use, with a hooks.json and two script examples); docs/guides/agents.md "Configuration" gains a three-line per-role model example (#227).
+
 ## 0.10.0 (2026-10-23)
 
 Version aligned with Armadra and armadra-cloud (all three ship 0.10.0); protocol constants unchanged. Nothing else was merged after 0.9.3.

package/CHANGELOG.zh-CN.md

@@ -4,6 +4,24 @@
 
 > 从 0.6.0 起 [CHANGELOG.md](CHANGELOG.md) 为英文，本文件保留中文记录（0.1–0.5.1 的完整历史在此）。新条目两份都要加。
 
+## 0.11.0（2026-10-30）
+
+### 工具与权限
+
+- **`web_fetch`**：`default` 预设新增的内置工具，GET 一个公网 http(s) URL，HTML 取正文转 Markdown（零依赖转换器）、JSON 美化、文本原样，二进制不解析。输出缺省截到 `maxChars`（50 000），用 `offset` 续读，全文落 `outputs/`，首行标注内容不可信。同主机重定向自动跟（≤ 5 跳、逐跳重检），跨主机只报告。总超时 30 s、首字节 15 s、正文 ≤ 5 MB。不含搜索（#232）。
+- **权限类 `network`**：`web_fetch` 在 Manual / Accept edits 下询问（第二项变成「本会话允许 `<主机>`」），Plan 下询问，`-p` 下除非命中 allow 规则一律拒绝，Auto 交分类器，Bypass 放行。规则 `web_fetch(<pattern>)` 对 `host/path` 匹配，裸域名含子域。无论哪种模式，本机名、私网、链路本地与云元数据地址（解析出的每个地址，含 IPv4 映射形式）都被拒绝，连接钉在检查过的地址上。不新增配置键：用 `tools.disabled: ["web_fetch"]`、`tools.default: ["-web_fetch"]` 或 `permission.deny` 关闭。导出的 `ToolPermission` 类型多 `"network"`；协议常量不变。
+- **Hook**：matcher `web_fetch(...)` 对 `url` 匹配。
+- **命令表跟随能力**：`/memory` 只在记忆开启时、`/tasks` 只在能调用 task（直接或经 codemode）时出现在 `/help`、补全与 RPC `get_commands` 里；直接输入时回应照旧。新增契约测试 `src/cli/capability-off.test.ts`：关掉 memory、codemode、task、todo 或 `web_fetch` 后，工具表、系统提示的节与规则句、codemode `ALL_TOOLS`、命令表、子会话活动集里都不再有它，且请求前缀与没有该能力时逐字节相同（#232）。
+- **提示预算**：`default` 增加约 120 token（含 codemode 约 1 600）；`codemode-only` 上限由 1 775 放宽到 1 900（实测 1 835，内联了 `web_fetch` 声明），`default` + task 单列上限 2 150（实测 2 116）。从旧版本续接的会话首个请求缓存未命中一次。
+
+### 宿主适配器
+
+- **runner 完成事件（host-api 1.1）**：`HostApi.runners.onDone(handler)` 在宿主注入的 runner 每轮结束时以 `RunnerDoneEvent`（`runner`、`taskId?`、`sessionId`、`round`、`status`、`isError`、`text?` / `error?`、`startedAt`、`endedAt`、`durationMs`）回调，宿主不必再轮询任务是否结束；处理器只观察，抛错只记日志。新增小版本 `HOST_API_MINOR = 1` 与 `api.minor`；`HOST_API_VERSION` 仍为 1，旧宿主不受影响，按 `typeof api.runners?.onDone === "function"` 探测。文档：docs/reference/host-api.md「版本」「runner 完成事件」（#226）。
+
+### 文档
+
+- docs/guides/hooks.md 加「范围」（task 子会话不触发 SessionStart / SessionEnd、外部 Agent 内部调用不经 Hook）与「按能力接入」（`web_fetch`、子 Agent 开始 / 结束、后台任务、外部 Agent、codemode 编排各自用哪个事件与 matcher，附 hooks.json 与两个脚本示例）；docs/guides/agents.md「配置」加按角色选模型的三行示例（#227）。
+
 ## 0.10.0（2026-10-23）
 
 版本号与 Armadra、armadra-cloud 对齐（三个产品统一为 0.10.0），协议常量无变化。0.9.3 之后没有其他合入。

package/README.md

@@ -196,6 +196,11 @@ await session.dispose();
 every mode. On macOS (`sandbox-exec`) and Linux (bubblewrap) an OS sandbox isolates codemode and, optionally, bash; Windows has none. See
 [permissions](docs/en/guides/permissions.md) and [sandbox](docs/guides/sandbox.md) (Chinese).
 
+- **Reading the web**: the built-in `web_fetch` reads one public http(s) page as Markdown (there is no search). It has
+  its own permission class, `network`: Manual asks (with "allow this host for this session"), `-p` denies, and
+  `--allow 'web_fetch(example.com)'` allows by domain; local, private and cloud-metadata addresses are refused in every
+  mode. Turn it off with `tools.disabled: ["web_fetch"]`. See [permissions](docs/en/guides/permissions.md), "Network class".
+
 The interface is available in English and Chinese (`--lang`, `AMA_LANG` or `ui.language`); text sent to the model is
 always English, so requests are byte-identical in both languages.
 

package/README.zh-CN.md

@@ -190,6 +190,10 @@ await session.dispose();
 Linux（bubblewrap）上有操作系统级沙箱隔离 codemode，bash 可选接入；Windows 没有。见[权限](docs/guides/permissions.md)与
 [沙箱](docs/guides/sandbox.md)。
 
+- **联网读取**：内置 `web_fetch` 把一个公网 http(s) 页面读成 Markdown（不做搜索）。它单独一类权限 `network`：Manual 下
+  询问（可选「本会话允许该主机」），`-p` 下拒绝，用 `--allow 'web_fetch(example.com)'` 按域名放行；本机、私网与云元数据
+  地址在任何模式下都被拒绝。不需要时 `tools.disabled: ["web_fetch"]`。见[权限](docs/guides/permissions.md)「网络类」。
+
 界面有中文与英文两种（`--lang`、`AMA_LANG` 或 `ui.language`）；发给模型的文本始终是英文，两种界面语言下请求逐字节相同。
 
 ## 文档