@gotgenes/pi-subagents 3.0.0 → 4.0.0

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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)
 
 

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/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.0.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"

package/src/index.ts

@@ -22,6 +22,8 @@ import { loadCustomAgents } from "./custom-agents.js";
 import { resolveAgentInvocationConfig } from "./invocation-config.js";
 import { type ModelRegistry, 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();

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];
+}