@yefengr/pi-subagents 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tintinweb
+
+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,375 @@
-# Temporary Holding Version
+# @yefengr/pi-subagents
 
-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.
+[yefengr](https://github.com/yefengr) maintains this [Pi](https://pi.dev) subagent package. It provides an in-process subagent runtime with foreground and background execution, steering, resume, session inspection, lifecycle events, and cross-extension type contracts.
+
+The local baseline comes from `@gotgenes/pi-subagents@19.3.4` and has since evolved independently in this repository. See [`UPSTREAM.md`](./UPSTREAM.md) for the exact source, verification records, import boundaries, and local adaptations. Historical differences from the original project and `tintinweb/pi-subagents` are kept in [Comparison with upstream](./docs/comparison-with-upstream.md).
+
+## Features
+
+- **In-process & native** — agents run inside the same pi runtime (no spawned subprocesses), sharing tool names, calling conventions, and UI patterns (`subagent`, `get_subagent_result`, `steer_subagent`) — feels native
+- **Parallel background agents** — spawn multiple agents that run concurrently with automatic queuing (configurable concurrency limit, default 4) and individual completion notifications
+- **Live widget UI** — persistent above-editor widget with animated spinners, live tool activity, token counts, and colored status icons
+- **Session transcripts** — open any subagent's full session transcript (running or with its session released) in pi's native read-only viewer via `/subagents:sessions`
+- **Custom agent types** — define agents in `.pi/agents/<name>.md` with YAML frontmatter: custom system prompts, model selection, thinking levels, tool restrictions
+- **Mid-run steering** — inject messages into running agents to redirect their work without restarting
+- **Session resume** — pick up where an agent left off, preserving full conversation context
+- **Bounded invocations** — strict turn and runtime budgets, a reserved wrap-up window, and independent queue deadlines keep every invocation finite
+- **Case-insensitive agent types** — `"explore"`, `"Explore"`, `"EXPLORE"` all work.
+  Unknown types fall back to general-purpose with a note
+- **Fuzzy model selection** — specify models by name (`"haiku"`, `"sonnet"`) instead of full IDs, with automatic filtering to only available/configured models
+- **Context inheritance** — optionally fork the parent conversation into a sub-agent so it knows what's been discussed
+- **Styled completion notifications** — background agent results render as themed, compact notification boxes (icon, stats, result preview) instead of raw XML.
+  Expandable to show full output
+- **Event bus** — lifecycle events (`subagents:created`, `started`, `completed`, `failed`, `resumed`, `steered`, `compacted`) emitted via `pi.events`, enabling other extensions to react to sub-agent activity
+
+## Loading and development
+
+Install from npm:
+
+```bash
+pi install npm:@yefengr/pi-subagents
+```
+
+Run `/reload` or restart Pi after installation. Other extensions can also depend on this package through `@yefengr/pi-subagents`.
+
+When developing directly in the package directory:
+
+```bash
+npm ci
+npm run check
+npm test
+```
+
+You can also load the entry explicitly for a development smoke test:
+
+```bash
+pi -e ./index.ts
+```
+
+## Quick Start
+
+The parent agent spawns sub-agents using the `subagent` tool:
+
+```text
+subagent({
+  subagent_type: "Explore",
+  prompt: "Find all files that handle authentication",
+  description: "Find auth files",
+  run_in_background: true,
+})
+```
+
+Foreground agents block until complete and return results inline. Fresh foreground terminal results include `Agent ID: <id>` so the parent can resume the same agent without a separate lookup.
+Background agents return an ID immediately and notify you on completion.
+
+## UI
+
+The extension renders a persistent widget above the editor showing active background agents (foreground runs are rendered inline by the `subagent` tool's progress stream):
+
+```text
+● Agents
+├─ ⠹ Agent  Refactor auth module · ↻5≤30 · 5 tool uses · 33.8k token (62%) · 12.3s
+│    ⎿  editing 2 files…
+├─ ⠹ Explore  Find auth files · ↻3 · 3 tool uses · 12.4k token (8%) · 4.1s
+│    ⎿  searching…
+├─ ⠹ Agent  Long-running task · ↻42 · 38 tool uses · 91.0k token (84% · ⇊2) · 2m17s
+│    ⎿  reading…
+└─ 2 queued
+```
+
+The token field is annotated with two optional signals inside parens:
+
+- **`NN%`** — context-window utilization (color-coded: <70% dim, 70–85% warning, ≥85% error).
+  Omitted when the model has no declared `contextWindow`, or briefly right after compaction.
+- **`⇊N`** — number of times the session has compacted, when > 0.
+  Stays dim; the percent's color carries urgency.
+
+Individual agent results render inline in the conversation:
+
+| Phase / outcome | Example                                                               |
+| --------------- | --------------------------------------------------------------------- |
+| **Running**     | `⠹ ↻3≤30 · 3 tool uses · 12.4k token (8%)` / `⎿ searching…`         |
+| **Completed**   | `✓ ↻8 · 5 tool uses · 33.8k token (62%) · 12.3s` / `⎿ Done`         |
+| **Turn limit**  | `✗ ↻30≤30 · 5 tool uses · 33.8k token` / `⎿ Turn limit reached`     |
+| **Timed out**   | `✗ ↻3 · 3 tool uses · 12.4k token` / `⎿ Invocation timed out`       |
+| **Cancelled**   | `✗ ↻3 · 3 tool uses · 12.4k token` / `⎿ Cancelled`                  |
+| **Queue timeout** | `✗` / `⎿ Queue wait timed out before execution`                    |
+
+Completed results can be expanded (ctrl+o in pi) to show the full agent output inline.
+
+Background agent completion notifications render as styled boxes:
+
+```text
+✓ Find auth files completed
+  ↻3 · 3 tool uses · 12.4k token · 4.1s
+  ⎿  Found 5 files related to authentication...
+  transcript: .pi/output/agent-abc123.jsonl
+```
+
+The LLM receives structured `<task-notification>` XML for parsing, while the user sees the themed visual.
+
+## Tools
+
+### `subagent`
+
+Launch a sub-agent.
+
+| Parameter           | Type         | Required | Description                                                      |
+| ------------------- | ------------ | -------- | ---------------------------------------------------------------- |
+| `prompt`            | string       | yes      | The task for the agent                                           |
+| `description`       | string       | yes      | Short 3-5 word summary (shown in UI)                             |
+| `subagent_type`     | string       | yes      | Agent type (built-in or custom)                                  |
+| `model`             | string       | no       | Model — `provider/modelId` or fuzzy name (`"haiku"`, `"sonnet"`) |
+| `thinking`          | string       | no       | Thinking level: off, minimal, low, medium, high, xhigh           |
+| `max_turns`         | integer      | no       | Strict hard maximum for model turns; can only tighten the configured limit |
+| `wrap_up_turns`     | integer      | no       | Turns reserved within `max_turns` for a final response; defaults from the profile or global setting |
+| `max_duration_seconds` | integer   | no       | Execution-time limit in seconds; can only tighten the configured limit |
+| `run_in_background` | boolean      | no       | Run without blocking                                             |
+| `resume`            | string       | no       | Agent ID to resume a previous session                            |
+| `inherit_context`   | boolean      | no       | Fork parent conversation into agent                              |
+
+### `get_subagent_result`
+
+Check status and retrieve results from a background agent.
+
+| Parameter  | Type    | Required | Description                   |
+| ---------- | ------- | -------- | ----------------------------- |
+| `agent_id` | string  | yes      | Agent ID to check             |
+| `wait`     | boolean | no       | Wait for completion           |
+| `verbose`  | boolean | no       | Include full conversation log |
+
+### `steer_subagent`
+
+Send a steering message to a running agent.
+The message interrupts after the current tool execution.
+
+| Parameter  | Type   | Required | Description                               |
+| ---------- | ------ | -------- | ----------------------------------------- |
+| `agent_id` | string | yes      | Agent ID to steer                         |
+| `message`  | string | yes      | Message to inject into agent conversation |
+
+## Commands
+
+| Command               | Description                                                                         |
+| --------------------- | ----------------------------------------------------------------------------------- |
+| `/subagents:settings` | Configure concurrency, resource budgets, retention, and interrupt policy |
+| `/subagents:sessions` | View a subagent's session transcript (read-only)                               |
+
+### `/subagents:agents`
+
+List all built-in and custom agent types, including disabled types. Select an agent to inspect its definition and choose whether to enable or disable it in the current project or globally. The reset action removes the selected layer's override: project settings then follow global settings, while global settings return to the default enabled state. Project settings take precedence over global settings. Global agent overrides are stored in the untracked `~/.pi/agent/subagents.local.json`; shared runtime settings remain in `~/.pi/agent/subagents.json`.
+
+### `/subagents:settings`
+
+Interactive list to tune max concurrency, max turns, reserved wrap-up turns, maximum execution duration, maximum queue wait, abort grace, the two session-retention windows, and whether ESC aborts every subagent.
+The numeric settings open an input prompt; the abort-on-ESC entry is a direct flip.
+Changes persist across pi restarts (see [Persistent Settings](./docs/configuration.md#persistent-settings)).
+
+### `/subagents:sessions`
+
+Pick any subagent — running, or completed with its live session already released — and read its full session transcript in pi's native per-entry viewer.
+Read-only: no steering, no session takeover (steering lives in the `steer_subagent` tool and the background widget).
+
+Creating and editing agent definitions is not a command — write an agent `.md` file in your editor, or ask a pi session to generate one (see [Custom Agents](./docs/configuration.md#custom-agents)).
+
+## Resource Limits
+
+Every invocation has finite limits. The defaults are `max_turns: 30`, `wrap_up_turns: 2`, `max_duration_seconds: 1800`, `max_queue_wait_seconds: 900`, and `abort_grace_seconds: 5`.
+
+`max_turns` is a strict hard maximum: the runtime never intentionally starts model turn `max_turns + 1`. `wrap_up_turns` is reserved **within** that maximum, not added to it. When the child still needs another model turn in the reserved window, it receives a final-response instruction; a child with no remaining reserved turns stops at the hard maximum.
+
+Profile and invocation values for `max_turns` and `max_duration_seconds` can only tighten the global ceiling. The effective value is the smallest valid value from global settings, profile frontmatter, and tool call. The wrap-up window uses invocation, then profile, then global precedence and is clamped to `0..max_turns - 1`.
+
+The execution clock starts when a child is admitted to run and includes workspace preparation, session construction, model calls, and tools. Background queue time is excluded from that clock and bounded separately. A queue timeout becomes terminal without starting a child session. On an execution timeout or cancellation, the runtime requests cooperative abort and releases the parent waiter and concurrency slot after `abort_grace_seconds` if the child remains unsettled; tools that ignore `AbortSignal` cannot be forcibly terminated inside this shared process. A terminal cancellation cannot be resumed until its prior turn loop has settled.
+
+## Concurrency
+
+Background agents are subject to a configurable concurrency limit (default: 4).
+Excess agents are queued and start as slots free. Each queued agent has an independent maximum wait (default: 900 seconds); when it expires, the agent reaches the `queue_timeout` terminal outcome without executing.
+The widget shows queued agents as a collapsed count.
+
+Foreground agents bypass the queue — they block the parent anyway.
+
+Stopping a still-queued agent produces the same completion notification a running agent's stop does.
+Because that agent never started, the notification says so and offers no result to collect.
+
+## Child session lifecycle
+
+A child session runs in the parent's process but is a full Pi session with its own extension set.
+It receives the standard pair of session lifecycle events:
+
+| Event              | When                                                | Reason      |
+| ------------------ | --------------------------------------------------- | ----------- |
+| `session_start`    | Extensions are bound, before the child's first turn | `"startup"` |
+| `session_shutdown` | The child session is disposed                       | `"quit"`    |
+
+Disposal happens when the retention window for a finished agent expires, when completed records are cleared at session start or switch, when the parent session shuts down, or when child extension binding fails partway.
+It does **not** happen the moment an agent finishes: the session is retained so the agent can be resumed, per the `consumedSessionRetentionMinutes` and `unconsumedSessionRetentionMinutes` settings above. The lightweight subagent record retains the child `sessionId` and optional `outputFile` even after the heavy session object is released.
+
+The shutdown event is dispatched and awaited **before** the child's `AgentSession` is disposed, so a handler still has a live context and can close what it opened — stdio subprocesses, sockets, timers, file handles.
+Each child's shutdown is bounded: a handler that never resolves is abandoned after a few seconds and disposal proceeds, so one misbehaving extension cannot stall the parent's teardown or Pi's exit.
+
+If you author an extension that runs in children, note that its `session_shutdown` handler now fires **once per child session** in addition to once for the parent.
+A handler that flushes a log, writes a summary, or closes a shared resource should be safe to run repeatedly within one process.
+Before this behavior existed, children fired `session_start` with no matching shutdown, so extension-owned resources accumulated for the life of the parent process.
+
+## Events
+
+Agent lifecycle events are emitted via `pi.events.emit()` so other extensions can react. Agent events use lifecycle record v3; earlier payload shapes are not supported.
+
+Every v3 payload contains `recordVersion: 3`, agent identity, `phase` (`queued`, `running`, or `terminal`), terminal `outcome` when applicable (`completed`, `turn_limit`, `timeout`, `queue_timeout`, `cancelled`, or `error`), invocation identity (`invocationKind`, `invocationSource`, `invocationIndex`, and tool-driven `toolCallId`), effective resource limits, separate invocation/lifetime turn counts and usage, and explicit session state. `sessionId` is mandatory once a child session exists. `sessionState: "not-created"` is reserved for a pre-session error, queued cancellation, or queue timeout. `outputFile` is optional diagnostic information, not the session attribution key.
+
+| Event                        | When                                                    | Additional fields / behavior                                                                                          |
+| ---------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `subagents:created`          | Background agent registered                             | v3 snapshot before limiter admission; not persisted                                                                   |
+| `subagents:started`          | Agent enters `running`, including queue admission       | v3 snapshot; not persisted                                                                                             |
+| `subagents:completed`        | Fresh invocation reaches `completed`                   | terminal v3 payload; exact same object is persisted as `subagents:record`                                             |
+| `subagents:failed`           | Fresh invocation has any non-completed terminal outcome | terminal v3 payload; exact same object is persisted as `subagents:record`                                             |
+| `subagents:resumed`          | Resume invocation reaches a terminal outcome            | terminal v3 payload with the current resume `toolCallId`; exact same object is persisted                              |
+| `subagents:steered`          | Steering message accepted                               | v3 snapshot plus `instruction`; steering stays inside the current invocation                                          |
+| `subagents:compacted`        | Agent's session successfully compacted                  | v3 snapshot plus `reason`, `tokensBefore`, and `compactionCount`                                                      |
+| `subagents:settings_loaded`  | Persisted settings applied at extension init            | `settings` (merged global + project)                                                                                   |
+| `subagents:settings_changed` | `/subagents:settings` mutation was applied              | `settings`, `persisted` (`boolean`; `false` on write failure)                                                         |
+
+`invocationUsage.total` and `lifetimeUsage.total` equal `input + output + cacheWrite`. `cacheRead` is excluded because each turn reports the cumulative cached prefix re-read on that API call. A fresh run and every resume open a zeroed invocation window while preserving lifetime totals, so prior turns, tools, duration, and usage cannot consume the new invocation's budget.
+
+## Worktree Isolation
+
+Worktree isolation lives in a companion package, not this core.
+Install [`@gotgenes/pi-subagents-worktrees`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-subagents-worktrees) and list the agent types you want isolated in its `worktreeAgents` config — opted-in agents run in a temporary git worktree, and their changes are saved to a branch on completion.
+The earlier `isolation: "worktree"` spawn flag and `isolation:` frontmatter key were removed from the core.
+
+## Removed: agent memory and skill preloading
+
+Persistent agent memory (the `memory:` frontmatter key) and skill preloading (the `skills:` frontmatter key) were removed when the core was slimmed down.
+Children inherit the parent's skills and extensions by default, so the `isolated`, `extensions`, and `skills` frontmatter keys no longer exist.
+Package-level extension opt-outs live in the [`excludedExtensionPackages`](./docs/configuration.md#excluding-package-extensions-from-children) setting rather than agent frontmatter.
+
+## Migrating from `disallowed_tools`
+
+The `disallowed_tools` frontmatter field has been removed.
+Use [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-permission-system)'s `permission:` frontmatter instead — it provides richer semantics (allow/ask/deny vs. binary hide):
+
+```yaml
+# Before (no longer supported)
+disallowed_tools: bash
+
+# After
+permission:
+  bash: deny
+```
+
+## Permission System Integration
+
+When [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-permission-system) is installed, this extension integrates automatically:
+
+- **Per-agent permission policies** — define `permission:` in agent YAML frontmatter to set allow/ask/deny rules per agent type.
+  The permission system resolves the agent name from the `<active_agent>` tag in the child system prompt.
+- **Tool filtering** — the permission system's `before_agent_start` handler removes denied tools from the child session before the agent starts.
+- **`ask`-state forwarding** — when a child session triggers an `ask` permission, the prompt forwards to the parent session's UI.
+  The parent approves or denies, and the child resumes.
+- **Deterministic child detection** — this extension publishes `subagents:child:session-created` before `bindExtensions()` fires; the permission system subscribes and registers the child session synchronously, so detection does not rely on env vars or filesystem heuristics.
+
+No configuration is required.
+When `@gotgenes/pi-permission-system` is not installed, the lifecycle events have no subscriber — a harmless no-op.
+
+## For Extension Authors
+
+This package exposes two public subpath exports for companion extensions. `npm pack` verifies that its declarations are independently consumable.
+
+### `@yefengr/pi-subagents` — cross-extension service contract
+
+Access the subagent service from another extension at runtime:
+
+```typescript
+const { getSubagentsService } = await import("@yefengr/pi-subagents");
+const svc = getSubagentsService();
+svc?.spawn("Explore", "Check for stale TODOs");
+```
+
+Declare this package as an optional peer dependency.
+See `src/service/service.ts` for the full `SubagentsService` interface and the `WorkspaceProvider` seam.
+
+### `@yefengr/pi-subagents/settings` — layered config loader
+
+Extensions that store configuration in JSON files can use the shared layered loader, which reads a global file (`<agentDir>/<filename>`) and a project file (`<cwd>/.pi/<filename>`) and merges them — project wins on conflicts, missing files are silent, malformed files warn and fall back:
+
+```typescript
+import { loadLayeredSettings, type LayeredSettingsSource } from "@yefengr/pi-subagents/settings";
+
+interface MyConfig { enabled?: boolean; limit?: number }
+
+function sanitize(raw: unknown): Partial<MyConfig> {
+  if (!raw || typeof raw !== "object") return {};
+  const r = raw as Record<string, unknown>;
+  const out: Partial<MyConfig> = {};
+  if (typeof r.enabled === "boolean") out.enabled = r.enabled;
+  if (typeof r.limit === "number") out.limit = r.limit;
+  return out;
+}
+
+const config = loadLayeredSettings<MyConfig>({
+  agentDir,          // Pi runtime agent home directory
+  cwd,               // project root — project file lives at <cwd>/.pi/<filename>
+  filename: "my-extension.json",
+  sanitize,
+  warnLabel: "my-extension",  // prefix for the malformed-file stderr warning
+});
+```
+
+`loadLayeredSettings` returns `Partial<T>` (all fields optional); apply your defaults after the call.
+It never throws — all error conditions produce a `console.warn` and return `{}`.
+
+## Scope and non-goals
+
+**Purpose.**
+A minimal, in-process sub-agent core.
+It spawns a child session derived from the parent, runs the turn loop, streams and collects the result, gates concurrency, supports resume, and publishes its lifecycle.
+Everything else is a consumer.
+
+**In scope.**
+Defects in the surfaces the core already owns, completeness of the public lifecycle-event contract, and internal work toward the minimal-core target.
+Anything attaching to the core either subscribes to a lifecycle event, or registers a provider if it must return a value the core consumes — see [ADR-0002](./docs/decisions/0002-extensions-on-a-minimal-core.md).
+
+**Non-goals.**
+
+- _Capability the fork deliberately left behind._
+  Scheduling, cross-extension RPC, model-scope enforcement, and a built-in tool denylist belong to upstream — see [Relationship to upstream](#relationship-to-upstream).
+- _Policy about what a child may do._
+  Tool restriction is allow/ask/deny in a permission layer, not a binary hide in a spawner — see [Migrating from `disallowed_tools`](#migrating-from-disallowed_tools).
+- _Widening a child's tool allowlist on the agent's behalf._
+  An agent's `tools:` frontmatter is the complete allowlist and the only mechanism that widens it, because a settings-level list would hand a read-only `Explore` agent write-capable tools from a file its author never saw.
+- _A global run-mode default._
+  Foreground or background is a per-invocation argument and a per-agent frontmatter key; a global flip changes every existing agent file at once.
+- _Provider seams with no consumer._
+  A seam nobody supplies is a speculative abstraction that taxes every reader; the architecture may admit one without shipping it until a real consumer exists.
+
+The [architecture doc](./docs/architecture/architecture.md#scope-and-non-goals) carries the full inventory, including the removed UI surfaces and the reasoning behind each.
+
+**Where adjacent requests belong.**
+Tool restriction and per-agent permission policy → [@gotgenes/pi-permission-system](https://www.npmjs.com/package/@gotgenes/pi-permission-system).
+Worktree isolation → [@gotgenes/pi-subagents-worktrees](https://www.npmjs.com/package/@gotgenes/pi-subagents-worktrees).
+Timed dispatch, telemetry, and alternate UIs → a consumer over the lifecycle events and the typed service.
+A batteries-included alternative → upstream [`tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents).
+
+## Documentation
+
+| Document                                                       | Contents                                                                                                       |
+| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| [Configuration](./docs/configuration.md)                       | Default agent types, custom agent files and their frontmatter fields, and the `subagents.json` settings file   |
+| [Architecture](./docs/architecture/architecture.md)            | Design principles, domain decomposition, module dependency flow, Mermaid diagrams, and the improvement roadmap |
+| [Comparison with upstream](./docs/comparison-with-upstream.md) | Feature-by-feature comparison against the current upstream release                                             |
+
+## Architecture
+
+This extension is a minimal, composable core: it owns agent spawning, execution, and result retrieval, and exposes a typed `SubagentsService` plus lifecycle events that other extensions build on.
+
+## Relationship to upstream
+
+This package starts from the verified `@gotgenes/pi-subagents@19.3.4` source baseline and is maintained independently in this repository. That source was itself a hard fork of [`tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents). See [`UPSTREAM.md`](./UPSTREAM.md) for the exact tag, commit, integrity evidence and import policy.
+
+The imported comparison and decision documents describe the state of the `19.3.4` baseline. They are retained as design history and must not be treated as a promise to track later third-party releases.
+
+## License
+
+MIT — [tintinweb](https://github.com/tintinweb) (upstream) and [Chris Lasher](https://github.com/gotgenes) (fork)

package/UPSTREAM.md

@@ -0,0 +1,48 @@
+# 上游来源
+
+`packages/pi-subagents/` 由本仓库以 `@yefengr/pi-subagents` 独立维护，不在运行时依赖上游子代理 npm 包。
+
+## 基线
+
+- 上游仓库：[`gotgenes/pi-packages`](https://github.com/gotgenes/pi-packages)
+- 上游目录：`packages/pi-subagents`
+- npm 包：`@gotgenes/pi-subagents@19.3.4`
+- Git 标签：`pi-subagents-v19.3.4`
+- Git 提交：`b330769ec96928479941543d196eeafcbc6489d0`
+- npm tarball SHA-1：`43fc057ead921e33b9fd544df81d1f2d257b0b01`
+- 许可证：MIT，原始版权声明保留在 [`LICENSE`](./LICENSE)
+
+GitHub 标签、npm Registry 的 SLSA provenance 和 npm tarball 均指向或验证了上述提交。本地迁移前还逐文件核对了 npm tarball 与已安装的 `19.3.4`：两者均为 95 个文件且内容完全一致。tarball 与上游提交的共同文件中，除发布流程生成的 `package.json` 外内容一致；`dist/public.d.ts` 和 `dist/settings.d.ts` 是构建产物。
+
+## 迁入范围
+
+迁入：
+
+- 完整 `src/` 与 `test/`。
+- npm 发布范围内的 README、CHANGELOG、配置、架构与决策文档。
+- 类型声明构建、公开类型验证和 Vitest 配置。
+- 原始 MIT LICENSE。
+
+不迁入：
+
+- 上游仓库级配置、workspace、lockfile 和共享脚本。
+- 上游 `.pi/`、`AGENTS.md` 等开发 harness 配置。
+- 上游 `docs/plans/`、`docs/retro/`、媒体文件及其他历史开发产物。
+- `node_modules/` 与生成的 `dist/`。
+
+## 本地适配
+
+- 包名改为 `agent-tools-subagents`，版本从 `0.1.0` 独立演进，并设置为 private，避免误发布。
+- 使用 npm 和 package-local lockfile，不依赖上游 pnpm workspace 或 catalog。
+- `tsconfig.json`、Biome 配置和测试入口改为自包含；不迁入上游 monorepo 的 ESLint、rumdl、fallow 与 release 工具链，本地门禁为 Biome、TypeScript、完整 Vitest、声明构建和打包后消费者类型检查。
+- Pi 核心包以 peer dependency 声明，开发验证固定到当前仓库使用的 Pi `0.85.1`。
+- 工具 schema 从旧 `@sinclair/typebox` 切换到 Pi 当前提供的 `typebox` peer。
+- Pi `0.85.1` 已以 `ModelRuntime` 取代 `createAgentSession()` 的旧 `modelRegistry` 参数；本地实现创建独立 child runtime，并参考后续上游修复提交 [`f805ffc4a6ae1849c4d396cd7697f09ea38b6ec6`](https://github.com/gotgenes/pi-packages/commit/f805ffc4a6ae1849c4d396cd7697f09ea38b6ec6) 复制父会话运行时 provider 注册。
+- 跨扩展 service key 与文档示例使用本地包身份，不提供旧包名兼容入口。
+- 生命周期公共事件与 `subagents:record` 持久化改为本项目唯一支持的 v2 契约：稳定 `sessionId`、逐调用身份、逐调用 usage/tool-use 窗口和 lifetime 累计分层，不兼容旧 payload。
+- fresh/resume 的父工具调用分别记录当次 `toolCallId`；service 调用使用显式 `invocationSource: "service"`，不伪造工具调用 ID。
+- 公开类型验证改用 npm，并在临时消费者中验证打包后的声明文件。
+
+后续同步上游时必须重新核对许可证、来源提交、实际差异和本地契约；不得直接用上游最新 HEAD 覆盖本地实现。
+- 2026-10 迁出 agent-tools，以当前包名 `@yefengr/pi-subagents` 发布到 npm，取消 private；版本从 `0.1.0` 继续独立演进，跨扩展服务身份为 `@yefengr/pi-subagents:service`，命令前缀和事件命名空间统一为 `subagents:`，配置文件名 `subagents.json` 保持不变。
+- 开发验证基线升级到 Pi `1.4.0` 与 `typebox` `1.3.27`，与当前运行环境一致；host 包仍以 `*` 声明 peer。

package/dist/public.d.ts

@@ -0,0 +1,201 @@
+import { ThinkingLevel } from '@earendil-works/pi-ai';
+
+/**
+ * types.ts — Type definitions for the subagent system.
+ */
+
+/** Agent type: any string name (built-in defaults or user-defined). */
+type SubagentType = string;
+interface AgentInvocation {
+    /** Short display name, e.g. "haiku" — only set when different from parent. */
+    modelName?: string;
+    thinking?: ThinkingLevel;
+    maxTurns?: number;
+    wrapUpTurns?: number;
+    maxDurationSeconds?: number;
+    inheritContext?: boolean;
+    runInBackground?: boolean;
+}
+/** Identifies the parent invocation currently driving a subagent turn. */
+type SubagentInvocationIdentity = {
+    kind: "fresh" | "resume";
+    source: "tool";
+    toolCallId: string;
+} | {
+    kind: "fresh" | "resume";
+    source: "service";
+    toolCallId?: never;
+};
+
+/** usage.ts — Token usage: shapes, accumulator operators, session-stats readers. */
+/**
+ * Lifetime usage components, accumulated via `message_end` events. Survives
+ * compaction (which replaces session.state.messages and would reset any
+ * stats-derived sum). cacheRead is excluded because each turn's cacheRead is
+ * the cumulative cached prefix re-read on that one call — summing across
+ * turns counts the prefix N times. See issue #38.
+ */
+type LifetimeUsage = {
+    input: number;
+    output: number;
+    cacheWrite: number;
+};
+
+/**
+ * subagent-state.ts — SubagentState value object: lifecycle phase/outcome, metrics, and live activity.
+ *
+ * Owns the passive, readable state of a subagent — phase, outcome, result, error,
+ * timestamps, lifetime and current-invocation metrics, compactionCount, and
+ * live-activity fields (invocation/lifetime turn counts, activeTools, responseText) — together with the transition
+ * methods (markRunning, markCompleted, …), accumulation methods
+ * (incrementToolUses, addUsage, incrementCompactions), and live-activity
+ * transition methods (incrementTurnCount, addActiveTool, removeActiveTool,
+ * resetResponseText, appendResponseText) that mutate them.
+ *
+ * State is encapsulated behind getters; external code reads through them but
+ * mutates only via the transition/accumulation methods. The value object owns
+ * all of its own mutations — no field is written from outside.
+ *
+ * Subagent holds one of these privately and delegates its getters and mutation
+ * methods to it. Extracting it lets the lifecycle state machine and the
+ * session-event observer be unit-tested without constructing an executor.
+ */
+
+type SubagentPhase = "queued" | "running" | "terminal";
+type SubagentOutcome = "completed" | "turn_limit" | "timeout" | "queue_timeout" | "cancelled" | "error";
+
+/**
+ * workspace.ts — The single generative extension seam (ADR 0002, Phase 16 Step 2).
+ *
+ * "Where does a child run, and what brackets the run?" is a strategy (git
+ * worktree, container, tmpdir, remote sandbox), not core behavior. The core
+ * needs only a working directory plus a disposal hook; the default — the
+ * parent's cwd, with no setup/teardown — is always correct.
+ *
+ * Unlike the observational lifecycle events in child-lifecycle.ts, this is a
+ * *generative* seam: a registered provider returns a value the core consumes
+ * synchronously at run-start. The core has no knowledge of git or worktrees.
+ */
+
+/** Context the core hands a provider when a child run starts. */
+interface WorkspacePrepareContext {
+    agentId: string;
+    agentType: SubagentType;
+    baseCwd: string;
+    invocation?: AgentInvocation;
+}
+/** Outcome the core reports to a workspace when the run ends. */
+interface WorkspaceDisposeOutcome {
+    outcome: SubagentOutcome;
+    description: string;
+}
+/** What dispose may hand back for the core to fold into the child result. */
+interface WorkspaceDisposeResult {
+    /** Appended verbatim to the child's result text — the provider owns the wording. */
+    resultAddendum?: string;
+}
+/** A prepared working directory plus its bracketed teardown. Born complete. */
+interface Workspace {
+    /** The working directory — already exists when the workspace is handed back. */
+    readonly cwd: string;
+    dispose(outcome: WorkspaceDisposeOutcome): WorkspaceDisposeResult | undefined;
+}
+/** The single generative seam: supplies a child's workspace. */
+interface WorkspaceProvider {
+    prepare(ctx: WorkspacePrepareContext): Promise<Workspace | undefined>;
+}
+
+/**
+ * service.ts — Public API surface for cross-extension access to subagents.
+ *
+ * Consumers declare this package as an optional peer dependency and use
+ * dynamic import to access the accessor functions:
+ *
+ *   const { getSubagentsService } = await import("@yefengr/pi-subagents");
+ *   const svc = getSubagentsService();
+ *   svc?.spawn("Explore", "Check for stale TODOs");
+ */
+
+/** Serializable snapshot of an agent's state — no live session objects. */
+interface SubagentRecord {
+    id: string;
+    type: string;
+    description: string;
+    phase: SubagentPhase;
+    outcome?: SubagentOutcome;
+    result?: string;
+    error?: string;
+    isBackground: boolean;
+    lifecycleInvocation: SubagentInvocationIdentity;
+    invocationIndex: number;
+    sessionState: "created" | "not-created";
+    sessionId?: string;
+    outputFile?: string;
+    toolUses: number;
+    startedAt: number;
+    completedAt?: number;
+    lifetimeUsage: LifetimeUsage;
+    invocationStartedAt: number;
+    invocationToolUses: number;
+    invocationUsage: LifetimeUsage;
+    compactionCount: number;
+    invocationTurnCount: number;
+    lifetimeTurnCount: number;
+    maxTurns: number;
+    wrapUpTurns: number;
+    maxDurationSeconds: number;
+}
+/** Options for spawning an agent via the service. */
+interface SpawnOptions {
+    description?: string;
+    model?: string;
+    maxTurns?: number;
+    wrapUpTurns?: number;
+    maxDurationSeconds?: number;
+    thinkingLevel?: string;
+    inheritContext?: boolean;
+    foreground?: boolean;
+    bypassQueue?: boolean;
+}
+/** The public service contract for cross-extension subagent access. */
+interface SubagentsService {
+    /** Spawn an agent. Returns the agent ID immediately. */
+    spawn(type: string, prompt: string, options?: SpawnOptions): string;
+    /** Get a snapshot of an agent's current state. */
+    getRecord(id: string): SubagentRecord | undefined;
+    /** List all tracked agents, most recent first. */
+    listAgents(): SubagentRecord[];
+    /** Abort a running or queued agent. Returns false if not found. */
+    abort(id: string): boolean;
+    /** Send a steering message to a running agent. */
+    steer(id: string, message: string): Promise<boolean>;
+    /** Wait for all running and queued agents to complete. */
+    waitForAll(): Promise<void>;
+    /** Whether any agents are running or queued. */
+    hasRunning(): boolean;
+    /**
+     * Register the single workspace provider that supplies a child's working
+     * directory plus bracketed setup/teardown. Throws if one is already
+     * registered. Returns a disposer that unregisters the provider.
+     */
+    registerWorkspaceProvider(provider: WorkspaceProvider): () => void;
+}
+/** Event channel constants for pi.events subscriptions. */
+declare const SUBAGENT_EVENTS: {
+    readonly STARTED: "subagents:started";
+    readonly COMPLETED: "subagents:completed";
+    readonly FAILED: "subagents:failed";
+    readonly RESUMED: "subagents:resumed";
+    readonly COMPACTED: "subagents:compacted";
+    readonly CREATED: "subagents:created";
+    readonly STEERED: "subagents:steered";
+};
+/** Publish the SubagentsService on globalThis for cross-extension access. */
+declare function publishSubagentsService(service: SubagentsService): void;
+/** Retrieve the published SubagentsService, or undefined if not yet published. */
+declare function getSubagentsService(): SubagentsService | undefined;
+/** Remove the SubagentsService from globalThis (call on shutdown/reload). */
+declare function unpublishSubagentsService(): void;
+
+export { SUBAGENT_EVENTS, getSubagentsService, publishSubagentsService, unpublishSubagentsService };
+export type { LifetimeUsage, SpawnOptions, SubagentInvocationIdentity, SubagentOutcome, SubagentPhase, SubagentRecord, SubagentsService, Workspace, WorkspaceDisposeOutcome, WorkspaceDisposeResult, WorkspacePrepareContext, WorkspaceProvider };