@cr1ms0n/pi-subagent 0.9.0 → 0.10.0

package/README.zh-CN.md

@@ -0,0 +1,132 @@
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+# Pi Smart Subagents
+
+在 [Pi](https://pi.dev/) 中运行独立子代理，由 Jev 为每项任务选择执行模型和具体工具。
+
+npm 包名为 `@cr1ms0n/pi-subagent`。本项目是 Luke Parke 的 `@parke.dev/pi-subagent` 0.8.0 的独立社区分支，上游来自 [LukasParke/pi-extensions](https://github.com/LukasParke/pi-extensions/tree/main/packages/pi-subagent)，并非上游官方发行版。原始 MIT 许可证和版权声明均予以保留。
+
+上游扩展提供子进程引擎、命名代理、后台任务、工作树和用量统计。本分支增加了强制 Jev 模型与工具选择，并在发送任务前核验子进程实际采用的模型和工具权限。
+
+---
+
+<a id="quick-start"></a>
+### 安装与快速开始
+
+需要 Node.js 22.19.0 或更高版本，以及已安装、已配置可用模型提供方的 Pi CLI。Pi 0.86.0 是已验证的宿主基线，能够执行内置工具、扩展工具和延迟注册工具的允许列表。若宿主无法核验所选能力，扩展会拒绝启动，不会扩大工具权限。
+
+**1. 安装已发布的软件包。**
+
+安装精确的 `0.10.0` 版本。较早的 `0.9.0` 使用旧的 `apiKeyEnv` 配置契约，不接受 `apiKey`：
+
+```bash
+pi install npm:@cr1ms0n/pi-subagent@0.10.0
+```
+
+Pi 会直接加载这个软件包。不要同时启用本扩展的其他副本或 `@parke.dev/pi-subagent`，它们会注册同名工具。本包提供 `subagent`、`subagent_wait`、`/subagents`、`/subagent-cost` 和 `/btw`。
+
+**2. 将 TypeSafe 凭据保存到私有配置。**
+
+在用户级 `~/.pi/subagent.json` 中设置 `jevRouting.apiKey`，格式如下。如果从 `0.9.0` 升级，请在启动新任务前将 `jevRouting.apiKeyEnv` 中的现有值移到 `jevRouting.apiKey`，并删除旧字段。不要把密钥放进聊天或仓库文件。配置文件以明文保存密钥，需要限制文件访问权限并保护备份。迁移与安全说明见[凭据配置](docs/REFERENCE.md#credential-setup)。子模型所需的提供方认证需要另行在 Pi 中配置。
+
+**3. 配置候选模型。**
+
+将下面的配置加入 `~/.pi/subagent.json`，保留其他已有设置。把示例模型 ID 替换为当前 Pi 中可用的精确 `provider/model-id`，并自行描述模型特点。如果存在旧的 `modelPolicy` 配置，需要将其移除；扩展不会自动迁移。
+
+```json
+{
+  "jevRouting": {
+    "selectorModel": "jev-latest",
+    "apiKey": "<your-typesafe-api-key>",
+    "timeoutMs": 15000,
+    "models": [
+      {
+        "model": "<provider/model-id>",
+        "description": "Describe this model's strengths and the tasks you want it to handle."
+      }
+    ]
+  }
+}
+```
+
+将 `apiKey` 占位符替换为自己的 TypeSafe 密钥，并移除旧的 `apiKeyEnv` 字段。扩展不会回退读取环境变量，也不会自动迁移。模型描述可以使用中文。可选的 thinking 默认值、profile 默认值和限制见[配置参考](docs/REFERENCE.md#configuration)。
+
+Jev 选择可能产生 TypeSafe 费用。它会接收委派任务文本、模型 ID 与描述、候选工具名称与描述，以及必要约束；不会自动上传仓库文件或对话历史，但任务中主动包含的文本仍可能泄露敏感信息。`action: "plan"` 同样会调用 Jev，之后实际执行时还会重新选择。
+
+**4. 启动 Pi，委派一个只读任务。**
+
+启动 Pi；如果刚切换扩展代码，需要重新加载或重启。加载 `0.10.0` 后，每次新任务都会重新读取配置，修改 `apiKey` 不需要更新 shell 环境变量。
+
+```bash
+pi
+```
+
+让主代理使用 `subagent`，例如传入下面的请求：
+
+```json
+{
+  "task": "Read README.md and summarize what this package does.",
+  "description": "Summarize the README",
+  "profile": "explore",
+  "tools": ["read"],
+  "max_turns": 4,
+  "timeout_ms": 120000,
+  "max_retries": 0
+}
+```
+
+不要传入 `model` 或 `fallback_models`。Jev 从配置的模型列表和允许的工具中进行选择；路由失败会阻止本次新任务启动，不会改用兜底方案。已有任务的管理操作不依赖路由凭据。
+
+---
+
+<a id="delegation"></a>
+### 任务委派
+
+- **模型与工具路由：**本分支让 Jev 根据任务和模型描述进行匹配，逐个选择工具；本地权限检查和子进程启动核验负责落实选择结果。
+- **命名代理与并行工作：**上游引擎支持可复用的代理角色和并发子进程。本分支为每个新子代理执行 Jev 路由，代理文件不能固定其模型或工具选择。
+- **后台任务：**上游引擎支持状态查询、可中断等待、取消和中途指导。本分支会显示所选模型，并在展开结果中展示工具详情。
+- **隔离修改：**上游工作树机制支持检查、应用或丢弃改动，避免并行代理共用同一个可写工作区。
+- **结构化结果与预算：**上游引擎在父进程中校验结构化输出，并保留部分工作成果。本分支始终使用已选定的模型和工具集进行重试，单独统计选择器 token。
+
+后台任务设置 `async: true`，之后使用 `subagent_wait` 或 `action: "wait"` 收取结果。中断等待或等待超时不会取消子代理，需要停止任务时使用 `action: "cancel"`。通过 `/subagents` 检查任务，通过 `/subagent-cost` 查看用量。
+
+[使用参考](docs/REFERENCE.md#quick-usage)涵盖并行任务、结果汇总、恢复与分叉、结构化输出、预算，以及工作树的 diff/apply/discard 操作。[TUI 指南](docs/UX.md)介绍任务查看器和键盘操作。
+
+---
+
+<a id="permissions-and-costs"></a>
+### 权限与费用
+
+| Profile | 工具选择 | 修改项目文件 |
+| --- | --- | --- |
+| `explore` | Jev 选择的本地允许的只读工具，加上可用的 Pi 上下文控制工具 | 不允许 |
+| `review` | 与 explore 相同的只读策略 | 不允许 |
+| `general` | Jev 选择的本地允许的工具，加上可用的 Pi 上下文控制工具 | 选中可写工具时可以修改 |
+
+单任务默认使用 `general`，并行任务默认使用 `explore`。显式传入的 `tools` 列表限定候选工具范围。即使传入 `tools: []`，本地仍会补充可用的 Pi 上下文管理工具。工具选择为空绝不表示允许所有工具。
+
+Profile 是工具选择策略，不是操作系统沙箱。子进程继承主进程环境，也能读取同一用户有权访问的文件，包括私有配置。工作树只隔离代码工作区。委派不可信任务前，请阅读[安全模型](docs/SECURITY.md)。
+
+用量账本分别记录主代理、子代理、路由和合计用量。TypeSafe 只报告路由 token，不报告金额，因此选择器费用标记为**未报告**，不代表免费。`max_cost` 限制子代理执行时由提供方报告的费用，不限制 TypeSafe 费用。结果交付、重试和会话分支的统计规则见[费用统计](docs/COST-ACCOUNTING.md)。
+
+扩展管理的新任务只支持 Pi 后端，原生 Codex/Claude 后端请求会被拒绝。[底层 SDK](docs/REFERENCE.md#using-the-runner-as-a-library)是另一套显式任务规格 API，不会自动调用 Jev，嵌入方需要自行负责模型和工具选择。
+
+---
+
+<a id="development"></a>
+### 开发
+
+源码是使用 peer dependencies 的独立 TypeScript 包，没有构建步骤，也没有随仓库提供的测试运行器或类型检查脚本。本仓库支持的检查方式见[开发与验证](docs/DEVELOPMENT.md)。语法转换不等于语义类型检查；`npm pack --dry-run --ignore-scripts --json` 用于检查打包内容，不会发布包。
+
+[架构约定](docs/ARCHITECTURE.md)记录模块职责和不变量。[发布维护](docs/RELEASING.md)说明如何选择性更新源码，以及需要单独明确授权的 npm 发布流程。
+
+---
+
+<a id="license"></a>
+### 许可证
+
+[MIT](LICENSE)。Copyright (c) 2026 Luke Parke。社区分支由 cr1ms0n（awoaCrim）维护。重新分发时请保留原始版权声明和许可证。
+
+译自 [README.md](README.md)，英文文件 blob：`02294faabd946a50be23551e43e694451628bc39`。中英文内容如有差异，以英文为准。
+
+感谢 [Linux.do](https://linux.do/)。

package/docs/DEVELOPMENT.md

@@ -0,0 +1,124 @@
+# Development and verification
+
+This is a standalone ESM TypeScript package loaded by Pi, not the upstream monorepo. Start with the [README](../README.md) for installation and the [architecture contract](ARCHITECTURE.md) before changing engine behavior.
+
+---
+
+### Checkout and runtime
+
+[package.json](../package.json) declares Node.js 22.19.0 or newer and Pi/TypeBox peer dependencies. There is no compiled distribution or build step. The extension entry is [extensions/subagent.ts](../extensions/subagent.ts); the supported SDK exports are in [src/index.ts](../src/index.ts).
+
+To use a local checkout, replace the example path with your own:
+
+```bash
+pi install /absolute/path/to/pi-smart-subagents
+```
+
+Pi registers a local path without copying it. Do not enable that checkout and another copy of the same extension together. Reload or restart Pi after package changes. Keep user settings, provider credentials and real session files outside the repository.
+
+The product skill at [skills/subagent/SKILL.md](../skills/subagent/SKILL.md) is distributed with the package. Maintainer-specific agents, workflows, task records and local verification artifacts are not required to use or inspect the public source.
+
+---
+
+### Source ownership
+
+| Responsibility | Owner |
+| --- | --- |
+| Pi registration and lifecycle wiring | [extension.ts](../src/extension.ts) |
+| Request schema, permission checks and normalization | [schema.ts](../src/schema.ts), [policy.ts](../src/policy.ts), [config.ts](../src/config.ts), [agents.ts](../src/agents.ts) |
+| Jev transport, candidate policy and dispatch | [routing-types.ts](../src/routing-types.ts), [routing-policy.ts](../src/routing-policy.ts), [jev-router.ts](../src/jev-router.ts), [dispatch-routing.ts](../src/dispatch-routing.ts) |
+| Local preflight and child capability verification | [dispatch-preflight.ts](../src/dispatch-preflight.ts), [startup-check.ts](../src/startup-check.ts), [child-preflight.ts](../src/child-preflight.ts) |
+| Child processes, retries and protocol | [runner.ts](../src/runner.ts), [orchestrator.ts](../src/orchestrator.ts), [protocol.ts](../src/protocol.ts), [backend adapters](../src/backends/) |
+| Concurrency, ownership and durable worktrees | [semaphore.ts](../src/semaphore.ts), [process-lock.ts](../src/process-lock.ts), [registry.ts](../src/registry.ts), [worktree.ts](../src/worktree.ts) |
+| Persistence, accounting and output | [persistence.ts](../src/persistence.ts), [usage.ts](../src/usage.ts), [output.ts](../src/output.ts), [structured.ts](../src/structured.ts) |
+| TUI, notifications and transcript display | [format.ts](../src/format.ts), [ui.ts](../src/ui.ts), [notifications.ts](../src/notifications.ts), [transcript.ts](../src/transcript.ts) |
+
+Keep engine rules in their owning modules. The extension is a composition root, and renderers consume narrow projections rather than owning a second run store. The architecture document covers the remaining modules and invariants.
+
+---
+
+### Checks available in this checkout
+
+There are no npm scripts, devDependencies, TypeScript project configuration or bundled test suite. `npm test`, `npm run typecheck` and the upstream release-check scripts are not available here. Installing dependencies alone does not create those commands. The historical [plan](PLAN.md) and [roadmap](ROADMAP.md) refer to upstream tooling and previous release work.
+
+#### Documentation and whitespace
+
+Review the English and Chinese READMEs together: commands, config keys, feature claims, language links, anchors and license references must agree. Check links against the intended public Git tree, not only files that happen to exist in a maintainer's checkout. Keep the English-source blob reference in the Chinese README current when changing the translation.
+
+For tracked changes:
+
+```bash
+git diff --check
+```
+
+For a prepared commit:
+
+```bash
+git diff --cached --check
+```
+
+These commands do not check Markdown links, translation accuracy or untracked files. Review those separately. Documentation-only changes do not require a provider call or a claim that engine tests passed.
+
+#### Offline TypeScript syntax check
+
+When the global Pi installation includes esbuild, the following Bash/Git Bash command enumerates production TypeScript files, parses and strips their types, and writes only to a unique temporary directory. It removes that directory afterward. It does not download a tool or modify source files.
+
+```bash
+node --input-type=module - "$(npm root -g)" <<'NODE'
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const esbuild = path.join(process.argv[2], "@earendil-works/pi-coding-agent/node_modules/esbuild/bin/esbuild");
+if (!fs.existsSync(esbuild)) throw new Error("Global Pi esbuild is unavailable; no syntax check was run.");
+const files = [];
+function walk(dir) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const file = path.join(dir, entry.name);
+    if (entry.isDirectory()) walk(file);
+    else if (file.endsWith(".ts")) files.push(file);
+  }
+}
+walk("src");
+walk("extensions");
+const outputDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-syntax-"));
+try {
+  for (const file of files.sort()) {
+    const result = spawnSync(process.execPath, [esbuild, file, "--loader:.ts=ts", "--format=esm",
+      "--target=node22", `--outfile=${path.join(outputDir, "check.js")}`], { stdio: "inherit" });
+    if (result.error) throw result.error;
+    if (result.status !== 0) throw new Error(`Syntax transform failed for ${file}`);
+  }
+  process.stdout.write(`Parsed ${files.length} TypeScript files; no semantic typechecking performed.\n`);
+} finally {
+  fs.rmSync(outputDir, { recursive: true, force: true });
+}
+NODE
+```
+
+This catches malformed TypeScript only. It does not resolve imports, check types or validate peer APIs. If your Pi installation does not expose that esbuild path, report the missing check rather than claiming success or installing new tooling silently.
+
+A semantic typecheck requires a separately configured TypeScript environment and compatible peers. There is no repository-owned command for it here. Any external harness or isolated fixture run must be reported with its actual setup, scope and limitations; private maintainer fixtures are not a test suite shipped in this checkout.
+
+#### Package contents
+
+Review the npm file list without generating or publishing a tarball:
+
+```bash
+npm pack --dry-run --ignore-scripts --json
+```
+
+The output should contain production source, the distributed skill, public documentation, both READMEs, changelog, license and package metadata. It must not contain local settings, agent instructions, tasks, backups, transcripts, credentials, tarballs or generated test bundles. Git exclusions and the package `files` allowlist are separate controls; inspect both when changing packaging.
+
+A dry run verifies packaging, not application behavior. For an actual release, follow the additional artifact and installation checks in [release maintenance](RELEASING.md).
+
+---
+
+### Behavior verification
+
+For engine changes, trace the affected architecture invariants and exercise the owned boundary with an injected transport, fake process or isolated host when such a harness is available. State what was exercised and keep paid partial output/accounting semantics intact.
+
+A real `subagent` call and `action: "plan"` both invoke Jev and may incur charges. A plan avoids spawning a child; it is not an offline test. Obtain explicit permission before live routing/provider smoke tests, use synthetic task data and keep real user sessions out of fixtures.
+
+Report syntax transforms, semantic typechecks, package checks, fixture assertions and live-provider checks separately. Do not summarize them as “tests passed” when no test suite was run.

package/docs/PLAN.md

@@ -1,5 +1,7 @@
 # Execution plan — remaining roadmap phases
 
+> **Historical upstream plan.** Retained as design rationale for phases that shipped before this fork's Jev routing changes. Version targets, test paths and `npm run release:check` below describe the upstream monorepo, not tools available in this standalone checkout. See [the current reference](REFERENCE.md), [architecture contract](ARCHITECTURE.md) and [development checks](DEVELOPMENT.md) for the maintained behavior and verification instructions. Historical gate statements are not verification results for the current checkout.
+
 Formalization of [ROADMAP.md](./ROADMAP.md) phases 2–4 into implementable work
 items. Where the roadmap holds rationale and design sketches, this document
 holds the execution contract: exact scope, file-level work breakdown,