pi-subagent-feather 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 eggmasonvalue
+Copyright (c) 2026 Page (pi-subagent-lite modifications)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,7 @@
+This project is derived from @eggmasonvalue/pi-subagent 2.0.1.
+Upstream: https://github.com/eggmasonvalue/pi-subagent
+Upstream author/copyright: eggmasonvalue (2026), MIT license.
+Model policy validation and child metadata/resume logic are adapted from upstream.
+Changes: bounded event collector, minimal persisted parent receipt, shorter declarations,
+no automatic system guidance/guidelines injection, compact UI, lifecycle cleanup.
+Not affiliated with or endorsed by the upstream author. Not published or enabled automatically.

package/README.md

@@ -1,3 +1,150 @@
-# Temporary Holding Version
+# pi-subagent-feather
+基于 [`@eggmasonvalue/pi-subagent` 2.0.1](https://github.com/eggmasonvalue/pi-subagent) 的独立 MIT 派生版。
+npm 包名 `pi-subagent-feather`，本地目录 `D:\Work\pi-subagent-lite`。
+版本 `0.2.0`。MIT 授权，见 LICENSE / NOTICE。
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+目标：保留独立上下文、子会话存档、resume、并行、超时与实时进度；减少父会话重复数据和额外提示词。
+
+## 改了什么
+
+| 项目 | 上游 2.0.1 | Lite |
+|---|---|---|
+| 父会话 details | 全部 messages/toolActivity/args/stderr，另有 task 副本 | 小型回执；不含答案、任务、过程、参数、思考、图片和 stderr |
+| 模型可见答案 | 最大 50KiB / 2000 行 | 默认答案正文 8KiB / 200 行，另外附短状态与 session 路径 |
+| 运行时收集器 | 收集完整过程 | 只保留最近答案、当前部分答案、有界 stderr 和标量统计 |
+| 父代理 promptGuidelines | 4 条 | 无 |
+| promptSnippet | 2 条 | 无 |
+| 子代理附加系统提示词 | 每次追加指导语 | 不追加 |
+| 模型清单 | 描述、benchmark 与解释字段 | 按需返回 ID、levels、默认值和短用户备注，不重复存 details |
+| 子会话 JSONL / resume metadata | 保留 | 保留，是完整过程的唯一插件存档来源 |
+
+**不是“零 token”**：工具 schema、任务、答案、Pi 本身系统提示词、用户 AGENTS 和项目资源仍会消耗 token。
+没有自动摘要模型调用，没有新增检索工具，没有静默删旧会话。
+去掉隐藏 details 的重复内容主要节省父会话磁盘/内存；它本来不送给模型，不应算成模型 token 节省。
+
+## 实测
+
+Windows / Node 24.18.1 / Pi 0.99.1：
+- 两个工具的声明 JSON（含 schema 和原来的额外提示词字段）UTF-8 体积 **3238 → 1513 字节，减少 53.3%**。
+  这是声明字节数，不是特定提供商的精确 token 数，更不是整段会话的 token 节省率。
+- 真实 DeepSeek 新子会话 + resume：两次 `details` 分别 **602 / 616 字节**；答案只出现在 `content` 一次。
+- 多 MB 工具参数/输出、图片、思考块不会进入父会话回执。
+
+父会话内容形式仍很简单：
+
+```text
+[status=done session=C:\...\child.jsonl]
+子代理答案
+```
+
+长答案会有 `[Truncated; full text is in the child session.]`。用已有 read/bash 按需查看 JSONL，或 resume 要求返回所需部分。
+不另外创建一份全文输出日志。
+
+## 启用与冲突
+
+与原插件使用相同工具名：`subagent` 和 `subagent_models`，因此**不能同时加载两版**。
+
+本机路径：`D:\Work\pi-subagent-lite`。
+正式切换时，把 `~/.pi/agent/settings.json` 的 packages 中：
+
+```json
+"npm:@eggmasonvalue/pi-subagent"
+```
+
+替换为：
+
+```json
+"D:\\Work\\pi-subagent-lite"
+```
+
+其余配置与包顺序不变；所有窗口 `/reload` 或重启。不要只添加新路径而保留旧插件一起加载。
+这是替换加载源，不是修改第三方 node_modules。回退时恢复旧的 packages 项并 reload。
+**项目创建过程没有执行上述切换。**
+
+## 接口与使用
+
+```ts
+subagent({ task: "自包含任务和预期结果", model: "deepseek/deepseek-flash", thinking: "low", tools: ["read", "bash"] })
+subagent({ task: "继续指令", resume: "C:\\...\\child.jsonl" })
+subagent_models({})
+```
+
+- `tools` 未指定：继承父代理当前活动工具，排除 subagent/subagent_models；`[]`：无工具。
+- 要允许递归，在 tools 里明确加入 subagent。并行调用是普通并行工具调用；子代理写不同文件。
+- `model/thinking/tools/cwd` 只用于新子会话，不能与 resume 同时指定。
+- timeout / cancellation 会停止子进程树，保留已写入的子会话供 resume。
+- 超时后如何检查进度/继续，由父代理和用户决定，不再自动注入固定监督流程。
+- 进度最多每100ms更新一次，最后一批数据即使没有后续 stdout 也会发布；只显示短进度/当前工具名与数量。
+- 展开父工具结果显示答案与统计，**不再展开完整中间轨迹**；完整过程看子会话。
+- `session_shutdown`（含 reload/会话替换）会取消并等待活动子代理。执行器不在扩展工厂中启动资源。
+
+## 模型策略与旧会话
+
+沿用现有 `~/.pi/agent/pi-subagent/models-allowlist.json`，无需重写模型白名单。
+`PI_CODING_AGENT_DIR` 改变 agent-dir 基路径。默认模型、thinking、支持等级和 resume 策略仍会校验。
+模型清单保留短用户 description，省略 AA / DeepSWE benchmark 输出；policy 文件内容不被改写。
+
+新会话在 `<agent-dir>/sessions/subagent-lite/<run-id>/` 下。
+继续使用上游 version 2 的 `.jsonl.subagent.json` metadata；可 resume 上游正常保存的旧子会话。
+旧父会话已保存的重复详情**不会被这版自动清除**；需要新会话或核心存储优化才能甩掉旧历史。
+若 metadata 缺失/损坏、模型被白名单撤销、thinking 不再允许，会明确拒绝恢复，不擅自换模型。
+
+## 大小预算
+
+可选配置：`<agent-dir>/pi-subagent-feather/config.json`。每次调用读取，缺省无需文件。
+
+```json
+{
+  "resultBytes": 8192,
+  "resultLines": 200,
+  "progressBytes": 2048,
+  "stderrBytes": 4096,
+  "eventBytes": 1048576
+}
+```
+
+- result 上限作用于答案正文，状态/路径/错误说明占少量额外空间；长答案仍完整存在子会话。
+- 支持多字节 Unicode；截断不切断代理对，有界子串会脱离巨大原字符串的 backing store。
+- stdout 单个 JSON 事件超过 eventBytes 会丢弃该事件并在下一行恢复；子 JSONL 不受此限制。
+  极大最终事件被丢弃时，使用已流出的有界正文，并标记截断；统计可能仅有已流出 usage。
+- 所有预算必须是正整数；最大 resultBytes 51200 / resultLines 2000 / eventBytes 64MiB。
+- stderr 是运行期最多4KiB的尾部，失败且没有正文时供模型看；不保存在 details。
+
+其他可选键（同一 config.json，未知键直接报错防拼写）：
+
+- `"offlineChildren": true`：子进程附加 `--offline`，跳过启动时的模型目录网络刷新（更快）。适合 API key 型 provider；OAuth 型子代理凭证过期时可能需要先在主会话刷新凭证。
+- `"defaultTimeoutMs": 30000`：调用未传 `timeoutMs` 时的兜底超时，防失控子进程。
+- `"resultKeep": "tail"`：完成的答案超预算时保留结尾（结论常在末尾）；默认 `"head"`。流式进度始终保留头部。
+- `eventBytes` 默认已降为 1MiB（真实子进程事件被 Pi 自身截断在 50KiB/2000 行内，1MiB 足够），单事件超限仍丢弃并在下一行恢复。
+- 收集器解析前按事件类型做廉价预过滤，不关注的事件类型跳过 JSON.parse。
+
+## /subagents 命令
+
+`/subagents` 列出最近的子会话（时间、大小、模型、路径），纯人看界面，不进入模型上下文、零 token。
+有 UI 时可选择一条并复制其 resume 路径；无 UI（或 RPC 降级）时以通知列出。
+
+## 开发 / 验证
+
+```sh
+npm install --legacy-peer-deps
+npm run typecheck
+npm test
+node --experimental-strip-types scripts/measure-prompts.mjs <upstream-index.ts>
+```
+
+普通测试不调用模型/网络/麦克风，使用自己的临时目录和假子进程；覆盖大量输出、UTF-8、输出预算、metadata、
+resume、timeout、abort、并行、流事件恢复、usage、生命周期清理、schema 和宽窄 TUI。
+
+```sh
+npm run smoke
+```
+
+**smoke 会用现有 DeepSeek 认证发起两次极小请求**，验证真实 Pi 加载/新会话/resume；
+认证和 models 只复制到私有临时目录，测试后删除，不打印凭证、不改主设置、不使用 Codex/火山额度。
+没有 DeepSeek 认证时不要运行此项。
+
+插件没有 runtime dependencies，宿主模块仅声明 peerDependencies；开发依赖用于类型检查和离线测试。
+`npm audit --omit=dev` 为零告警。固定 Pi 0.99.1 的开发依赖树目前有 brace-expansion 的已知告警，
+不会随本插件打包，且不应通过修改用户全局 Pi 来消除本仓库的开发依赖告警。
+
+保留上游 MIT 授权与出处，见 LICENSE / NOTICE。