@gotgenes/pi-subagents 2.0.0 → 4.0.0

package/CHANGELOG.md

@@ -5,6 +5,53 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.0.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v3.0.0...pi-subagents-v4.0.0) (2026-05-17)
+
+
+### ⚠ BREAKING CHANGES
+
+* The untyped globalThis[Symbol.for("pi-subagents:manager")] accessor is removed. Use getSubagentsService() from the package's public exports instead.
+* The public API surface is now exported from src/service.ts. The old untyped Symbol.for("pi-subagents:manager") global will be removed in a subsequent commit.
+
+### Features
+
+* add SubagentRecord serializer ([d7afb45](https://github.com/gotgenes/pi-packages/commit/d7afb4569c9e28ce5d4bf7fb1ac560b0bcbb7c90))
+* add SubagentsService types and accessor functions ([468623c](https://github.com/gotgenes/pi-packages/commit/468623c936f45cc30d3c5dde134cc2d21da4a0c4))
+* expose public service entry point via package exports ([0dbeaaf](https://github.com/gotgenes/pi-packages/commit/0dbeaaf39c79717df8cabf59e8ba53652f9bc7af))
+* implement getRecord and listAgents on SubagentsService adapter ([a6da473](https://github.com/gotgenes/pi-packages/commit/a6da47393f6faa3fef93bd065c1ad1a0613d1636))
+* implement spawn with model resolution on SubagentsService adapter ([fd70d82](https://github.com/gotgenes/pi-packages/commit/fd70d828905bc3415fa8b8aebfe4c2a5355209cb))
+* implement steer, abort, waitForAll, hasRunning on adapter ([00f0b99](https://github.com/gotgenes/pi-packages/commit/00f0b99ea978625798ba67a40b375e42006d33e4))
+* publish SubagentsService at extension init, remove old untyped global ([6047e2b](https://github.com/gotgenes/pi-packages/commit/6047e2bbbaf87b5e28325b084b09daf2b0c9b6b9))
+
+
+### Documentation
+
+* plan SubagentsService implementation ([#48](https://github.com/gotgenes/pi-packages/issues/48)) ([6bd2af8](https://github.com/gotgenes/pi-packages/commit/6bd2af862fb7e7f429617c154391c800b50c5d86))
+* **retro:** add retro notes for issue [#49](https://github.com/gotgenes/pi-packages/issues/49) ([69a5bfc](https://github.com/gotgenes/pi-packages/commit/69a5bfc94edfc445d46fb495449649998614f86d))
+
+## [3.0.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v2.0.0...pi-subagents-v3.0.0) (2026-05-17)
+
+
+### ⚠ BREAKING CHANGES
+
+* The JoinMode type and defaultJoinMode setting are removed from the public settings interface.
+* The join-mode setting (smart/async/group) is removed. Background agents always notify individually on completion.
+* The subagents:ready event is no longer emitted. Extensions should use the typed SubagentsAPI ([#48](https://github.com/gotgenes/pi-packages/issues/48)) instead of event-based RPC discovery.
+* The subagents:rpc:ping, subagents:rpc:spawn, and subagents:rpc:stop event channels are no longer registered. Use the typed SubagentsAPI via Symbol.for() instead.
+
+### Features
+
+* remove group-join and cross-extension-rpc source ([b7d7f21](https://github.com/gotgenes/pi-packages/commit/b7d7f21af265e2ff95f0534f5c0b51f71b8f1e7f))
+* remove group-join wiring from index.ts ([4e2dc7f](https://github.com/gotgenes/pi-packages/commit/4e2dc7f8a98e441308f229745dfc42d09784d786))
+* remove join-mode types and settings ([1d98793](https://github.com/gotgenes/pi-packages/commit/1d98793eb85aa3d9815274aa443c34bb4434b6f9))
+* remove RPC wiring from index.ts ([3a960af](https://github.com/gotgenes/pi-packages/commit/3a960af8f6bb83219497d6229d12c6859cf3eb71))
+
+
+### Documentation
+
+* plan removal of group-join, output-file, and ad-hoc RPC ([#49](https://github.com/gotgenes/pi-packages/issues/49)) ([853a97f](https://github.com/gotgenes/pi-packages/commit/853a97f1c47051868b2ffddd7d5509f765a80d07))
+* remove group-join and RPC from README and AGENTS ([9f65f7a](https://github.com/gotgenes/pi-packages/commit/9f65f7a21611af8dead00a5fb34d7d10f3d6ab43))
+
 ## [2.0.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v1.0.2...pi-subagents-v2.0.0) (2026-05-17)
 
 

package/README.md

@@ -17,7 +17,7 @@ https://github.com/user-attachments/assets/8685261b-9338-4fea-8dfe-1c590d5df543
 ## Features
 
 - **Claude Code look & feel** — same tool names, calling conventions, and UI patterns (`Agent`, `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 smart group join (consolidated notifications)
+- **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
 - **Conversation viewer** — select any agent in `/agents` to open a live-scrolling overlay of its full conversation (auto-follows new content, scroll up to pause)
 - **Custom agent types** — define agents in `.pi/agents/<name>.md` with YAML frontmatter: custom system prompts, model selection, thinking levels, tool restrictions
@@ -31,9 +31,9 @@ https://github.com/user-attachments/assets/8685261b-9338-4fea-8dfe-1c590d5df543
 - **Git worktree isolation** — run agents in isolated repo copies; changes auto-committed to branches on completion
 - **Skill preloading** — inject named skills into agent system prompts, discovered from `.pi/skills/`, `.agents/skills/`, and global locations (Pi-standard `<name>/SKILL.md` directory layout supported)
 - **Tool denylist** — block specific tools via `disallowed_tools` frontmatter
-- **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. Group completions render each agent individually
+- **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`, `steered`, `compacted`) emitted via `pi.events`, enabling other extensions to react to sub-agent activity
-- **Cross-extension RPC** — other pi extensions can spawn and stop subagents via the `pi.events` event bus (`subagents:rpc:ping`, `subagents:rpc:spawn`, `subagents:rpc:stop`). Standardized reply envelopes with protocol versioning. Emits `subagents:ready` on load
+
 
 ## Install
 
@@ -103,7 +103,7 @@ Background agent completion notifications render as styled boxes:
   transcript: .pi/output/agent-abc123.jsonl
 ```
 
-Group completions render each agent as a separate block. The LLM receives structured `<task-notification>` XML for parsing, while the user sees the themed visual.
+The LLM receives structured `<task-notification>` XML for parsing, while the user sees the themed visual.
 
 ## Default Agent Types
 
@@ -232,7 +232,7 @@ The `/agents` command opens an interactive menu:
 Running agents (2) — 1 running, 1 done     ← only shown when agents exist
 Agent types (6)                             ← unified list: defaults + custom
 Create new agent                            ← manual wizard or AI-generated
-Settings                                    ← max concurrency, max turns, grace turns, join mode
+Settings                                    ← max concurrency, max turns, grace turns
 ```
 
 - **Agent types** — unified list with source indicators: `•` (project), `◦` (global), `✕` (disabled). Select an agent to manage it:
@@ -243,7 +243,7 @@ Settings                                    ← max concurrency, max turns, grac
 - **Eject** — writes the embedded default config as a `.md` file to project or personal location, so you can customize it
 - **Disable/Enable** — toggle agent availability. Disabled agents stay visible in the list (marked `✕`) and can be re-enabled
 - **Create new agent** — choose project/personal location, then manual wizard (step-by-step prompts for name, tools, model, thinking, system prompt) or AI-generated (describe what the agent should do and a sub-agent writes the `.md` file). Any name is allowed, including default agent names (overrides them)
-- **Settings** — configure max concurrency, default max turns, grace turns, and join mode at runtime
+- **Settings** — configure max concurrency, default max turns, and grace turns at runtime
 
 ## Graceful Max Turns
 
@@ -266,29 +266,14 @@ Background agents are subject to a configurable concurrency limit (default: 4).
 
 Foreground agents bypass the queue — they block the parent anyway.
 
-## Join Strategies
-
-When background agents complete, they notify the main agent. The **join mode** controls how these notifications are delivered. It applies only to background agents.
-
-| Mode | Behavior |
-|------|----------|
-| `smart` (default) | 2+ background agents spawned in the same turn are auto-grouped into a single consolidated notification. Solo agents notify individually. |
-| `async` | Each agent sends its own notification on completion (original behavior). Best when results need incremental processing. |
-| `group` | Force grouping even when spawning a single agent. Useful when you know more agents will follow. |
-
-**Timeout behavior:** When agents are grouped, a 30-second timeout starts after the first agent completes. If not all agents finish in time, a partial notification is sent with completed results and remaining agents continue with a shorter 15-second re-batch window for stragglers.
-
-**Configuration:**
-- Configure join mode in `/agents` → Settings → Join mode
-
 ## Persistent Settings
 
-Runtime tuning values set via `/agents` → Settings (max concurrency, default max turns, grace turns, default join mode) persist across pi restarts. Two files, merged on load:
+Runtime tuning values set via `/agents` → Settings (max concurrency, default max turns, grace turns) persist across pi restarts. Two files, merged on load:
 
 - **Global:** `~/.pi/agent/subagents.json` — your machine-wide defaults. Edit by hand; the `/agents` menu never writes here.
 - **Project:** `<cwd>/.pi/subagents.json` — per-project overrides. Written by `/agents` → Settings.
 
-**Precedence:** project overrides global on any field present in both. Missing fields fall back to the hardcoded defaults (max concurrency `4`, default max turns unlimited, grace turns `5`, join mode `smart`).
+**Precedence:** project overrides global on any field present in both. Missing fields fall back to the hardcoded defaults (max concurrency `4`, default max turns unlimited, grace turns `5`).
 
 **Example — global defaults for a beefy machine:**
 
@@ -318,78 +303,11 @@ Agent lifecycle events are emitted via `pi.events.emit()` so other extensions ca
 | `subagents:failed` | Agent errored, stopped, or aborted | same as completed + `error`, `status` |
 | `subagents:steered` | Steering message sent | `id`, `message` |
 | `subagents:compacted` | Agent's session successfully compacted | `id`, `type`, `description`, `reason` (`"manual"` / `"threshold"` / `"overflow"`), `tokensBefore`, `compactionCount` |
-| `subagents:ready` | Extension loaded and RPC handlers registered | — |
 | `subagents:settings_loaded` | Persisted settings applied at extension init | `settings` (merged global + project) |
 | `subagents:settings_changed` | `/agents` → Settings mutation was applied | `settings`, `persisted` (`boolean` — `false` on write failure) |
 
 `tokens.total` = `input + output + cacheWrite`. `cacheRead` is excluded — each turn's `cacheRead` is the cumulative cached prefix re-read on that one API call, so summing per-message would over-count it. Use `contextUsage.percent` (surfaced as `(NN%)` in the widget) for current context size.
 
-## Cross-Extension RPC
-
-Other pi extensions can spawn and stop subagents programmatically via the `pi.events` event bus, without importing this package directly.
-
-All RPC replies use a standardized envelope: `{ success: true, data?: T }` on success, `{ success: false, error: string }` on failure.
-
-### Discovery
-
-Listen for `subagents:ready` to know when RPC handlers are available:
-
-```typescript
-pi.events.on("subagents:ready", () => {
-  // RPC handlers are registered — safe to call ping/spawn/stop
-});
-```
-
-### Ping
-
-Check if the subagents extension is loaded and get the protocol version:
-
-```typescript
-const requestId = crypto.randomUUID();
-const unsub = pi.events.on(`subagents:rpc:ping:reply:${requestId}`, (reply) => {
-  unsub();
-  if (reply.success) console.log("Protocol version:", reply.data.version);
-});
-pi.events.emit("subagents:rpc:ping", { requestId });
-```
-
-### Spawn
-
-Spawn a subagent and receive its ID:
-
-```typescript
-const requestId = crypto.randomUUID();
-const unsub = pi.events.on(`subagents:rpc:spawn:reply:${requestId}`, (reply) => {
-  unsub();
-  if (!reply.success) {
-    console.error("Spawn failed:", reply.error);
-  } else {
-    console.log("Agent ID:", reply.data.id);
-  }
-});
-pi.events.emit("subagents:rpc:spawn", {
-  requestId,
-  type: "general-purpose",
-  prompt: "Do something useful",
-  options: { description: "My task", run_in_background: true },
-});
-```
-
-### Stop
-
-Stop a running agent by ID:
-
-```typescript
-const requestId = crypto.randomUUID();
-const unsub = pi.events.on(`subagents:rpc:stop:reply:${requestId}`, (reply) => {
-  unsub();
-  if (!reply.success) console.error("Stop failed:", reply.error);
-});
-pi.events.emit("subagents:rpc:stop", { requestId, agentId: "agent-id-here" });
-```
-
-Reply channels are scoped per `requestId`, so concurrent requests don't interfere.
-
 ## Persistent Agent Memory
 
 Agents can have persistent memory across sessions. Set `memory` in frontmatter to enable:
@@ -477,8 +395,6 @@ src/
   agent-types.ts      # Unified agent registry (defaults + user), tool name resolution
   agent-runner.ts     # Session creation, execution, graceful max_turns, steer/resume
   agent-manager.ts    # Agent lifecycle, concurrency queue, completion notifications
-  cross-extension-rpc.ts # RPC handlers for cross-extension spawn/ping via pi.events
-  group-join.ts       # Group join manager: batched completion notifications with timeout
   custom-agents.ts    # Load user-defined agents from .pi/agents/*.md
   memory.ts           # Persistent agent memory (resolve, read, build prompt blocks)
   skill-loader.ts     # Preload skills (Pi-standard + Agent Skills spec layouts)

package/docs/plans/0048-implement-subagents-api.md

@@ -0,0 +1,303 @@
+---
+issue: 48
+issue_title: "feat: implement and publish SubagentsAPI at extension init"
+---
+
+# Implement and publish SubagentsService
+
+## Problem Statement
+
+The package currently exposes an untyped, undocumented manager via `Symbol.for("pi-subagents:manager")` on `globalThis`.
+This forces consumers to guess the API shape, lacks model resolution at the boundary (causing "No API key found for undefined" crashes when consumers pass string model names), and leaks non-serializable internals (`AgentSession`, `AbortController`) in returned records.
+
+The architecture doc specifies a typed interface with `Symbol.for()` accessor functions that other extensions import as an optional peer dependency.
+This issue implements that boundary, following the naming and structural conventions established by `pi-permission-system`.
+
+## Goals
+
+- Export `SubagentsService` interface, `SubagentRecord`, `SubagentStatus`, `SpawnOptions`, `LifetimeUsage`, accessor functions (`publishSubagentsService`, `getSubagentsService`), and event constants from the package's public entry point.
+- Create `src/service-adapter.ts` — an adapter wrapping `AgentManager` to satisfy `SubagentsService`, handling string model resolution and record serialization.
+- Call `publishSubagentsService()` at extension init; clean up on `session_shutdown`.
+- Remove the old `Symbol.for("pi-subagents:manager")` global key.
+- This is a **breaking change** (`feat!:`) — the old untyped global key is removed and replaced with the typed service under a new key.
+- Follow the naming and structural conventions established by `pi-permission-system` (`service.ts`, `@gotgenes/<pkg>:service` key, `Record<symbol, unknown>` cast).
+
+## Non-Goals
+
+- Consumer extensions (scheduling, transcript) — these are separate packages.
+- Native Pi service registry integration (`pi.registerService()`) — deferred to a future Pi SDK release.
+- `SubagentsService.resume()` — not part of the initial interface per the architecture doc.
+- Output-file JSONL format migration (#61).
+
+## Background
+
+### Prerequisite issues
+
+- #49 (remove group-join and RPC) — **closed/merged**. The untyped RPC channels are already gone.
+- #52 (remove scheduled subagents) — **closed/merged**.
+- #51 (update ADR for hard fork) — **closed/merged**.
+
+### Relevant modules
+
+| Module                  | Role in this change                                                                                  |
+| ----------------------- | ---------------------------------------------------------------------------------------------------- |
+| `src/index.ts`          | Wiring layer. Currently publishes the untyped global; will call `publishSubagentsService()` instead. |
+| `src/agent-manager.ts`  | Core lifecycle manager. The adapter wraps its public methods.                                        |
+| `src/model-resolver.ts` | `resolveModel()` converts string → `Model`. The adapter calls this at the API boundary.              |
+| `src/types.ts`          | Defines `AgentRecord` (internal, non-serializable).                                                  |
+| `src/usage.ts`          | Exports `LifetimeUsage` (already serializable).                                                      |
+
+### Constraints from AGENTS.md
+
+- One concern per file — types/accessors in `src/service.ts`, adapter logic in `src/service-adapter.ts`.
+- Avoid `any` unless absolutely necessary — the accessor functions use `Record<symbol, unknown>` on `globalThis`.
+- Pi SDK imports stay out of business-logic modules — `service-adapter.ts` accepts `pi` and `ctx` as narrow interface parameters.
+- Narrow interface types for collaborators — the adapter takes a minimal `AgentManagerLike` interface, not the concrete `AgentManager` class.
+
+### Alignment with pi-permission-system
+
+This plan deliberately follows the pattern established by `@gotgenes/pi-permission-system`:
+
+| Aspect          | pi-permission-system                       | pi-subagents (this plan)                |
+| --------------- | ------------------------------------------ | --------------------------------------- |
+| Public file     | `src/service.ts`                           | `src/service.ts`                        |
+| Interface name  | `PermissionsService`                       | `SubagentsService`                      |
+| Symbol.for key  | `"@gotgenes/pi-permission-system:service"` | `"@gotgenes/pi-subagents:service"`      |
+| globalThis cast | `Record<symbol, unknown>`                  | `Record<symbol, unknown>`               |
+| Accessors       | `publish/get/unpublishPermissionsService`  | `publish/get/unpublishSubagentsService` |
+| exports →       | `./src/service.ts`                         | `./src/service.ts`                      |
+
+The architecture doc uses `SubagentsAPI` naming and `pi:service:subagents` key; it should be updated during implementation to reflect the final naming.
+
+## Design Overview
+
+### Module decomposition
+
+```text
+src/service.ts          ← SubagentsService interface, SubagentRecord, SpawnOptions,
+                          SubagentStatus, accessor functions, event constants
+src/service-adapter.ts  ← createSubagentsService() factory, record serialization,
+                          model resolution at the boundary
+src/index.ts            ← wire: publishSubagentsService(createSubagentsService(...))
+```
+
+### Types (in `src/service.ts`)
+
+```typescript
+export type SubagentStatus =
+  | "queued" | "running" | "completed" | "steered"
+  | "aborted" | "stopped" | "error";
+
+export interface SubagentRecord {
+  id: string;
+  type: string;
+  description: string;
+  status: SubagentStatus;
+  result?: string;
+  error?: string;
+  toolUses: number;
+  startedAt: number;
+  completedAt?: number;
+  lifetimeUsage: LifetimeUsage;
+  compactionCount: number;
+  worktreeResult?: { hasChanges: boolean; branch?: string };
+}
+
+export interface SpawnOptions {
+  description?: string;
+  model?: string;
+  maxTurns?: number;
+  thinkingLevel?: string;
+  isolated?: boolean;
+  inheritContext?: boolean;
+  foreground?: boolean;
+  bypassQueue?: boolean;
+  isolation?: "worktree";
+}
+
+export interface SubagentsService {
+  spawn(type: string, prompt: string, options?: SpawnOptions): string;
+  getRecord(id: string): SubagentRecord | undefined;
+  listAgents(): SubagentRecord[];
+  abort(id: string): boolean;
+  steer(id: string, message: string): Promise<boolean>;
+  waitForAll(): Promise<void>;
+  hasRunning(): boolean;
+}
+
+export const SUBAGENT_EVENTS = {
+  STARTED: "subagents:started",
+  COMPLETED: "subagents:completed",
+  ACTIVITY: "subagents:activity",
+} as const;
+```
+
+### Accessor pattern
+
+```typescript
+const SERVICE_KEY = Symbol.for("@gotgenes/pi-subagents:service");
+
+export function publishSubagentsService(service: SubagentsService): void {
+  (globalThis as Record<symbol, unknown>)[SERVICE_KEY] = service;
+}
+
+export function getSubagentsService(): SubagentsService | undefined {
+  return (globalThis as Record<symbol, unknown>)[SERVICE_KEY] as
+    | SubagentsService
+    | undefined;
+}
+
+export function unpublishSubagentsService(): void {
+  delete (globalThis as Record<symbol, unknown>)[SERVICE_KEY];
+}
+```
+
+### Adapter (`src/service-adapter.ts`)
+
+The adapter accepts narrow interfaces rather than concrete classes:
+
+```typescript
+interface AgentManagerLike {
+  spawn(pi: any, ctx: any, type: string, prompt: string, options: any): string;
+  getRecord(id: string): AgentRecord | undefined;
+  listAgents(): AgentRecord[];
+  abort(id: string): boolean;
+  waitForAll(): Promise<void>;
+  hasRunning(): boolean;
+}
+
+interface AdapterDeps {
+  manager: AgentManagerLike;
+  resolveModel: (input: string, registry: ModelRegistry) => any;
+  getCtx: () => { pi: any; ctx: any } | undefined;
+  getModelRegistry: () => ModelRegistry | undefined;
+}
+```
+
+Key behaviors:
+
+1. **String model resolution** — `spawn()` calls `resolveModel(options.model, registry)` before delegating to the manager.
+   If resolution fails, throws with the error string (list of available models).
+2. **Session gating** — throws if `getCtx()` returns `undefined` (no active session).
+3. **Record serialization** — `toSubagentRecord()` strips `session`, `abortController`, `promise`, `pendingSteers`, `outputCleanup` from `AgentRecord`.
+4. **Steer delegation** — uses the same pattern as the `steer_subagent` tool: checks status, queues if session not ready, delegates to `session.steer()`.
+
+This mirrors the `pi-permission-system` pattern: a slim `service.ts` defines the contract and accessors; a separate adapter file contains the implementation wiring.
+
+### Public entry point
+
+The package currently has no explicit `exports` field in `package.json`.
+Since Pi loads the extension via `pi.extensions` (pointing at `./src/index.ts`), the service types and accessors need a separate public entry point.
+Add an `exports` map:
+
+```json
+{
+  "exports": {
+    ".": "./src/service.ts"
+  }
+}
+```
+
+This exposes the types and accessor functions to consumers who `import("@gotgenes/pi-subagents")`.
+The extension entry point (`./src/index.ts`) remains declared in `pi.extensions`.
+This matches the pattern established by `pi-permission-system` (`exports` → `service.ts`, `pi.extensions` → `index.ts`).
+
+### Edge cases
+
+- **No active session**: `spawn()` throws `"No active session — cannot spawn agents outside a session."`.
+- **Model resolution failure**: `spawn()` throws with the error string from `resolveModel()`.
+- **Missing description**: default to a truncated prompt (`prompt.slice(0, 80)`).
+- **Steer on non-running agent**: returns `false`.
+- **Steer before session ready**: queues the message (returns `true`).
+
+### Naming conventions
+
+Following `pi-permission-system`'s established pattern:
+
+- Public file: `service.ts` (not `api.ts`)
+- Interface: `SubagentsService` (not `SubagentsAPI`)
+- Symbol key: `"@gotgenes/pi-subagents:service"` (scoped package name, not generic `pi:service:*`)
+- globalThis cast: `Record<symbol, unknown>` (not `any`)
+- Accessor names: `publish/get/unpublishSubagentsService`
+
+## Module-Level Changes
+
+### New files
+
+| File                           | Contents                                                                                                                                                                       |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `src/service.ts`               | `SubagentsService` interface, `SubagentRecord`, `SubagentStatus`, `SpawnOptions`, `LifetimeUsage` re-export, accessor functions, event constants, `unpublishSubagentsService`. |
+| `src/service-adapter.ts`       | `createSubagentsService()` factory. `toSubagentRecord()` serializer. Narrow `AgentManagerLike` and `AdapterDeps` interfaces.                                                   |
+| `test/service-adapter.test.ts` | Unit tests for the adapter (model resolution, serialization, session gating, steer delegation).                                                                                |
+| `test/service.test.ts`         | Unit tests for accessor functions (publish/get/unpublish round-trip, isolation between keys).                                                                                  |
+
+### Modified files
+
+| File           | Change                                                                                                                                                                                                                                                                                                                                                                      |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/index.ts` | Import `publishSubagentsService`, `unpublishSubagentsService` from `./service.js` and `createSubagentsService` from `./service-adapter.js`. Replace `Symbol.for("pi-subagents:manager")` block with `publishSubagentsService(createSubagentsService(...))`. In `session_shutdown`, call `unpublishSubagentsService()` instead of `delete (globalThis as any)[MANAGER_KEY]`. |
+| `package.json` | Add `"exports": { ".": "./src/service.ts" }`.                                                                                                                                                                                                                                                                                                                               |
+| `src/usage.ts` | No change needed — `LifetimeUsage` is already exported. Re-exported from `src/service.ts`.                                                                                                                                                                                                                                                                                  |
+
+## Test Impact Analysis
+
+1. **New unit tests enabled**: `test/service-adapter.test.ts` tests the adapter in isolation against a mock `AgentManagerLike` — model resolution, record stripping, session gating, steer semantics.
+   `test/service.test.ts` tests the accessor functions (publish/get/unpublish lifecycle, `undefined` before publish).
+2. **Existing tests that become redundant**: None — the old `Symbol.for("pi-subagents:manager")` global was not unit-tested.
+3. **Existing tests that must stay**: All `agent-manager.test.ts` and `agent-runner.test.ts` tests remain — they test the internal engine, not the public service boundary.
+   Any test referencing `MANAGER_KEY` or `"pi-subagents:manager"` in string assertions must be updated.
+
+## TDD Order
+
+1. **`src/service.ts` — types, accessors, and event constants.**
+   Test: `test/service.test.ts` — `publishSubagentsService` stores on globalThis, `getSubagentsService` retrieves it, `unpublishSubagentsService` removes it, `getSubagentsService` returns `undefined` when not published.
+   Commit: `feat!: add SubagentsService types and accessor functions`
+
+2. **`src/service-adapter.ts` — `toSubagentRecord()` serializer.**
+   Test: `test/service-adapter.test.ts` — given an `AgentRecord` with `session`, `abortController`, `promise`, `pendingSteers`, `outputCleanup`, verify the returned `SubagentRecord` contains only serializable fields.
+   Commit: `feat: add SubagentRecord serializer`
+
+3. **`src/service-adapter.ts` — `createSubagentsService().getRecord()` and `listAgents()`.**
+   Test: verify `getRecord` delegates to manager and serializes; `listAgents` returns serialized records sorted by `startedAt` descending.
+   Commit: `feat: implement getRecord and listAgents on SubagentsService adapter`
+
+4. **`src/service-adapter.ts` — `spawn()` with model resolution and session gating.**
+   Test: (a) throws when `getCtx()` returns `undefined`; (b) resolves string model names via `resolveModel`; (c) throws on model resolution failure; (d) delegates to manager with resolved model; (e) uses truncated prompt as default description.
+   Commit: `feat: implement spawn with model resolution on SubagentsService adapter`
+
+5. **`src/service-adapter.ts` — `steer()`, `abort()`, `waitForAll()`, `hasRunning()`.**
+   Test: `steer` returns `false` for non-running agent, `true` when session queues or delivers; `abort`/`waitForAll`/`hasRunning` delegate to manager.
+   Commit: `feat: implement steer, abort, waitForAll, hasRunning on adapter`
+
+6. **Wire into `src/index.ts` — replace old global with typed service.**
+   Replace `Symbol.for("pi-subagents:manager")` block with `publishSubagentsService(createSubagentsService(...))`.
+   Update `session_shutdown` to call `unpublishSubagentsService()`.
+   Commit: `feat!: publish SubagentsService at extension init, remove old untyped global`
+
+7. **Add `exports` to `package.json`.**
+   Add `"exports": { ".": "./src/service.ts" }` so consumers can `import("@gotgenes/pi-subagents")`.
+   Commit: `feat: expose public service entry point via package exports`
+
+8. **Run full suite and type check.**
+   `pnpm vitest run && pnpm run check`.
+   Fix any straggling references to `MANAGER_KEY` or `"pi-subagents:manager"` in tests.
+   Commit (if fixes needed): `test: update references to old Symbol.for key`
+
+## Risks and Mitigations
+
+| Risk                                                                            | Mitigation                                                                                                                                                                                                         |
+| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Consumers relying on the old `pi-subagents:manager` key break silently          | This is a `feat!:` (major bump). No other package in this monorepo references the old key. Document migration in CHANGELOG via release-please.                                                                     |
+| `exports` field breaks Pi's extension loader                                    | Pi loads via `pi.extensions` (`./src/index.ts`), which is separate from `exports`. The `exports` field only affects `import("@gotgenes/pi-subagents")` from consumer code. Same pattern as `pi-permission-system`. |
+| Adapter leaks internal state if `AgentRecord` gains new non-serializable fields | `toSubagentRecord()` uses an explicit allowlist (pick pattern), not a denylist. New fields must be opted in.                                                                                                       |
+| `steer()` race condition — session created between status check and queue push  | The existing tool handler has the same race window and handles it acceptably. The adapter uses the same pattern (check session → queue if absent → delegate if present).                                           |
+| `resolveModel` returns `any` — type unsafety at boundary                        | The adapter's `AgentManagerLike.spawn` already accepts `Model<any>` for the `options.model` field. The `any` is confined to the model-resolution seam, matching existing code.                                     |
+| Architecture doc uses different naming (`SubagentsAPI`, `pi:service:subagents`) | Open question documented below. Update the architecture doc during implementation to reflect final naming.                                                                                                         |
+
+## Open Questions
+
+- Should `SubagentsService` be augmented with an `onEvent(channel, callback)` subscription method, or is `pi.events.on(SUBAGENT_EVENTS.COMPLETED, ...)` sufficient for consumers?
+  Deferred — consumers already have access to `pi.events` and the event constants are exported.
+- The architecture doc uses `SubagentsAPI` naming and `pi:service:subagents` key.
+  This plan intentionally diverges to align with the established `pi-permission-system` pattern (`*Service` naming, `@gotgenes/<pkg>:service` key, `Record<symbol, unknown>` cast).
+  The architecture doc should be updated during implementation to reflect the final naming.