@arkkwang/pi-subagent 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 arkkwang
+
+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/README.md

@@ -1,3 +1,139 @@
-# Temporary Holding Version
+English | [简体中文](README.zh-CN.md)
 
-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.
+# pi-subagent
+
+An extension for the official Pi SDK that lets a main agent create independent sub-agent sessions, observe execution, send follow-up instructions, and stop tasks. Supports foreground results and background completion notifications.
+
+Uses the official `@earendil-works/pi-coding-agent` package. The current verified SDK baseline is **1.0.0**; Node.js 22.19+ is required.
+
+## Install
+
+```bash
+pi install npm:@arkkwang/pi-subagent
+```
+
+Or clone this repository and install the local package from its root:
+
+```bash
+pi install .
+```
+
+Restart Pi to load the extension. There is no standalone CLI, daemon, or second SDK installation: Pi's extension loader supplies the SDK.
+
+## Agent usage
+
+The three tools use `exposure: "deferred"`. Agents discover and load them through `tool_search`; tool definitions are not exposed by default, but the extension still initializes normally. Keep `tool_search` available; adding sub-agent tools to `defaultTools` is unnecessary.
+
+```js
+subagent_start({
+  task: "Read-only review of src/cart.js and test/cart.test.js. Report defects, evidence, and missing tests. Do not modify files.",
+  name: "Review", mode: "background"
+})
+
+subagent_observe({ id: "returned child ID" }) // Immediate snapshot
+subagent_observe({ id: "...", timeoutSeconds: 60 }) // Wait up to 60 seconds
+
+// Running: returns after steer acceptance. Idle: starts a new run in the fixed mode.
+subagent_send({ id: "...", action: "message", message: "Check that quantity=0 is not treated as missing." })
+subagent_send({ id: "...", action: "stop" })
+```
+
+- `start` requires `task`: provide context, constraints, and completion criteria. Optional `name` also sets the Pi session title; omitting it preserves Pi's first-message-based title behavior. `cwd` can be absolute or relative to the parent project. `model` uses `provider/modelId`. Defaults are the parent project/model and `mode: "background"`. Mode is fixed when the session is created and cannot be changed.
+- `send` requires `id/action`; the `message` action requires `message`. `stop` does not accept a message. There is no `start.notify`, `send.mode`, or silent mode.
+- `observe` without an ID lists all children of the current parent. Default output is the first 2000 characters of the latest assistant text. `detail: "output"` defaults to 16000 characters; paginate with `offset/limit` (maximum 32000 per call). A non-null `nextOffset` indicates more content.
+
+`timeoutSeconds` defaults to 0. Waiting requires an ID and is capped at 240 seconds, shared by runtime validation and tool schema through `OBSERVE_MAX_TIMEOUT_SECONDS` in `manager.mjs`. Single-task observations include `timedOut`. Timeout or cancellation ends only the observation, not the child task. Waiting uses completion events and one timer, not polling.
+
+Tool text is pure JSON, also exposed as `structuredContent`. Completion notifications are JSON with `event: "subagent_run_ended"`. For example, a partial result:
+
+```json
+{
+  "status": "idle",
+  "lastRunOutcome": "ended",
+  "lastRunStopReason": "length",
+  "lastOutput": "Current output..."
+}
+```
+
+This means the last run hit the output limit and is no longer executing—not that the task succeeded.
+
+## State and evidence
+
+There are only two states:
+
+- `running`: includes model work, tools, automatic retries, compaction, and accepted queued instructions while execution remains active.
+- `idle`: nothing is currently executing; the user's goal may still be unmet.
+
+| Field | Meaning |
+| --- | --- |
+| `mode` | Fixed foreground/background delivery policy |
+| `lastOutput` | Latest assistant text, possibly partial while streaming; excludes thinking and tool logs |
+| `lastOutputRun` / `run` | Output's source run / current run; output may still belong to the previous run |
+| `lastOutputAt` | Latest text-update time |
+| `lastActivity` | Latest text or tool activity |
+| `queuedMessages` | SDK messages not yet consumed; not confirmation that instructions were fulfilled |
+| `lastRunOutcome` / `lastRun` | Latest completed run and its outcome: `ended`, `failed`, or `stopped` |
+| `lastRunStopReason` | Actual model termination reason, such as `stop`, `length`, `error`, or `aborted` |
+| `error` | Latest execution error; a tool-level `isError` means the call itself failed |
+| `stopRequested` | Stop was requested; if still running, do not assume tools or external processes have ended |
+| `sessionFile` | Full child JSONL log for investigation |
+
+A run is one continuous execution interval, not a model turn or every input submission. Tool submissions start counting at acceptance; other SDK activity starts at an observed `agent_start`. Instructions and adjacent continuations before settlement remain in the same run. Manual SDK compaction may show running without creating a new business run.
+
+A child that asks a question and finishes is simply idle. The main agent reads the output and decides whether to answer with `message`, add requirements, or accept the result. There is no separate ask/reply protocol, waiting-for-answer state, or prose classifier.
+
+## Waiting and notifications
+
+| Operation | Foreground session | Background session (default) |
+| --- | --- | --- |
+| `start` | Waits for the run to settle | Returns after acceptance |
+| `send(message)` while idle | Waits for the new run | Returns after acceptance |
+| `send(message)` while running | Returns after steer acceptance | Returns after steer acceptance |
+| Run completion | No parent notification | Returns to waiting observers, or notifies the parent if none are waiting |
+
+- Running messages use SDK `prompt(..., { streamingBehavior: 'steer' })` without changing mode. Acceptance is not execution or completion.
+- Completion goes through one finish path. Waiting observers receive the result without an additional background notification. Immediate observations, expired waits, and cancelled waits do not suppress later notifications. `stop` keeps the delivery policy; shutdown cleanup suppresses notifications.
+- Notifications use Pi `sendMessage(..., { deliverAs: 'steer', triggerTurn: true })`: delivery enters at a processable SDK boundary when the parent is busy and wakes it when idle. Children do not need a notification tool.
+- Cancelling a foreground start or idle-send wait requests child cancellation. After background acceptance, or a running-message acceptance, the completed tool call's signal is not attached to the child execution.
+- Notifications are best-effort, in-process delivery, with no restart recovery or exactly-once guarantee. Pi reports asynchronous delivery failures. Results remain available through observe.
+
+Stopping does not undo file changes or erase context. When changing goals after a stop, explicitly cancel the old goal in your next instruction. The main agent must verify output; `ended` does not mean business success.
+
+## Execution boundaries
+
+- Each parent allows up to 16 concurrent and 1024 retained child sessions. State queries use memory and SDK state, not disk scans or history parsing.
+- Children have only `read/bash/edit/write`, project rules, and locally discovered Skills. Parent chat history is not copied.
+- Parent extensions, package resources, MCP servers, and notification tools are not loaded. Recursive delegation tools are not installed. Models must resolve from local Pi model configuration; models registered only temporarily by parent extensions are not inherited.
+- **Not a security sandbox:** children share filesystem, process privileges, and model services. Parent-extension confirmation/permission hooks are not inherited. “Read-only” is an instruction, not enforced filesystem access control. Assign disjoint files for parallel writers. Do not use this default tool set where extension-enforced approval is required.
+- Tasks are parent-scoped. Switching, forking, or closing cancels execution and releases resources. If stopping is unconfirmed after five seconds, state remains running; switching/forking is cancelled and can be retried.
+- Session logs use Pi's normal `~/.pi/agent/sessions/<cwd group>/` layout, respecting `PI_CODING_AGENT_DIR`, and retain parent-session linkage. Pi's default session list and `pi-snap` can discover them. Background execution and task IDs are not restored after process exit.
+- A single-slot model server may serialize requests. Background execution does not imply parallel GPU inference.
+
+## Discovery versus ownership
+
+Ordinary SDK session files and parent links support discovery by Pi and `pi-snap`. Discovery does not transfer execution ownership: this extension manages run state, messages, cancellation, and result delivery.
+
+No WebUI shared-instance or parent-liveness bridges are registered, and runtime state is not handed to upstream. Upstream file-list refresh is outside this extension's responsibilities. Do not resume a still-active child from another process.
+
+## Tests
+
+```bash
+npm ci
+npm test
+# Real SDK with a local mock HTTP model; no external model calls:
+PI_SDK_ENTRY=/absolute/path/to/pi/dist/index.js npm test
+PI_SDK_ENTRY=/absolute/path/to/pi/dist/index.js node test/benchmark.mjs
+```
+
+Without `PI_SDK_ENTRY`, real-SDK tests are skipped. `test/local-smoke.mjs` is a separately invoked real local-model exercise, not part of the default tests.
+
+Validated locally with Windows Git Bash, Node 22.23.2, and official Pi 1.0.0. macOS/Linux and other Pi versions have not yet been locally tested. The benchmark compares resource loading with/without the extension and queries with large output; it does not measure full cold startup or model inference.
+
+## Related projects
+
+- [pi-cron](https://github.com/arkkwang/pi-cron): schedule agent tasks.
+- [pi-snap](https://github.com/arkkwang/pi-snap): help humans and agents investigate session failures.
+
+## License
+
+[MIT](LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,143 @@
+[English](README.md) | 简体中文
+
+# Pi Subagent
+
+基于官方 Pi SDK 的子 Agent 扩展：创建独立会话、观察执行、追加消息或停止任务。支持前台结果返回与后台完成通知。
+
+使用官方包 `@earendil-works/pi-coding-agent`，当前验证基线为 1.0.0。需要 Node.js 22.19+。
+
+## 使用
+
+三个工具统一注册为 `exposure: "deferred"`，不默认向模型暴露定义；通过 `tool_search` 按需发现、加载。插件仍正常初始化。这不要求将 subagent 工具加入 `defaultTools`；需保持 `tool_search` 可用。
+
+```js
+// 异步派发，执行结束后通知当前主会话。
+subagent_start({
+  task: "只读检查 src/cart.js 和 test/cart.test.js，报告缺陷、证据和缺失测试，不修改文件。",
+  name: "审查", mode: "background"
+})
+
+subagent_observe({ id: "返回的子会话 ID" }) // 立即返回
+subagent_observe({ id: "...", timeoutSeconds: 60 }) // 等本轮结束，最多 60 秒
+
+// running：steer 受理后返回；idle：沿用创建时的 mode 开始下一轮。
+subagent_send({ id: "...", action: "message", message: "重点检查 quantity=0，不得当作缺省值。" })
+
+subagent_send({ id: "...", action: "stop" })
+```
+
+- `start`：必填 `task`，应包含必要背景、限制和完成依据；可选 `name`（同时写入 Pi 会话标题；不传时保留界面从首条消息生成的标题）、`cwd`（相对主项目或绝对路径）、`model`（`provider/modelId`）。默认当前项目、主 Agent 模型；`mode` 为 `foreground` / `background`（默认），创建时固定为会话属性，后续不可切换。
+- `send`：必填 `id/action`；`message` 动作必填 `message`；`stop` 不接受消息。没有 `start.notify` 或 `send.mode` 参数，也没有 silent 模式。
+- `observe`：不传 ID 列出当前主会话所有子任务；默认截取最近 assistant 正文前 2000 字符。用 `detail: "output"` 获取最多 16000 字符，`offset/limit` 分页，单次上限 32000。`nextOffset` 非 null 时还有内容。
+
+`timeoutSeconds` 默认 0；大于 0 时必须指定 id，上限由 `manager.mjs` 的 `OBSERVE_MAX_TIMEOUT_SECONDS = 240` 统一配置，工具 schema 与运行时校验共用。单任务观察返回 `timedOut`；到期返回当前快照，不停止子任务。取消观察同样不停止子任务。等待使用结束事件与单个定时器，不轮询。
+
+工具返回正文为纯 JSON，并同时提供 `structuredContent`；结束通知也是纯 JSON，额外带 `event: "subagent_run_ended"`，不混入自然语言前缀。字段示例（省略其余字段）：
+
+```json
+{
+  "status": "idle",
+  "lastRunOutcome": "ended",
+  "lastRunStopReason": "length",
+  "lastOutput": "当前输出……"
+}
+```
+
+这表示当前未执行、上一轮达到输出上限，不表示任务已完成。
+
+**只有两种状态：**
+
+- `running`：包括模型执行、工具调用、自动重试、压缩和已接受的排队指令。
+- `idle`：当前没有执行，不保证用户目标已经达成。
+
+其他信息不作为状态：
+
+| 字段 | 含义 |
+| --- | --- |
+| `mode` | 创建时固定的 `foreground` / `background`，决定 idle 续发的等待方式及每轮通知 |
+| `lastOutput` | 最近 assistant 正文；流式执行时可能只是部分内容，不含思考或工具日志 |
+| `lastOutputRun` / `run` | 输出来源轮次 / 当前轮次；新一轮尚未输出时，可能显示旧输出 |
+| `lastOutputAt` | 最近正文更新时间 |
+| `lastActivity` | 最近正文或工具活动 |
+| `queuedMessages` | SDK 尚未消费的排队消息数，不是“要求已完成”的确认 |
+| `lastRunOutcome` / `lastRun` | 最近结束的一轮及结果：`ended` / `failed` / `stopped` |
+| `lastRunStopReason` | 模型实际结束原因，例如 `stop`、`length`、`error`、`aborted`；`length` 表示模型输出达到上限 |
+| `error` | 最近运行错误；工具返回 `isError` 则表示调用自身未受理 |
+| `stopRequested` | 已请求停止；仍 running 时不能假定工具或外部进程已结束 |
+| `sessionFile` | 子会话完整 JSONL 记录，可供排查 |
+
+`run` 记录一次连续执行区间，而非模型底层 turn 数或每次 UI 提交：工具提交从受理开始，外部 SDK 调用从可观察的 `agent_start` 开始，均到执行收束结束。期间加入的消息、收束前紧邻的续跑属于同一轮。SDK 手动压缩可以显示 running，但不额外增加业务轮次。
+
+子 Agent 输出问题后正常结束也只是 idle。主 Agent 查看文本，自行判断是否通过 `message` 回答、追加要求或收取结果；没有 `ask`、`reply`、等待回复状态或文本分类器。
+
+## 等待与通知
+
+| 操作 | foreground 会话 | background 会话（默认） |
+| --- | --- | --- |
+| `start` | 等待本轮收束后返回 | 受理后返回 |
+| idle 时 `send(message)` | 等待新一轮收束后返回 | 受理后返回 |
+| running 时 `send(message)` | steer 受理后返回，不等待本轮 | steer 受理后返回，不等待本轮 |
+| 每轮结束通知 | 不通知父会话 | 有等待观察者则通过观察返回，否则主动通知父会话 |
+
+- running 消息使用 SDK `prompt(..., { streamingBehavior: 'steer' })`，不改变会话 mode。受理不代表消息已执行或任务已完成；需等结果或查询状态。
+- 每轮真正收束统一走 `finish`；等待观察在收束时直接收到结果，避免重复后台通知。立即观察、超时或取消不抑制后续后台通知；`stop` 不改变交付，关闭会话的资源清理仍抑制通知。
+- 插件通过 Pi `sendMessage(..., { deliverAs: 'steer', triggerTurn: true })` 交付结束事件：主 Agent 忙时在 SDK 可处理边界进入，空闲时唤醒。不依赖子模型调用通知工具。
+- 前台启动或 idle 续发的等待调用取消时请求停止子任务；后台受理后及 running 消息受理后，不把已返回调用的取消信号绑定到子执行。
+- 通知是进程内尽力交付，没有重启恢复和严格 exactly-once 保证；Pi API 的异步投递失败由 Pi 报告。可以随时通过 observe 取回结果。
+
+停止不撤销文件修改，不删除已有上下文。停止后改变目标，应明确说明“旧任务已取消，接下来做……”。主模型仍需核对输出，不能把 `ended` 当成业务成功。
+
+## 运行边界
+
+- 本工具每个主会话最多受理 16 个并行子会话、保留 1024 个子会话。状态结合内存记录与 SDK 状态，查询不扫描磁盘或解析历史。
+- 子会话只启用 `read/bash/edit/write`；加载目标项目的规则和本地发现的 Skills，不复制主会话聊天历史。
+- 不加载主 Agent 的扩展、包资源、MCP 或通知工具，不自动注册递归派发工具。仅支持本机模型配置可解析的模型，不继承仅由主扩展临时注册的模型。
+- **不是安全沙箱**：共享文件系统、进程权限和模型服务；不继承主会话扩展提供的确认/权限钩子。“只读”是任务约束，不是强制文件权限。并行写任务必须划分文件范围。需要依靠扩展强制审批的项目不应直接使用此默认工具集。
+- 默认不跨主会话共享任务。切换、分叉、关闭会话时取消子执行并释放资源；5 秒内未确认停止则保留 running，切换/分叉会被取消，可稍后重试。
+- 子会话记录使用 Pi 默认目录 `~/.pi/agent/sessions/<工作目录分组>/`（遵循 `PI_CODING_AGENT_DIR`），与普通会话相同，保留父会话关联，默认会话列表和 `pi-snap` 可直接发现。进程退出后不恢复后台执行或任务 ID。
+- 模型服务只有一个推理 slot 时，多个 Agent 请求仍可能由服务端串行处理；后台执行不等于 GPU 并行推理。
+
+## 会话发现与状态归属
+
+子会话使用官方 SDK 默认的会话文件布局和父会话关联，供 Pi 会话列表或 `pi-snap` 发现。列表发现不等于接管执行：运行状态、消息、取消和结果交付由本扩展管理。
+
+不注册 WebUI 共享 SDK 实例或主会话保活接口，不向上游交付运行时状态。上游如何刷新文件列表不属于本扩展职责。不要同时从其他进程恢复一个仍由本扩展执行的会话。
+
+## 安装
+
+从 npm 安装：
+
+```bash
+pi install npm:@arkkwang/pi-subagent
+```
+
+也可以克隆仓库后，在仓库目录内安装本地包：
+
+```bash
+pi install .
+```
+
+重启 Pi 后加载扩展。无独立 CLI、常驻服务或第二份 Pi SDK；SDK 由 Pi 扩展加载器提供。三个工具按需暴露，主 Agent 使用前需通过 `tool_search` 发现。
+
+## 验证
+
+```bash
+npm ci
+npm test
+# 完整集成测试：实际 SDK + 本地模拟 HTTP 模型，不调用外部模型。
+PI_SDK_ENTRY=/absolute/path/to/pi/dist/index.js npm test
+PI_SDK_ENTRY=/absolute/path/to/pi/dist/index.js node test/benchmark.mjs
+```
+
+未设置 `PI_SDK_ENTRY` 时跳过真实 SDK 测试。`test/local-smoke.mjs` 是需要显式授权的真实本地模型演练，不包含在默认测试中。
+
+Windows Git Bash / Node 22.23.2 / 官方 Pi 1.0.0 为本次验证环境；macOS/Linux 和其他 Pi 版本尚未实测。性能脚本对照带/不带扩展的资源加载，并测量大输出状态查询；不代表完整冷启动或模型推理耗时。
+
+## 相关项目
+
+- [pi-cron](https://github.com/arkkwang/pi-cron)：定时执行 Agent 任务。
+- [pi-snap](https://github.com/arkkwang/pi-snap)：帮助人和 Agent 快速定位会话问题。
+
+## License
+
+[MIT](LICENSE)

package/extension.mjs

@@ -0,0 +1,100 @@
+import { Subagents, OBSERVE_MAX_TIMEOUT_SECONDS } from './manager.mjs';
+import { sessionFactory } from './sessions.mjs';
+
+const string = { type: 'string', minLength: 1 };
+const mode = { type: 'string', enum: ['foreground', 'background'], description: '创建时固定交付模式，后续沿用：foreground 等待执行结束后由工具返回；background 立即返回，结束后通知主会话（默认）。' };
+const schema = (properties, required = []) => ({ type: 'object', properties, required, additionalProperties: false });
+const result = value => ({ content: [{ type: 'text', text: JSON.stringify(value) }], structuredContent: value, details: value });
+
+export function registerSubagents(pi, sdk, createFactory = sessionFactory) {
+  let owner;
+  let manager;
+  let shutdownDrain;
+  function current(ctx) {
+    const id = ctx.sessionManager.getSessionId();
+    if (!manager) {
+      owner = id;
+      manager = new Subagents({
+        createSession: createFactory(sdk),
+        notify: event => {
+          const payload = { event: 'subagent_run_ended', ...event };
+          pi.sendMessage({
+            customType: 'subagent-result', display: true,
+            content: JSON.stringify(payload),
+            details: payload,
+          }, { deliverAs: 'steer', triggerTurn: true });
+        },
+      });
+    }
+    if (owner !== id) throw new Error('子会话仍属于上一主会话，清理后才能继续。');
+    return manager;
+  }
+  async function cleanup() {
+    if (manager) await manager.close();
+    shutdownDrain = undefined;
+    manager = undefined;
+    owner = undefined;
+  }
+  async function beforeSwitch(_event, ctx) {
+    try { await cleanup(); }
+    catch (error) { ctx.ui.notify(error.message, 'error'); return { cancel: true }; }
+  }
+  async function shutdown() {
+    try { await cleanup(); }
+    catch (error) {
+      // A host may dispose the parent after its own shutdown deadline. Keep the
+      // finalizer alive independently; release children only after work really ends.
+      const closing = manager;
+      if (closing && !shutdownDrain) {
+        shutdownDrain = Promise.allSettled([...closing.records.values()].map(r => r.work))
+          .then(() => { if (manager === closing) return cleanup(); })
+          .catch(failure => console.error('[subagent] Deferred shutdown cleanup failed:', failure));
+      }
+      throw error;
+    }
+  }
+  pi.on('session_before_switch', beforeSwitch);
+  pi.on('session_before_fork', beforeSwitch);
+  pi.on('session_shutdown', shutdown);
+  pi.on('session_start', async (_event, ctx) => {
+    if (manager && owner !== ctx.sessionManager.getSessionId()) await cleanup();
+  });
+
+  function tool(name, label, description, parameters, execute) {
+    pi.registerTool({ name, label, description, parameters, exposure: 'deferred',
+      async execute(_id, args, signal, _update, ctx) {
+        try { return result(await execute(current(ctx), args, signal, ctx)); }
+        catch (error) { return { ...result({ error: error.message }), isError: true }; }
+      },
+    });
+  }
+  tool('subagent_start', '启动子 Agent',
+    '创建独立上下文的子会话；task 必须包含必要背景、范围与限制。共享文件系统，不是沙箱。'
+    + '子会话仅有 read/bash/edit/write 和项目规则/本地 Skills，不继承主会话历史、MCP 或扩展。'
+    + 'mode 在创建时确定，后续不切换。默认后台运行，真正结束本轮后通知主会话；主会话忙时在可处理边界送达，空闲时唤醒。前台通过工具返回结果，不额外通知。'
+    + '返回 idle 只表示本轮结束，必须检查输出和 lastRunOutcome。并行任务避免修改同一文件。',
+    schema({ task: string, name: string, cwd: string, model: { ...string, description: 'provider/modelId；默认沿用主 Agent 模型。' }, mode }, ['task']),
+    (m, args, signal, ctx) => {
+      if (!args.task.trim()) throw new Error('task 不能为空。');
+      return m.start(args, ctx, signal);
+    });
+  tool('subagent_observe', '观察子 Agent',
+    '观察子会话；默认立即返回，不传 id 列出当前主会话的子任务。状态只有 idle/running。'
+    + `指定 id 和 timeoutSeconds 可等待本轮结束，最多 ${OBSERVE_MAX_TIMEOUT_SECONDS} 秒；超时返回 timedOut=true，不停止子任务。取消只退出观察。`
+    + '等待期间结束则直接返回，不重复发后台通知；超时或取消后仍由后台通知交付。无其他工作时用等待观察，不要自行 sleep 轮询。'
+    + 'lastOutput 是最近 assistant 正文，运行中可能不完整；lastOutputRun 标明来源轮次，可能来自上一轮。'
+    + 'idle 不保证目标完成，检查 lastRunOutcome/error；lastRunStopReason=length 表示模型达到输出上限。输出展示截断时用 detail=output、offset/limit 续取。',
+    schema({ id: string, timeoutSeconds: { type: 'number', minimum: 0, maximum: OBSERVE_MAX_TIMEOUT_SECONDS, default: 0, description: '最多等待秒数；0 立即返回，大于 0 必须指定 id。' }, detail: { type: 'string', enum: ['summary', 'output'] }, offset: { type: 'integer', minimum: 0 }, limit: { type: 'integer', minimum: 1, maximum: 32000 } }),
+    (m, args, signal) => m.observeStatus(args, signal));
+  tool('subagent_send', '指挥子 Agent',
+    '向已有子会话发送 message 或 stop。running 时消息排队，到可处理点读取，不撤销已经发生的操作；'
+    + 'idle 时保留上下文开始新一轮；停止后仍保留旧任务历史，改变目标时请明确说明。回复输出中的问题也使用 message，不需要专用回复动作。'
+    + '运行中 message 受理后返回，不另行等待或改变交付模式；idle 时沿用创建时 mode：前台等待新一轮结果，后台立即返回、结束后通知。stop 取消执行和排队消息，不回滚文件，也不改变原有结果交付；'
+    + '若仍为 running 且 stopRequested=true，表示尚未确认停止。',
+    schema({ id: string, action: { type: 'string', enum: ['message', 'stop'] }, message: string }, ['id', 'action']),
+    (m, args, signal) => {
+      if (args.action === 'stop' && args.message !== undefined)
+        throw new Error('stop 不接受 message。');
+      return m.send(args, signal);
+    });
+}

package/index.js

@@ -0,0 +1,7 @@
+// Pi supplies this SDK through its extension loader; do not install a second copy.
+import * as sdk from '@earendil-works/pi-coding-agent';
+import { registerSubagents } from './extension.mjs';
+
+export default function (pi) {
+  registerSubagents(pi, sdk);
+}

package/manager.mjs

@@ -0,0 +1,280 @@
+import { randomUUID } from 'node:crypto';
+
+// Shared by runtime validation and the tool schema (seconds).
+export const OBSERVE_MAX_TIMEOUT_SECONDS = 240;
+
+const textOf = message => (message?.content ?? []).filter(c => c.type === 'text').map(c => c.text).join('\n');
+const errorText = error => error instanceof Error ? error.message : String(error);
+const now = () => new Date().toISOString();
+
+/** One manager belongs to one parent session. SDK work, not model prose, owns status. */
+export class Subagents {
+  constructor({ createSession, notify, maxRunning = 16, maxSessions = 1024, stopTimeout = 5000 }) {
+    Object.assign(this, { createSession, notify, maxRunning, maxSessions, stopTimeout });
+    this.records = new Map();
+    this.closed = false;
+    this.starting = 0;
+    this.creating = new Set();
+  }
+
+  isRunning(r) {
+    return r.status === 'running' || !r.session.isIdle || r.session.isCompacting;
+  }
+
+  checkCapacity() {
+    if (this.closed) throw new Error('子会话管理器已关闭。');
+    if (this.starting + [...this.records.values()].filter(r => this.isRunning(r)).length >= this.maxRunning)
+      throw new Error(`最多同时运行 ${this.maxRunning} 个子会话；请先等待或停止已有任务。`);
+  }
+
+  get(id) {
+    const record = this.records.get(id);
+    if (!record) throw new Error(`当前主会话没有子会话 ${id}。`);
+    return record;
+  }
+
+  snapshot(r, { detail = 'summary', offset = 0, limit = detail === 'output' ? 16000 : 2000 } = {}) {
+    limit = Math.min(Math.max(limit, 1), 32000);
+    return {
+      id: r.id, name: r.name, cwd: r.cwd,
+      model: r.session.model ? `${r.session.model.provider}/${r.session.model.id}` : null,
+      status: this.isRunning(r) ? 'running' : 'idle', run: r.run,
+      mode: r.mode, startedAt: r.startedAt, endedAt: r.endedAt,
+      lastActivity: r.lastActivity, queuedMessages: r.queuedMessages,
+      lastOutput: r.lastOutput.slice(offset, offset + limit), lastOutputAt: r.lastOutputAt,
+      lastOutputRun: r.lastOutputRun,
+      outputOffset: offset, outputLength: r.lastOutput.length,
+      nextOffset: offset + limit < r.lastOutput.length ? offset + limit : null,
+      lastRunOutcome: r.lastRunOutcome, lastRun: r.lastRun, lastRunStopReason: r.lastRunStopReason,
+      error: r.error, stopRequested: r.stopRequested,
+      notificationError: r.notificationError,
+      sessionFile: r.session.sessionFile ?? null,
+    };
+  }
+
+  status(args = {}) {
+    if (args.id) return this.snapshot(this.get(args.id), args);
+    return [...this.records.values()].map(r => this.snapshot(r));
+  }
+
+  async observeStatus(args = {}, signal) {
+    const { timeoutSeconds = 0 } = args;
+    if (!Number.isFinite(timeoutSeconds) || timeoutSeconds < 0 || timeoutSeconds > OBSERVE_MAX_TIMEOUT_SECONDS)
+      throw new Error(`timeoutSeconds 必须在 0 到 ${OBSERVE_MAX_TIMEOUT_SECONDS} 秒之间。`);
+    if (timeoutSeconds > 0 && !args.id) throw new Error('等待观察必须指定 id。');
+    if (signal?.aborted) throw new Error('观察已取消；子任务继续运行。');
+    if (!args.id) return this.status(args);
+    const r = this.get(args.id);
+    if (!timeoutSeconds || !this.isRunning(r)) return { ...this.snapshot(r, args), timedOut: false };
+    return new Promise((resolve, reject) => {
+      let timer;
+      const cleanup = () => {
+        clearTimeout(timer);
+        r.observers.delete(done);
+        signal?.removeEventListener('abort', abort);
+      };
+      const done = (timedOut = false) => {
+        cleanup();
+        resolve({ ...this.snapshot(r, args), timedOut });
+      };
+      const abort = () => { cleanup(); reject(new Error('观察已取消；子任务继续运行。')); };
+      r.observers.add(done);
+      signal?.addEventListener('abort', abort, { once: true });
+      timer = setTimeout(() => done(true), timeoutSeconds * 1000);
+      // Manual SDK compaction is busy but does not produce a manager run/finish.
+      if (r.status !== 'running') r.session.waitForIdle().then(() => {
+        if (r.observers.has(done) && !this.isRunning(r)) done();
+      }, error => { if (r.observers.has(done)) { cleanup(); reject(error); } });
+    });
+  }
+
+  async start(args, context, signal) {
+    this.checkCapacity();
+    if (this.records.size + this.starting >= this.maxSessions)
+      throw new Error(`当前主会话最多保留 ${this.maxSessions} 个子会话。`);
+    this.starting++;
+    const creation = Promise.resolve().then(() => this.createSession(args, context));
+    this.creating.add(creation);
+    let session;
+    try {
+      session = await creation;
+      if (this.closed || signal?.aborted) {
+        session.dispose();
+        throw new Error('子会话启动已取消。');
+      }
+    } finally {
+      this.creating.delete(creation);
+      this.starting--;
+    }
+    const r = {
+      id: `sa-${randomUUID().slice(0, 8)}`, name: args.name ?? '子任务', session,
+      cwd: session.sessionManager?.getCwd() ?? context.cwd,
+      status: 'idle', run: 0, mode: args.mode ?? 'background',
+      lastOutput: '', lastOutputAt: null, lastOutputRun: null,
+      lastRunOutcome: null, lastRun: null, lastRunStopReason: null, error: null, notificationError: null,
+      startedAt: null, endedAt: null, lastActivity: null, queuedMessages: 0,
+      stopRequested: false, dispatches: new Set(), observers: new Set(),
+    };
+    r.unsubscribe = session.subscribe(event => this.onEvent(r, event));
+    this.records.set(r.id, r);
+    this.launch(r, args.task);
+    return r.mode === 'foreground' ? this.wait(r, signal) : this.snapshot(r);
+  }
+
+  onEvent(r, event) {
+    if (event.type === 'agent_start' && r.status !== 'running') {
+      this.begin(r);
+      // External callers own prompt(), but tool foreground/stop still need a work promise.
+      const settled = new Promise(resolve => { r.settle = resolve; });
+      // SDK settled listeners run BEFORE deferred continuations. Let those start,
+      // then observe actual idle without taking ownership of the caller's queue.
+      r.work = settled.then(() => new Promise(resolve => setImmediate(resolve)))
+        .then(() => this.observe(r));
+    }
+    if (event.type === 'agent_settled') {
+      r.settle?.();
+      r.settle = null;
+    }
+    if (event.type === 'message_start' && event.message.role === 'assistant') r.partial = '';
+    if (event.type === 'message_update' && event.assistantMessageEvent.type === 'text_delta') {
+      r.partial = (r.partial ?? '') + event.assistantMessageEvent.delta;
+      this.output(r, r.partial);
+    }
+    if (event.type === 'message_end' && event.message.role === 'assistant') {
+      const text = textOf(event.message);
+      if (text) this.output(r, text);
+      // Retried errors may be followed by a successful message. Only the latest counts.
+      r.stopReason = event.message.stopReason;
+      r.runError = event.message.errorMessage ?? null;
+    }
+    if (event.type === 'tool_execution_start') r.lastActivity = { type: 'tool', name: event.toolName, at: now() };
+    if (event.type === 'queue_update') r.queuedMessages = event.steering.length + event.followUp.length;
+    // agent_end is NOT completion: recovery, compaction and queued work may follow.
+  }
+
+  output(r, text) {
+    r.lastOutput = text;
+    r.lastOutputAt = now();
+    r.lastOutputRun = r.run;
+    r.lastActivity = { type: 'output', at: r.lastOutputAt };
+  }
+
+  begin(r) {
+    r.status = 'running';
+    r.run++;
+    r.startedAt = now();
+    r.endedAt = null;
+    r.stopRequested = false;
+    r.error = null;
+    r.runError = null;
+    r.stopReason = null;
+    r.notificationError = null;
+  }
+
+  async observe(r, failure) {
+    do {
+      await r.session.waitForIdle();
+      while (r.dispatches.size) await Promise.allSettled([...r.dispatches]);
+    } while (!r.session.isIdle);
+    return this.finish(r, failure);
+  }
+
+  launch(r, message) {
+    this.begin(r);
+    // Defer execution so callers can observe the accepted run before it settles.
+    r.work = Promise.resolve().then(() => this.run(r, message));
+  }
+
+  async run(r, message) {
+    let failure;
+    try {
+      if (!r.stopRequested)
+        await r.session.prompt(message, { expandPromptTemplates: false });
+    } catch (error) {
+      failure = errorText(error);
+    }
+    return this.observe(r, failure);
+  }
+
+  finish(r, failure) {
+    r.status = 'idle';
+    r.endedAt = now();
+    r.lastRun = r.run;
+    r.lastRunStopReason = r.stopReason;
+    r.lastRunOutcome = r.stopRequested || r.stopReason === 'aborted' ? 'stopped'
+      : failure || r.stopReason === 'error' ? 'failed' : 'ended';
+    r.error = r.lastRunOutcome === 'failed' ? failure || r.runError || '模型执行失败。' : null;
+    const result = this.snapshot(r);
+    const observed = r.observers.size > 0;
+    for (const done of [...r.observers]) done();
+    if (!this.closed && r.mode === 'background' && !observed) {
+      try { this.notify(result); }
+      catch (error) { r.notificationError = errorText(error); }
+    }
+    return result;
+  }
+
+  async send(args, signal) {
+    const r = this.get(args.id);
+    if (args.action === 'stop') return this.stop(r);
+    if (this.closed) throw new Error('子会话管理器已关闭。');
+    if (!args.message?.trim()) throw new Error('message 动作需要非空 message。');
+    if (r.stopRequested && this.isRunning(r)) throw new Error('正在停止，确认 idle 后再发送消息。');
+    if (signal?.aborted) throw new Error('发送已取消。');
+    if (r.status === 'idle') {
+      if (this.isRunning(r)) throw new Error('子会话正在处理 SDK 操作，请等待 idle 后再发送消息。');
+      this.checkCapacity();
+      this.launch(r, args.message);
+      return r.mode === 'foreground' ? this.wait(r, signal) : this.snapshot(r);
+    }
+    // Supplement the active run; do not create another result consumer.
+    const dispatch = r.session.prompt(args.message, { streamingBehavior: 'steer', expandPromptTemplates: false });
+    r.dispatches.add(dispatch);
+    try { await dispatch; }
+    finally { r.dispatches.delete(dispatch); }
+    return this.snapshot(r);
+  }
+
+  async wait(r, signal) {
+    let onAbort;
+    const cancelled = new Promise(resolve => {
+      onAbort = () => { this.stop(r).then(resolve, error => resolve({ ...this.snapshot(r), error: errorText(error) })); };
+      signal?.addEventListener('abort', onAbort, { once: true });
+      if (signal?.aborted) onAbort();
+    });
+    try { return await Promise.race([r.work, cancelled]); }
+    finally {
+      signal?.removeEventListener('abort', onAbort);
+    }
+  }
+
+  async stop(r) {
+    if (!this.isRunning(r)) return this.snapshot(r);
+    if (!r.stopping) {
+      if (r.status === 'running') r.stopRequested = true;
+      r.session.clearQueue();
+      r.stopping = (async () => {
+        let timer;
+        try {
+          const stopped = Promise.resolve().then(async () => {
+            await r.session.abort();
+            await r.work;
+          });
+          await Promise.race([stopped, new Promise(resolve => { timer = setTimeout(resolve, this.stopTimeout); })]);
+          return this.snapshot(r); // timeout retains running + stopRequested, never claims idle
+        } finally { clearTimeout(timer); r.stopping = null; }
+      })();
+    }
+    return r.stopping;
+  }
+
+  async close() {
+    this.closed = true; // Suppress notifications into a different parent session.
+    await Promise.allSettled([...this.creating]);
+    await Promise.all([...this.records.values()].map(r => this.stop(r)));
+    if ([...this.records.values()].some(r => this.isRunning(r)))
+      throw new Error('部分子任务尚未确认停止；不能切换会话，请稍后重试。');
+    for (const r of this.records.values()) { r.unsubscribe(); r.session.dispose(); }
+    this.records.clear();
+  }
+}

package/package.json

@@ -1,6 +1,50 @@
-{
-  "name": "@arkkwang/pi-subagent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@arkkwang/pi-subagent",
+  "version": "0.1.0",
+  "type": "module",
+  "pi": {
+    "extensions": [
+      "./index.js"
+    ]
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "description": "Sub-agent sessions for the official Pi SDK",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arkkwang/pi-subagent.git"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "license": "MIT",
+  "author": "arkkwang",
+  "files": [
+    "index.js",
+    "extension.mjs",
+    "manager.mjs",
+    "sessions.mjs",
+    "README.zh-CN.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/arkkwang/pi-subagent#readme",
+  "bugs": {
+    "url": "https://github.com/arkkwang/pi-subagent/issues"
+  },
+  "keywords": [
+    "pi-agent",
+    "ai",
+    "pi-package"
+  ]
+}

package/sessions.mjs

@@ -0,0 +1,53 @@
+import path from 'node:path';
+import { stat } from 'node:fs/promises';
+
+/** Lazy SDK setup: loading the parent extension never scans resources or starts a model. */
+export function sessionFactory(sdk) {
+  let runtime;
+  return async (args, ctx) => {
+    const cwd = path.resolve(ctx.cwd, args.cwd ?? '.');
+    if (!(await stat(cwd)).isDirectory()) throw new Error(`不是目录：${cwd}`);
+    const agentDir = sdk.getAgentDir();
+    runtime ??= sdk.ModelRuntime.create();
+    let modelRuntime;
+    try { modelRuntime = await runtime; }
+    catch (error) { runtime = undefined; throw error; }
+    let model;
+    if (args.model) {
+      const split = args.model.indexOf('/');
+      if (split < 1) throw new Error('model 必须为 provider/modelId，例如 llama/iq3。');
+      model = modelRuntime.getModel(args.model.slice(0, split), args.model.slice(split + 1));
+    } else if (ctx.model) {
+      model = modelRuntime.getModel(ctx.model.provider, ctx.model.id);
+    }
+    if (!model) throw new Error('无法解析子模型；请选择本机 Pi 配置中的 provider/modelId。');
+
+    // Keep model/compaction settings and AGENTS/Skills, but never recursively load
+    // parent extensions, package executables, external notifications or MCP servers.
+    const trusted = cwd === path.resolve(ctx.cwd) && ctx.isProjectTrusted();
+    const configured = sdk.SettingsManager.create(cwd, agentDir, { projectTrusted: trusted }).getSettings();
+    const settingsManager = sdk.SettingsManager.inMemory({
+      ...configured, packages: [], extensions: [], prompts: [], themes: [],
+    }, { projectTrusted: trusted });
+    const resourceLoader = new sdk.DefaultResourceLoader({
+      cwd, agentDir, settingsManager, noExtensions: true, noPromptTemplates: true, noThemes: true,
+      appendSystemPrompt: [
+        'You are a sub-agent. Work on the delegated task using the supplied context and project rules. '
+        + 'Your last text output is returned to the main agent. State results, evidence, limitations or questions clearly. '
+        + 'You have an independent conversation but share the filesystem; do not assume file isolation. '
+        + 'Do not launch other agents or send external notifications. Use only the permissions granted for the delegated task.',
+      ],
+    });
+    await resourceLoader.reload();
+    const sessionManager = sdk.SessionManager.create(cwd, undefined, {
+      parentSession: ctx.sessionManager.getSessionFile(),
+    });
+    const { session } = await sdk.createAgentSession({
+      cwd, agentDir, modelRuntime, model, thinkingLevel: ctx.thinkingLevel,
+      settingsManager, resourceLoader, sessionManager,
+      tools: ['read', 'bash', 'edit', 'write'],
+    });
+    if (args.name !== undefined) session.setSessionName(args.name);
+    return session;
+  };
+}