@gotgenes/pi-subagents 3.0.0 → 4.1.0

package/CHANGELOG.md

@@ -5,6 +5,48 @@ 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.1.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v4.0.0...pi-subagents-v4.1.0) (2026-05-18)
+
+
+### Features
+
+* add resolveInvocationModel to model-resolver ([462b519](https://github.com/gotgenes/pi-packages/commit/462b5194fdfdf86d8d2d166a99472c651e00b76b))
+
+
+### Bug Fixes
+
+* remove quotes from rumdl glob patterns in lint:md script ([a8a0c62](https://github.com/gotgenes/pi-packages/commit/a8a0c62feb2fc45cf68cd7d777259dc159de671b))
+
+
+### Documentation
+
+* plan extract model resolution from Agent.execute ([#53](https://github.com/gotgenes/pi-packages/issues/53)) ([4c07a47](https://github.com/gotgenes/pi-packages/commit/4c07a474f9f25043a2fa3a4f2829e97eb9bb7666))
+* **retro:** add retro notes for issue [#48](https://github.com/gotgenes/pi-packages/issues/48) ([f244c04](https://github.com/gotgenes/pi-packages/commit/f244c04c64f768e724e89d77962f2fb63715b998))
+
+## [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)
 
 

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.

package/docs/plans/0053-extract-model-resolution-from-execute.md

@@ -0,0 +1,181 @@
+---
+issue: 53
+issue_title: "refactor: extract model resolution from Agent.execute"
+---
+
+# Extract model resolution from Agent.execute
+
+## Problem Statement
+
+The `Agent` tool's `execute` callback in `index.ts` contains inline model-resolution logic (~lines 660–670) that determines which model an agent runs with.
+This block checks `resolvedConfig.modelInput`, calls `resolveModel()`, distinguishes error strings from resolved model instances, and silently falls back to the parent model for config-specified models that fail resolution.
+The logic is not independently testable — it is only exercised through integration-level agent spawning.
+
+A second, simpler call site in `getModelLabel()` (~line 1043) also calls `resolveModel()` inline but only checks whether the model resolves; it does not need the same fallback semantics.
+
+## Goals
+
+- Extract the inline model-resolution block from `Agent.execute` into a named, unit-testable function in `model-resolver.ts`.
+- Keep the existing `resolveModel()` function unchanged — the new function composes it.
+- No behavior change: model-resolution priority and fallback semantics remain identical.
+
+## Non-Goals
+
+- Changing the `resolveModel()` fuzzy-matching algorithm.
+- Refactoring the `getModelLabel()` call site (~line 1043) — it has different semantics (display-only, no fallback) and does not benefit from the same extraction.
+- Refactoring `service-adapter.ts` model resolution — it already uses a clean injected-dependency pattern.
+- Changing any public API surface.
+
+## Background
+
+### Existing modules
+
+| Module                 | Role                                                                                                                                                                                                                                    |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `model-resolver.ts`    | Exports `resolveModel(input, registry)` — returns a `Model` on success or an error string on failure.                                                                                                                                   |
+| `invocation-config.ts` | Exports `resolveAgentInvocationConfig()` — merges tool params with agent config. Returns `modelInput` (the raw string) and `modelFromParams` (whether the string came from tool params vs. agent config).                               |
+| `service-adapter.ts`   | Already receives `resolveModel` as a dependency via `AdapterDeps`. Its model resolution is simpler (always throw on failure).                                                                                                           |
+| `index.ts`             | `Agent.execute` contains the inline block. Uses both `modelInput` and `modelFromParams` to decide: (a) return error to user if params-specified model fails, or (b) silently fall back to parent model if config-specified model fails. |
+
+### Relevant constraint from AGENTS.md
+
+> Keep modules focused and composable (one concern per file).
+
+The new function belongs in `model-resolver.ts` alongside `resolveModel()` since it composes the latter with invocation-level fallback policy.
+
+## Design Overview
+
+### New function signature
+
+```typescript
+interface ModelResolutionResult {
+  model: unknown;
+  error?: undefined;
+}
+
+interface ModelResolutionError {
+  model?: undefined;
+  error: string;
+}
+
+type ModelResolution = ModelResolutionResult | ModelResolutionError;
+
+function resolveInvocationModel(
+  parentModel: unknown,
+  modelInput: string | undefined,
+  modelFromParams: boolean,
+  registry: ModelRegistry,
+): ModelResolution;
+```
+
+### Decision model
+
+The function encapsulates the existing three-branch logic:
+
+1. **No `modelInput`** → return `{ model: parentModel }` (inherit parent).
+2. **`modelInput` resolves** → return `{ model: resolved }`.
+3. **`modelInput` fails to resolve**:
+   - If `modelFromParams` (user typed it) → return `{ error: errorMessage }` so the caller can surface it.
+   - If `!modelFromParams` (agent config specified it) → return `{ model: parentModel }` (silent fallback).
+
+### Result shape rationale
+
+A discriminated union (`ModelResolution`) with `model` and `error` fields avoids the existing `typeof resolved === "string"` type-narrowing smell.
+The caller in `index.ts` becomes:
+
+```typescript
+const resolution = resolveInvocationModel(
+  ctx.model,
+  resolvedConfig.modelInput,
+  resolvedConfig.modelFromParams,
+  ctx.modelRegistry,
+);
+if (resolution.error) return textResult(resolution.error);
+const model = resolution.model;
+```
+
+### Edge cases
+
+- `modelInput` is `undefined` → short-circuit, return parent model.
+- `modelInput` is an empty string → delegates to `resolveModel()`, which currently matches vacuously (documented in existing tests); no change in behavior.
+
+## Module-Level Changes
+
+### `src/model-resolver.ts`
+
+- Add `ModelResolutionResult`, `ModelResolutionError`, and `ModelResolution` type exports.
+- Add `resolveInvocationModel()` export.
+- No changes to existing `resolveModel()`, `ModelEntry`, or `ModelRegistry`.
+
+### `src/index.ts`
+
+- Update import to include `resolveInvocationModel`.
+- Replace the inline model-resolution block in `Agent.execute` (~lines 660–670) with a call to `resolveInvocationModel()` and a check on the result.
+- Remove the now-unused destructuring of `modelFromParams` from `resolvedConfig` at the call site (it is consumed internally by `resolveInvocationModel` via the parameter).
+
+### `test/model-resolver.test.ts`
+
+- Add a new `describe("resolveInvocationModel")` block with tests covering all three branches plus edge cases.
+
+## Test Impact Analysis
+
+### New unit tests enabled
+
+The extraction enables direct testing of the three-branch fallback logic (inherit, resolve, fallback-on-config-failure) that was previously only exercisable through full agent spawning.
+Specifically:
+
+- Parent model inheritance when no `modelInput` is provided.
+- Successful resolution returns the resolved model.
+- User-specified model failure returns an error.
+- Config-specified model failure silently falls back to parent.
+
+### Existing tests that stay as-is
+
+- All existing `resolveModel` tests in `test/model-resolver.test.ts` — they test the lower-level function which is unchanged.
+- Integration-level tests in `test/agent-runner.test.ts` and `test/agent-manager.test.ts` — they exercise model usage through the full agent lifecycle.
+- `test/invocation-config.test.ts` — unchanged module.
+- `test/service-adapter.test.ts` — uses its own injected `resolveModel` dependency, unaffected.
+
+### Tests that become redundant
+
+None.
+The inline block was not directly tested anywhere — it was only reached through integration paths that test much more than model resolution.
+
+## TDD Order
+
+1. **Red → Green: parent model inheritance.**
+   Test: `resolveInvocationModel` returns `{ model: parentModel }` when `modelInput` is `undefined`.
+   Commit: `test: add resolveInvocationModel tests for parent model inheritance`
+
+2. **Red → Green: successful model resolution.**
+   Test: returns `{ model: resolvedModel }` when `resolveModel` succeeds (both params-specified and config-specified).
+   Commit: `test: add resolveInvocationModel tests for successful resolution`
+
+3. **Red → Green: user-specified model failure.**
+   Test: returns `{ error: message }` when `modelFromParams` is `true` and `resolveModel` returns an error string.
+   Commit: `test: add resolveInvocationModel tests for param model failure`
+
+4. **Red → Green: config-specified model silent fallback.**
+   Test: returns `{ model: parentModel }` when `modelFromParams` is `false` and `resolveModel` returns an error string.
+   Commit: `test: add resolveInvocationModel tests for config model fallback`
+
+5. **Green: implement `resolveInvocationModel` in `model-resolver.ts`.**
+   All four test cases go green.
+   Commit: `feat: add resolveInvocationModel to model-resolver`
+
+6. **Refactor: replace inline block in `index.ts`.**
+   Replace the inline model-resolution block in `Agent.execute` with a call to `resolveInvocationModel`.
+   Run full test suite to confirm no regressions.
+   Commit: `refactor: use resolveInvocationModel in Agent.execute (#53)`
+
+## Risks and Mitigations
+
+| Risk                                                                                   | Mitigation                                                                                                                                                                                         |
+| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Subtle behavior difference in the extracted function vs. the inline block              | TDD steps 1–4 encode the exact current semantics; step 6 is a pure mechanical substitution.                                                                                                        |
+| `resolveModel` return type is `any \| string` — fragile narrowing                      | The new function encapsulates the `typeof` check behind a discriminated union, reducing but not eliminating the `any`. Fixing the `any` is out of scope (would require Pi SDK model type changes). |
+| Second call site (`getModelLabel`) might seem like it should also use the new function | Explicitly listed as a non-goal — it has display-only semantics with no fallback behavior.                                                                                                         |
+
+## Open Questions
+
+None — the extraction is mechanical and the issue's acceptance criteria are unambiguous.

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

@@ -0,0 +1,44 @@
+---
+issue: 48
+issue_title: "feat: implement and publish SubagentsService at extension init"
+---
+
+# Retro: #48 — implement and publish SubagentsService at extension init
+
+## Final Retrospective (2026-05-17T15:30:00Z)
+
+### Session summary
+
+Planned and implemented a typed `SubagentsService` interface with `Symbol.for()` accessor functions, an adapter wrapping `AgentManager` with model resolution and record serialization, and wired it into the extension init.
+Released as `@gotgenes/pi-subagents@4.0.0` (breaking: old untyped global removed).
+The plan was revised mid-session to align naming with `pi-permission-system`'s established conventions after the user flagged the discrepancy.
+
+### Observations
+
+#### What went well
+
+- TDD execution was clean: 8 steps, zero rework, all 33 new tests green on first pass.
+- The adapter design was well-scoped — `index.ts` wiring was +16/−12 lines, and the narrow `AgentManagerLike` interface made test mocks trivial.
+- The allowlist serialization pattern (`toSubagentRecord`) prevents future leaks of non-serializable fields by default.
+
+#### What caused friction (agent side)
+
+- `missing-context` — The initial plan adopted the issue body's naming verbatim (`SubagentsAPI`, `api.ts`, `pi:service:subagents`, `(globalThis as any)`) without checking `pi-permission-system` for the established convention (`SubagentsService`, `service.ts`, `@gotgenes/<pkg>:service`, `Record<symbol, unknown>`).
+  The user had to explicitly ask "Does this structure follow the pattern set forth by pi-permission-system?"
+  Impact: full plan rewrite (replaced entire file), issue title update, issue body update — ~15 minutes of rework across 3 user turns.
+  This was **user-caught**.
+
+- `missing-context` — Same pattern as the #49 retro: following the issue spec literally without checking the codebase.
+  The architecture doc also used the stale naming, reinforcing the wrong choice.
+  Root cause: the "Gather context" step in `/plan-issue` didn't include a cross-package convention check.
+
+#### What caused friction (user side)
+
+- The user had to perform mechanical oversight ("Does this follow the pi-permission-system pattern?") that the planner should have caught independently.
+  If the `/plan-issue` prompt included a step to grep sibling packages for established API patterns, this would have been a design decision surfaced during planning rather than a correction after the fact.
+
+### Changes made
+
+1. Created `packages/pi-subagents/docs/retro/0048-implement-subagents-api.md` (this file).
+2. Updated `.pi/skills/package-pi-subagents/SKILL.md` — changed `SubagentsAPI` → `SubagentsService` in Implementation Priorities; added `service.ts` and `service-adapter.ts` to module dependency graph and descriptions.
+3. Updated `.pi/prompts/plan-issue.md` — added step 7 to Gather context: check sibling packages for established API patterns before adopting issue body naming.

package/docs/retro/0049-remove-group-join-output-file-rpc.md

@@ -0,0 +1,38 @@
+---
+issue: 49
+issue_title: "feat: remove group-join, output-file, and ad-hoc RPC"
+---
+
+# Retro: #49 — remove group-join, output-file, and ad-hoc RPC
+
+## Final Retrospective (2026-05-17T15:15:00Z)
+
+### Session summary
+
+Planned and implemented the removal of group-join and ad-hoc RPC from `pi-subagents`, releasing v3.0.0.
+The original scope included `output-file.ts` removal, but the user intervened to retain it for post-hoc debugging value.
+A new issue (#61) was filed to port the output-file format to Pi's official JSONL session schema.
+
+### Observations
+
+#### What went well
+
+- User intervention produced a materially better outcome — retaining debugging transcripts and identifying a format conformance gap that became #61.
+- TDD execution was clean: 6 steps, zero rework, all tests green on first pass after each step.
+- The `feat!:` → release-please → v3.0.0 pipeline worked smoothly end-to-end.
+
+#### What caused friction (agent side)
+
+- `missing-context` — Included `output-file.ts` removal in the initial plan without questioning its debugging value, despite AGENTS.md's rule "Ask before removing functionality or changing defaults." The issue body explicitly listed it for removal so I followed the spec literally. Impact: required plan revision (amend commit), scope-narrowing comment on issue, and filing #61 — roughly 10 minutes of rework, but produced a better design.
+
+- `missing-context` — When asked whether output-file adheres to Pi's session format, searched the web (`web_search` for "Claude Code session JSONL format") instead of checking the local `~/development/pi/pi` monorepo. The user had to explicitly say "~/development/pi/pi has the code for Pi's JSONL format." Impact: one extra round-trip and less authoritative initial answer (Claude Code's format vs Pi's `SessionManager`). Self-identified after user redirect.
+
+- `instruction-violation` (self-identified) — Shell-escaped the `gh issue comment` body incorrectly; backtick-wrapped `src/output-file.ts` was interpreted by bash. Caught immediately via `gh issue view` and fixed with `--edit-last`. Impact: trivial — one extra command.
+
+#### What caused friction (user side)
+
+- The issue body listed output-file for removal without noting its debugging value. The user's "How confident are we in getting rid of the logging system?" intervention was the correction. If the issue had marked output-file removal as "tentative pending debugging value assessment," the plan would have surfaced it as a design decision from the start. Minor — the discussion was quick and productive.
+
+### Changes made
+
+1. Created `packages/pi-subagents/docs/retro/0049-remove-group-join-output-file-rpc.md` (this file).

package/package.json

@@ -1,6 +1,9 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "3.0.0",
+  "version": "4.1.0",
+  "exports": {
+    ".": "./src/service.ts"
+  },
   "description": "A pi extension that brings Claude Code-style autonomous sub-agents to pi. Friendly fork of @tintinweb/pi-subagents.",
   "author": {
     "name": "Chris Lasher"
@@ -56,7 +59,7 @@
     "check": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "lint:md": "rumdl check '*.md' 'docs/**/*.md'",
+    "lint:md": "rumdl check *.md docs/**/*.md",
     "lint": "biome check . && pnpm run lint:md"
   }
 }

package/src/index.ts

@@ -20,8 +20,10 @@ import { getAgentConversation, getDefaultMaxTurns, getGraceTurns, normalizeMaxTu
 import { BUILTIN_TOOL_NAMES, getAgentConfig, getAllTypes, getAvailableTypes, getDefaultAgentNames, getUserAgentNames, registerAgents, resolveType } from "./agent-types.js";
 import { loadCustomAgents } from "./custom-agents.js";
 import { resolveAgentInvocationConfig } from "./invocation-config.js";
-import { type ModelRegistry, resolveModel } from "./model-resolver.js";
+import { type ModelRegistry, resolveInvocationModel, resolveModel } from "./model-resolver.js";
 import { createOutputFilePath, streamToOutputFile, writeInitialEntry } from "./output-file.js";
+import { publishSubagentsService, unpublishSubagentsService } from "./service.js";
+import { createSubagentsService } from "./service-adapter.js";
 import { applyAndEmitLoaded, type SubagentsSettings, saveAndEmitChanged } from "./settings.js";
 import { type AgentConfig, type AgentInvocation, type AgentRecord, type NotificationDetails, type SubagentType } from "./types.js";
 import {
@@ -376,18 +378,19 @@ export default function (pi: ExtensionAPI) {
     });
   });
 
-  // Expose manager via Symbol.for() global registry for cross-package access.
-  // Standard Node.js pattern for cross-package singletons (used by OpenTelemetry, etc.).
-  const MANAGER_KEY = Symbol.for("pi-subagents:manager");
-  (globalThis as any)[MANAGER_KEY] = {
-    waitForAll: () => manager.waitForAll(),
-    hasRunning: () => manager.hasRunning(),
-    spawn: (piRef: any, ctx: any, type: string, prompt: string, options: any) =>
-      manager.spawn(piRef, ctx, type, prompt, options),
-    getRecord: (id: string) => manager.getRecord(id),
-  };
+  // Typed service published via Symbol.for() for cross-extension access.
+  // Consumers: const { getSubagentsService } = await import("@gotgenes/pi-subagents");
+  let currentCtx: { pi: unknown; ctx: unknown } | undefined;
+  const service = createSubagentsService({
+    manager,
+    resolveModel,
+    getCtx: () => currentCtx,
+    getModelRegistry: () => (currentCtx?.ctx as { modelRegistry?: ModelRegistry } | undefined)?.modelRegistry,
+  });
+  publishSubagentsService(service);
 
-  pi.on("session_start", async (_event, _ctx) => {
+  pi.on("session_start", async (_event, ctx) => {
+    currentCtx = { pi, ctx };
     manager.clearCompleted();
   });
 
@@ -398,7 +401,8 @@ export default function (pi: ExtensionAPI) {
   // On shutdown, abort all agents immediately and clean up.
   // If the session is going down, there's nothing left to consume agent results.
   pi.on("session_shutdown", async () => {
-    delete (globalThis as any)[MANAGER_KEY];
+    unpublishSubagentsService();
+    currentCtx = undefined;
     manager.abortAll();
     for (const timer of pendingNudges.values()) clearTimeout(timer);
     pendingNudges.clear();
@@ -653,16 +657,14 @@ Guidelines:
       const resolvedConfig = resolveAgentInvocationConfig(customConfig, params);
 
       // Resolve model from agent config first; tool-call params only fill gaps.
-      let model = ctx.model;
-      if (resolvedConfig.modelInput) {
-        const resolved = resolveModel(resolvedConfig.modelInput, ctx.modelRegistry);
-        if (typeof resolved === "string") {
-          if (resolvedConfig.modelFromParams) return textResult(resolved);
-          // config-specified: silent fallback to parent
-        } else {
-          model = resolved;
-        }
-      }
+      const resolution = resolveInvocationModel(
+        ctx.model,
+        resolvedConfig.modelInput,
+        resolvedConfig.modelFromParams,
+        ctx.modelRegistry,
+      );
+      if (resolution.error) return textResult(resolution.error);
+      const model = resolution.model;
 
       const thinking = resolvedConfig.thinking;
       const inheritContext = resolvedConfig.inheritContext;

package/src/model-resolver.ts

@@ -14,6 +14,45 @@ export interface ModelRegistry {
   getAvailable?(): any[];
 }
 
+/** Successful model resolution — `model` is the resolved or inherited model instance. */
+export interface ModelResolutionResult {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  model: any;
+  error?: undefined;
+}
+
+/** Failed model resolution when the model was user-specified (params) — surface the error. */
+export interface ModelResolutionError {
+  model?: undefined;
+  error: string;
+}
+
+/** Discriminated union returned by `resolveInvocationModel`. */
+export type ModelResolution = ModelResolutionResult | ModelResolutionError;
+
+/**
+ * Resolve the effective model for an agent invocation.
+ *
+ * Encapsulates the three-branch fallback policy used in `Agent.execute`:
+ * 1. No `modelInput` → inherit `parentModel`.
+ * 2. `modelInput` resolves → return the resolved model.
+ * 3. `modelInput` fails:
+ *    - `modelFromParams` true  → return `{ error }` so the caller can surface it.
+ *    - `modelFromParams` false → silent fallback to `parentModel`.
+ */
+export function resolveInvocationModel(
+  parentModel: unknown,
+  modelInput: string | undefined,
+  modelFromParams: boolean,
+  registry: ModelRegistry,
+): ModelResolution {
+  if (!modelInput) return { model: parentModel };
+  const resolved = resolveModel(modelInput, registry);
+  if (typeof resolved !== "string") return { model: resolved };
+  if (modelFromParams) return { error: resolved };
+  return { model: parentModel };
+}
+
 /**
  * Resolve a model string to a Model instance.
  * Tries exact match first ("provider/modelId"), then fuzzy match against all available models.

package/src/service-adapter.ts

@@ -0,0 +1,130 @@
+/**
+ * service-adapter.ts — Adapter that wraps AgentManager to satisfy SubagentsService.
+ *
+ * Handles model resolution at the API boundary, record serialization
+ * (stripping non-serializable fields), and session gating.
+ */
+
+import type { ModelRegistry } from "./model-resolver.js";
+import type { SubagentRecord, SubagentsService } from "./service.js";
+import type { AgentRecord } from "./types.js";
+
+/** Narrow interface for the AgentManager — avoids coupling to the concrete class. */
+export interface AgentManagerLike {
+  spawn(pi: unknown, ctx: unknown, type: string, prompt: string, options: unknown): string;
+  getRecord(id: string): AgentRecord | undefined;
+  listAgents(): AgentRecord[];
+  abort(id: string): boolean;
+  waitForAll(): Promise<void>;
+  hasRunning(): boolean;
+}
+
+/** Dependencies injected into the adapter factory. */
+export interface AdapterDeps {
+  manager: AgentManagerLike;
+  resolveModel: (input: string, registry: ModelRegistry) => unknown | string;
+  getCtx: () => { pi: unknown; ctx: unknown } | undefined;
+  getModelRegistry: () => ModelRegistry | undefined;
+}
+
+/** Create a SubagentsService backed by the given dependencies. */
+export function createSubagentsService(deps: AdapterDeps): SubagentsService {
+  const { manager } = deps;
+
+  return {
+    spawn(type: string, prompt: string, options?) {
+      const session = deps.getCtx();
+      if (!session) {
+        throw new Error("No active session — cannot spawn agents outside a session.");
+      }
+
+      let model: unknown;
+      if (options?.model) {
+        const registry = deps.getModelRegistry();
+        if (!registry) {
+          throw new Error("No model registry available.");
+        }
+        const resolved = deps.resolveModel(options.model, registry);
+        if (typeof resolved === "string") {
+          throw new Error(resolved);
+        }
+        model = resolved;
+      }
+
+      const description = options?.description ?? prompt.slice(0, 80);
+      const isBackground = !(options?.foreground ?? false);
+
+      return manager.spawn(session.pi, session.ctx, type, prompt, {
+        description,
+        model,
+        maxTurns: options?.maxTurns,
+        thinkingLevel: options?.thinkingLevel,
+        isolated: options?.isolated,
+        inheritContext: options?.inheritContext,
+        bypassQueue: options?.bypassQueue,
+        isolation: options?.isolation,
+        isBackground,
+      });
+    },
+
+    getRecord(id: string): SubagentRecord | undefined {
+      const record = manager.getRecord(id);
+      return record ? toSubagentRecord(record) : undefined;
+    },
+
+    listAgents(): SubagentRecord[] {
+      return manager.listAgents().map(toSubagentRecord);
+    },
+
+    abort(id: string): boolean {
+      return manager.abort(id);
+    },
+
+    async steer(id: string, message: string): Promise<boolean> {
+      const record = manager.getRecord(id);
+      if (!record || record.status !== "running") {
+        return false;
+      }
+      if (!record.session) {
+        // Session not ready yet — queue for delivery once initialized
+        if (!record.pendingSteers) record.pendingSteers = [];
+        record.pendingSteers.push(message);
+        return true;
+      }
+      await record.session.steer(message);
+      return true;
+    },
+
+    async waitForAll(): Promise<void> {
+      return manager.waitForAll();
+    },
+
+    hasRunning(): boolean {
+      return manager.hasRunning();
+    },
+  };
+}
+
+/**
+ * Convert an internal AgentRecord to a serializable SubagentRecord.
+ * Uses an explicit allowlist — new fields must be opted in.
+ */
+export function toSubagentRecord(record: AgentRecord): SubagentRecord {
+  const out: SubagentRecord = {
+    id: record.id,
+    type: record.type,
+    description: record.description,
+    status: record.status,
+    toolUses: record.toolUses,
+    startedAt: record.startedAt,
+    lifetimeUsage: record.lifetimeUsage,
+    compactionCount: record.compactionCount,
+  };
+
+  if (record.result !== undefined) out.result = record.result;
+  if (record.error !== undefined) out.error = record.error;
+  if (record.completedAt !== undefined) out.completedAt = record.completedAt;
+  if (record.worktreeResult !== undefined) out.worktreeResult = record.worktreeResult;
+
+  return out;
+}

package/src/service.ts

@@ -0,0 +1,104 @@
+/**
+ * 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("@gotgenes/pi-subagents");
+ *   const svc = getSubagentsService();
+ *   svc?.spawn("Explore", "Check for stale TODOs");
+ */
+
+import type { LifetimeUsage } from "./usage.js";
+
+export type { LifetimeUsage };
+
+export type SubagentStatus =
+  | "queued"
+  | "running"
+  | "completed"
+  | "steered"
+  | "aborted"
+  | "stopped"
+  | "error";
+
+/** Serializable snapshot of an agent's state — no live session objects. */
+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 };
+}
+
+/** Options for spawning an agent via the service. */
+export interface SpawnOptions {
+  description?: string;
+  model?: string;
+  maxTurns?: number;
+  thinkingLevel?: string;
+  isolated?: boolean;
+  inheritContext?: boolean;
+  foreground?: boolean;
+  bypassQueue?: boolean;
+  isolation?: "worktree";
+}
+
+/** The public service contract for cross-extension subagent access. */
+export 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;
+}
+
+/** Event channel constants for pi.events subscriptions. */
+export const SUBAGENT_EVENTS = {
+  STARTED: "subagents:started",
+  COMPLETED: "subagents:completed",
+  ACTIVITY: "subagents:activity",
+} as const;
+
+// ---- Accessor functions ----
+
+const SERVICE_KEY = Symbol.for("@gotgenes/pi-subagents:service");
+
+/** Publish the SubagentsService on globalThis for cross-extension access. */
+export function publishSubagentsService(service: SubagentsService): void {
+  (globalThis as Record<symbol, unknown>)[SERVICE_KEY] = service;
+}
+
+/** Retrieve the published SubagentsService, or undefined if not yet published. */
+export function getSubagentsService(): SubagentsService | undefined {
+  return (globalThis as Record<symbol, unknown>)[SERVICE_KEY] as
+    | SubagentsService
+    | undefined;
+}
+
+/** Remove the SubagentsService from globalThis (call on shutdown/reload). */
+export function unpublishSubagentsService(): void {
+  delete (globalThis as Record<symbol, unknown>)[SERVICE_KEY];
+}