@gotgenes/pi-subagents 11.5.0 → 11.6.0

package/CHANGELOG.md

@@ -5,6 +5,13 @@ 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).
 
+## [11.6.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v11.5.0...pi-subagents-v11.6.0) (2026-05-29)
+
+
+### Features
+
+* **pi-subagents:** publish bundled type declarations and fix stale exports path ([8eda6f6](https://github.com/gotgenes/pi-packages/commit/8eda6f6611a12c60d99a5069f352abd634997e67))
+
 ## [11.5.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v11.4.0...pi-subagents-v11.5.0) (2026-05-29)
 
 

package/dist/public.d.ts

@@ -0,0 +1,178 @@
+import { ThinkingLevel } from '@earendil-works/pi-ai';
+
+/** usage.ts — Token usage: shapes, accumulator operators, session-stats readers. */
+/**
+ * Lifetime usage components, accumulated via `message_end` events. Survives
+ * compaction (which replaces session.state.messages and would reset any
+ * stats-derived sum). cacheRead is excluded because each turn's cacheRead is
+ * the cumulative cached prefix re-read on that one call — summing across
+ * turns counts the prefix N times. See issue #38.
+ */
+type LifetimeUsage = {
+    input: number;
+    output: number;
+    cacheWrite: number;
+};
+
+/**
+ * types.ts — Type definitions for the subagent system.
+ */
+
+/** Agent type: any string name (built-in defaults or user-defined). */
+type SubagentType = string;
+/** Isolation mode for agent execution. */
+type IsolationMode = "worktree";
+interface AgentInvocation {
+    /** Short display name, e.g. "haiku" — only set when different from parent. */
+    modelName?: string;
+    thinking?: ThinkingLevel;
+    maxTurns?: number;
+    isolated?: boolean;
+    inheritContext?: boolean;
+    runInBackground?: boolean;
+    isolation?: IsolationMode;
+}
+
+/**
+ * agent.ts — Agent class with encapsulated status-transition logic and per-agent behavior.
+ *
+ * Status transitions (status, result, error, startedAt, completedAt) are owned
+ * by the class and exposed via transition methods. External code reads these
+ * fields through public properties but cannot write them directly.
+ *
+ * Stats (toolUses, lifetimeUsage, compactionCount) are owned by the class and
+ * accumulated via mutation methods (incrementToolUses, addUsage, incrementCompactions).
+ *
+ * Behavior (abort, steer buffering, worktree setup) lives on the agent
+ * rather than on AgentManager — each agent manages its own lifecycle concerns.
+ *
+ * Worktree isolation is delegated to an optional WorktreeIsolation collaborator
+ * (set at construction when isolation is requested); its presence IS the mode.
+ *
+ * Phase-specific collaborators (execution, notification) are attached
+ * after construction as lifecycle information becomes available.
+ */
+
+type AgentStatus = "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
+
+/**
+ * workspace.ts — The single generative extension seam (ADR 0002, Phase 16 Step 2).
+ *
+ * "Where does a child run, and what brackets the run?" is a strategy (git
+ * worktree, container, tmpdir, remote sandbox), not core behavior. The core
+ * needs only a working directory plus a disposal hook; the default — the
+ * parent's cwd, with no setup/teardown — is always correct.
+ *
+ * Unlike the observational lifecycle events in child-lifecycle.ts, this is a
+ * *generative* seam: a registered provider returns a value the core consumes
+ * synchronously at run-start. The core has no knowledge of git or worktrees.
+ */
+
+/** Context the core hands a provider when a child run starts. */
+interface WorkspacePrepareContext {
+    agentId: string;
+    agentType: SubagentType;
+    baseCwd: string;
+    invocation?: AgentInvocation;
+}
+/** Outcome the core reports to a workspace when the run ends. */
+interface WorkspaceDisposeOutcome {
+    status: AgentStatus;
+    description: string;
+}
+/** What dispose may hand back for the core to fold into the child result. */
+interface WorkspaceDisposeResult {
+    /** Appended verbatim to the child's result text — the provider owns the wording. */
+    resultAddendum?: string;
+}
+/** A prepared working directory plus its bracketed teardown. Born complete. */
+interface Workspace {
+    /** The working directory — already exists when the workspace is handed back. */
+    readonly cwd: string;
+    dispose(outcome: WorkspaceDisposeOutcome): WorkspaceDisposeResult | undefined;
+}
+/** The single generative seam: supplies a child's workspace. */
+interface WorkspaceProvider {
+    prepare(ctx: WorkspacePrepareContext): Promise<Workspace | undefined>;
+}
+
+/**
+ * service.ts — Public API surface for cross-extension access to subagents.
+ *
+ * Consumers declare this package as an optional peer dependency and use
+ * dynamic import to access the accessor functions:
+ *
+ *   const { getSubagentsService } = await import("@gotgenes/pi-subagents");
+ *   const svc = getSubagentsService();
+ *   svc?.spawn("Explore", "Check for stale TODOs");
+ */
+
+type SubagentStatus = "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
+/** Serializable snapshot of an agent's state — no live session objects. */
+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. */
+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. */
+interface SubagentsService {
+    /** Spawn an agent. Returns the agent ID immediately. */
+    spawn(type: string, prompt: string, options?: SpawnOptions): string;
+    /** Get a snapshot of an agent's current state. */
+    getRecord(id: string): SubagentRecord | undefined;
+    /** List all tracked agents, most recent first. */
+    listAgents(): SubagentRecord[];
+    /** Abort a running or queued agent. Returns false if not found. */
+    abort(id: string): boolean;
+    /** Send a steering message to a running agent. */
+    steer(id: string, message: string): Promise<boolean>;
+    /** Wait for all running and queued agents to complete. */
+    waitForAll(): Promise<void>;
+    /** Whether any agents are running or queued. */
+    hasRunning(): boolean;
+    /**
+     * Register the single workspace provider that supplies a child's working
+     * directory plus bracketed setup/teardown. Throws if one is already
+     * registered. Returns a disposer that unregisters the provider.
+     */
+    registerWorkspaceProvider(provider: WorkspaceProvider): () => void;
+}
+/** Event channel constants for pi.events subscriptions. */
+declare const SUBAGENT_EVENTS: {
+    readonly STARTED: "subagents:started";
+    readonly COMPLETED: "subagents:completed";
+    readonly ACTIVITY: "subagents:activity";
+};
+/** Publish the SubagentsService on globalThis for cross-extension access. */
+declare function publishSubagentsService(service: SubagentsService): void;
+/** Retrieve the published SubagentsService, or undefined if not yet published. */
+declare function getSubagentsService(): SubagentsService | undefined;
+/** Remove the SubagentsService from globalThis (call on shutdown/reload). */
+declare function unpublishSubagentsService(): void;
+
+export { SUBAGENT_EVENTS, getSubagentsService, publishSubagentsService, unpublishSubagentsService };
+export type { LifetimeUsage, SpawnOptions, SubagentRecord, SubagentStatus, SubagentsService, WorkspaceProvider };

package/docs/decisions/0003-publish-bundled-type-declarations.md

@@ -0,0 +1,69 @@
+---
+status: accepted
+date: 2026-05-29
+---
+
+# 0003 — Publish a bundled `.d.ts` for the public surface
+
+## Status
+
+Accepted.
+Introduces the repository's first build step, scoped to type declarations only.
+
+## Context
+
+`@gotgenes/pi-subagents` could not be imported by another TypeScript package in this workspace.
+Issue #263 (extract worktree isolation to `@gotgenes/pi-subagents-worktrees`) is the first intra-repo consumer: it must `implements WorkspaceProvider` and call `getSubagentsService().registerWorkspaceProvider(...)`, both of which require importing the package by name.
+
+A `tsc --traceResolution` of a sibling consuming the package surfaced two compounding failures.
+
+1. `package.json` `exports["."]` pointed at `./src/service.ts`, which does not exist — the real module is `./src/service/service.ts`.
+   A latent bug, unnoticed because nothing in-repo imported the package by name.
+2. Once corrected, the public entry's internal alias imports cascade.
+   `service/service.ts` imports `type LifetimeUsage` and `type WorkspaceProvider` via the `#src/*` alias.
+   When a sibling's `tsc` follows the symlink, the consumer's own `paths` (`#src/*` → `./src/*`) intercept first and resolve into the *consumer's* `src/` — a global-`paths` collision, since both packages define `#src/*`.
+   The fallback to the publisher's `package.json` `imports` field also fails: `tsc` cannot resolve the extensionless `.ts` target under Node `imports` semantics ("Import specifier '#src/lifecycle/usage' does not exist in package.json scope").
+
+The public entry's type closure is deeply entangled: `WorkspaceProvider` (in `lifecycle/workspace.ts`) reaches `AgentStatus` in the 510-line `lifecycle/agent.ts`, plus `SubagentType`/`AgentInvocation` from `types.ts` (which itself re-exports the `Agent` class).
+A shallow alias-free entry is therefore not achievable without a substantial source restructure.
+
+This collides with the ship-source model (ADR 0002): every package ships raw `.ts` executed directly by Pi, with no build step.
+
+## Decision
+
+Emit a single, self-contained `dist/public.d.ts` for the public surface and advertise it through a `types` export condition, while the runtime entry continues to serve `.ts` source.
+
+```jsonc
+"exports": {
+  ".": {
+    "types": "./dist/public.d.ts",
+    "default": "./src/service/service.ts"
+  }
+}
+```
+
+- `rollup-plugin-dts` rolls the declaration graph rooted at `src/service/service.ts` into one file, inlining the internal `#src/*` types and keeping peer-dependency types (`@earendil-works/*`, `@sinclair/typebox`) external.
+  We ship `.ts` source, so only the declaration bundle is emitted — no JS.
+- The bundle is generated at `prepack` time and shipped via a `files` allowlist; it is gitignored and never committed.
+- `default` → `./src/service/service.ts` fixes the stale path and serves runtime consumers; its `import type` lines erase, so no runtime `#src/*` resolution is needed.
+- A `pnpm pack` → throwaway-consumer → `tsc` harness proves external consumability with no publish round-trip and no workspace privileges.
+
+This is the repository's first build step.
+It is deliberately narrow: it produces type declarations only and changes nothing about how Pi loads the extension from source (`pi.extensions: ["./src/index.ts"]` is untouched).
+
+## Alternatives considered
+
+- Alias-free public entry (restructure the source so the entry's full type closure resolves via same-directory `./` imports).
+  Mechanically possible, but it requires moving the `AgentStatus`/`SubagentType`/`AgentInvocation`/`WorkspaceProvider` definitions and untangling the `agent.ts`/`types.ts` graph, with care that inner layers do not import the outer service layer.
+  `eslint`'s `no-parent-relative-imports` rule (which forbids `../`) narrows the options further.
+  Larger blast radius than emitting a `.d.ts`, and it churns the domain model to serve a packaging concern.
+- A self-contained entry that re-declares the public types inline, guarded by a conformance test.
+  Avoids a build step but duplicates the seam/usage/status type definitions, which drift over time.
+
+## Consequences
+
+- The repository now has a build step, but it is type-only and isolated to this package; the ship-source model is otherwise intact.
+- Consumers (including `@gotgenes/pi-subagents-worktrees` in #263) consume the packaged public interface like any external developer — no `workspace:*` privileges.
+- The `types` condition points at a build-time artifact; an in-repo workspace-linked consumer that imported the package would need `dist/public.d.ts` present.
+  This is acceptable because no in-repo package imports the surface yet; #263 consumes the built artifact from the published tarball.
+- Sequencing: #270 must be published (its release-please PR merged) before #263 edits `pi-subagents` core, so #263's changes do not batch into the same `pi-subagents` release.

package/docs/plans/0270-type-consumable-public-surface.md

@@ -0,0 +1,202 @@
+---
+issue: 270
+issue_title: "Make @gotgenes/pi-subagents type-consumable by sibling workspace packages"
+---
+
+# Publish a bundled `.d.ts` for the pi-subagents public surface
+
+## Problem Statement
+
+`@gotgenes/pi-subagents` cannot be imported by another TypeScript package in this workspace.
+A sibling that writes `import { getSubagentsService, type WorkspaceProvider } from "@gotgenes/pi-subagents"` fails its `tsc` run.
+This blocks Issue #263 (extract worktree isolation to `@gotgenes/pi-subagents-worktrees`), the first package that needs to import the subagents service and the `WorkspaceProvider` seam by name.
+
+Two compounding causes were confirmed empirically with `tsc --traceResolution`:
+
+1. `package.json` `exports["."]` points at `./src/service.ts`, which does not exist — the real module is `./src/service/service.ts`.
+   This is a latent bug; nothing in-repo imports the package by name today.
+2. Once the path is corrected, the public entry's internal alias imports cascade.
+   `service/service.ts` imports `type LifetimeUsage` and `type WorkspaceProvider` via `#src/*`.
+   When a sibling's `tsc` follows the symlink and resolves those specifiers, the consumer's own `paths` (`#src/*` → `./src/*`) intercept first and point into the *consumer's* `src/` (a global-`paths` collision — both packages even define `#src/*`).
+   The fallback to the publisher's `package.json` `imports` field then fails too: tsc cannot resolve the extensionless `.ts` target under Node `imports` semantics ("Import specifier '#src/lifecycle/usage' does not exist in package.json scope").
+
+The public entry's type closure is also deeply entangled: `WorkspaceProvider` (in `lifecycle/workspace.ts`) pulls in `AgentStatus` from the 510-line `lifecycle/agent.ts`, plus `SubagentType`/`AgentInvocation` from `types.ts` (which itself re-exports the `Agent` class).
+A shallow alias-free entry is therefore not achievable without a substantial source restructure.
+
+## Goals
+
+- A consumer using the **published/packaged** `@gotgenes/pi-subagents` can `import { getSubagentsService, type WorkspaceProvider } from "@gotgenes/pi-subagents"` and have `tsc` pass.
+- Fix the stale `exports["."]` path so it resolves to a real file.
+- Emit a self-contained (alias-free) `.d.ts` for the public surface via `rollup-plugin-dts`, generated at pack/publish time and shipped in the npm tarball.
+- Add a verification harness that proves external consumability via `pnpm pack` → throwaway consumer → `tsc`, with no publish round-trip.
+- No regression to how Pi loads the extension from source (`pi.extensions: ["./src/index.ts"]` is untouched).
+- `feat:` — adds a publishable capability (a typed public API surface) to `pi-subagents`.
+
+## Non-Goals
+
+- No source restructuring to make the entry alias-free (the rejected alternative — see Background).
+  `src/` modules and `#src/*` internal imports are left exactly as they are.
+- No removal of worktree code from the core (`worktree.ts`, `worktree-isolation.ts`, `IsolationMode`, `isolation` spawn mode) — that is Issue #263.
+- No change to `pi-subagents-worktrees`' dependency wiring: it stays on `workspace:*` and does not yet import `@gotgenes/pi-subagents`.
+  Flipping it to registry consumption (drop `workspace:*`, set `link-workspace-packages: false`, point at the fixed version, wire the real import) is deferred to Issue #263, because the registry version carrying this fix does not exist until #270 is published.
+- No registration of `pi-subagents-worktrees` into `release-please-config.json` — that belongs to Issue #263 when it is ready to publish.
+
+## Background
+
+Relevant modules and facts:
+
+- `packages/pi-subagents/src/service/service.ts` — the real public entry.
+  Locally declares the public service contract (`SubagentsService`, `SubagentRecord`, `SpawnOptions`, `SubagentStatus`, `SUBAGENT_EVENTS`) and the `Symbol.for()` accessor functions (`publishSubagentsService`, `getSubagentsService`, `unpublishSubagentsService`).
+  Its only internal imports are `import type { LifetimeUsage }` and `import type { WorkspaceProvider }` — both type-only, so they erase at runtime.
+- `src/lifecycle/workspace.ts` — defines `WorkspaceProvider`, `Workspace`, and the prepare/dispose context types.
+  Imports `AgentStatus` from `#src/lifecycle/agent` and `AgentInvocation`/`SubagentType` from `#src/types`.
+- `src/lifecycle/usage.ts` — defines `LifetimeUsage` plus internal runtime helpers.
+- `src/lifecycle/agent.ts` (510 LOC) — defines `AgentStatus` near the top, alongside the `Agent` class and a wide `#src/*` import graph.
+- `src/index.ts` — the Pi extension entry; imports `publishSubagentsService`/`unpublishSubagentsService` from `#src/service/service` (internal use, unaffected).
+
+Constraints from `AGENTS.md` and the package skill:
+
+- Ship-source model: every package ships raw `.ts` executed directly by Pi; there is no build step today.
+  ADR 0002 frames pi-subagents as a minimal core.
+  Introducing the repo's **first build step** is a deliberate decision and warrants an ADR.
+- `eslint`'s `no-parent-relative-imports` rule forbids `../` imports inside `packages/*/src`; same-directory `./` is allowed.
+  This (plus the deep type entanglement above) is why the alias-free-entry alternative was rejected.
+- New packages and internal docs subdirectories must be added to `release-please-config.json` `exclude-paths` where appropriate.
+
+Rejected alternative (recorded for the ADR): restructure the source so the entry's full type closure is alias-free (leaf types module imported via `./`).
+It is mechanically possible but requires moving `AgentStatus`/`SubagentType`/`AgentInvocation`/`WorkspaceProvider` definitions and reworking the `agent.ts`/`types.ts` entanglement, with care around dependency direction (inner layers must not import the outer service layer).
+Larger blast radius than emitting a `.d.ts`.
+
+Release/CI mechanics relevant to sequencing:
+
+- CI publishes only when the `release-please` PR is merged (`publish` job gated on `releases_created == true`), not on every push to `main`.
+- `release-please` batches all releasable commits per component.
+  The `#263` scaffold commits on `main` touch only the `pi-subagents-worktrees` component (which is **not** registered in `release-please-config.json`), so they neither trigger a release nor batch into `pi-subagents`.
+
+## Design Overview
+
+### Conditional exports
+
+Point the `types` condition at the bundled declaration and the runtime condition at the real source module:
+
+```jsonc
+"exports": {
+  ".": {
+    "types": "./dist/public.d.ts",
+    "default": "./src/service/service.ts"
+  }
+}
+```
+
+- `default` → `./src/service/service.ts` fixes the stale path and serves runtime `await import("@gotgenes/pi-subagents")` (the accessor functions; its `import type` lines erase, so no runtime `#src/*` resolution is needed).
+- `types` → `./dist/public.d.ts` gives a consumer's `tsc` a self-contained declaration that never references `#src/*`, sidestepping both the `paths` collision and the `imports`-field resolution failure.
+
+### Bundled declaration emit
+
+`rollup-plugin-dts` rolls the declaration graph rooted at `src/service/service.ts` into a single `dist/public.d.ts`.
+It tree-shakes to only the types reachable from the entry's exports — `SubagentsService`, `SubagentRecord`, `SpawnOptions`, `SubagentStatus`, `SUBAGENT_EVENTS`, the accessor signatures, plus the seam closure (`WorkspaceProvider`, `Workspace`, the context types, `AgentStatus`, `AgentInvocation`, `SubagentType`) and `LifetimeUsage`, all inlined.
+Imports from `@earendil-works/*` and `@sinclair/typebox` remain **external** in the output (the consumer has them as peers), so they are not inlined.
+
+We ship `.ts` source, so we want **only** the `.d.ts` — no JS bundle.
+`rollup-plugin-dts` does exactly that.
+
+Resolution note (primary feasibility risk): the roll-up must resolve the publisher's `#src/*` specifiers while parsing the type graph.
+`rollup-plugin-dts` drives the TypeScript compiler, which reads `compilerOptions.paths`; the build config references a tsconfig carrying the existing `#src/*` → `./src/*` paths.
+If `#src/*` does not resolve out of the box, add a tsconfig-paths/alias resolver to the rollup config.
+The first build step (below) is the checkpoint that proves this.
+
+### Generation timing and packaging
+
+- `prepack` runs `build:types` before both `pnpm pack` and `pnpm publish` (publish packs internally), so the tarball always contains a freshly generated `dist/public.d.ts`.
+- `dist/` is gitignored, so the artifact is **never committed**.
+- A `files` allowlist is added so the gitignored `dist/` is included in the published tarball.
+  The allowlist must preserve everything currently published (the whole `src/` tree, `docs/`, `README.md`, `LICENSE`, `CHANGELOG.md`, `AGENTS.md`, `.prettierignore`) plus `dist/`.
+  Validate parity with `pnpm pack --dry-run` before/after.
+
+### Verification harness (the proof)
+
+A script (run locally and in CI) proves external consumability without a publish:
+
+```bash
+# pseudocode — scripts/verify-public-types.sh
+pnpm --filter @gotgenes/pi-subagents pack --pack-destination "$TMP"   # triggers prepack → build:types
+cd "$TMP/consumer"                                                     # minimal package.json + tsconfig
+pnpm add "$TMP/gotgenes-pi-subagents-*.tgz" \
+  @earendil-works/pi-ai @earendil-works/pi-coding-agent @earendil-works/pi-tui typescript
+# probe.ts: import { getSubagentsService, type WorkspaceProvider } from "@gotgenes/pi-subagents"
+pnpm exec tsc --noEmit                                                 # must pass
+```
+
+Plus a cheap self-containment guard: assert `dist/public.d.ts` exists, exports the expected symbols, and contains no `#src/` substring (proving it is alias-free).
+
+## Module-Level Changes
+
+- `packages/pi-subagents/package.json`
+  - `exports["."]` → `{ "types": "./dist/public.d.ts", "default": "./src/service/service.ts" }`.
+  - Add `devDependencies`: `rollup`, `rollup-plugin-dts` (package-specific, not catalog — only this package builds types).
+  - Add scripts: `"build:types"` (runs rollup with the dts config) and `"prepack": "pnpm run build:types"`; add `"verify:public-types"` invoking the harness script.
+  - Add a `files` allowlist including `src`, `dist`, `docs`, `README.md`, `LICENSE`, `CHANGELOG.md`, `AGENTS.md`, `.prettierignore` (validated against `pnpm pack --dry-run`).
+- `packages/pi-subagents/rollup.dts.config.mjs` — **new**.
+  Entry `src/service/service.ts` → output `dist/public.d.ts`; `rollup-plugin-dts` with the package tsconfig (for `#src/*` paths); externals = peer deps + `@sinclair/typebox`.
+- `packages/pi-subagents/scripts/verify-public-types.sh` (or repo-level `scripts/`) — **new**.
+  Pack → throwaway consumer → `tsc`, plus the self-containment grep guard.
+- `.github/workflows/ci.yml`
+  - Add a "Verify public types" step in the `check` job (runs on PR and `main`) invoking `pnpm --filter @gotgenes/pi-subagents run verify:public-types`.
+- `packages/pi-subagents/docs/decisions/0003-publish-bundled-type-declarations.md` — **new** ADR.
+  Records the first-build-step decision, the rejected alias-free alternative, and the ship-source tradeoff (docs path; `exclude-paths` already covers `docs/decisions`, so it does not trigger a release).
+
+No `src/` module is added, renamed, or removed; no exported symbol is removed.
+No `docs/architecture/` layout/complexity tables reference `dist/` or the build config, so no architecture-doc edits are required beyond the ADR (optionally cross-link a one-line "build step" note — defer to build stage).
+
+## Test Impact Analysis
+
+This is a build/packaging change; `src/` is untouched, so the existing vitest suite (362 tests) is unaffected and stays as-is.
+
+1. New verification this enables: a packaged-artifact consumability check (`pnpm pack` → consumer `tsc`) that did not exist and was previously impossible (the package was not consumable at all).
+2. No existing tests become redundant — none currently exercise packaging or the public `exports`.
+3. No existing tests must change; the public service contract types in `service.ts` are unchanged.
+
+## Build Order
+
+This is a tooling/config change with a verification harness (not red→green→refactor), so it proceeds as build steps that each leave the repo valid.
+
+1. **Emit checkpoint.**
+   Add `rollup` + `rollup-plugin-dts` devDeps, write `rollup.dts.config.mjs`, add the `build:types` script.
+   Run `build:types`; confirm `dist/public.d.ts` is generated, exports the expected symbols, and contains no `#src/` substring (resolve the `#src/*` resolution risk here — add a paths/alias resolver if needed).
+   Commit: `build(pi-subagents): bundle public .d.ts with rollup-plugin-dts`.
+2. **Wire exports + packaging.**
+   Set the conditional `exports` (`types` + `default`, fixing the stale path), add `prepack`, add the `files` allowlist; validate `pnpm pack --dry-run` parity (no currently-shipped file dropped; `dist/public.d.ts` present).
+   Commit: `feat(pi-subagents): publish bundled type declarations and fix stale exports path`.
+3. **Verification harness + CI.**
+   Add `scripts/verify-public-types.sh` (pack → throwaway consumer → `tsc`, plus self-containment guard), the `verify:public-types` script, and the CI step.
+   Commit: `test(pi-subagents): verify the public surface is type-consumable from the packaged tarball`.
+4. **ADR.**
+   Add `docs/decisions/0003-publish-bundled-type-declarations.md`.
+   Commit: `docs(pi-subagents): record decision to publish bundled type declarations (ADR 0003)`.
+
+## Risks and Mitigations
+
+- **`rollup-plugin-dts` cannot resolve `#src/*`** (primary risk).
+  Mitigation: drive it with the package tsconfig (which carries `#src/*` paths); if needed, add a tsconfig-paths/alias resolver.
+  Step 1 is the explicit checkpoint — if it cannot produce an alias-free `dist/public.d.ts`, stop and reassess before wiring exports.
+- **Deep type graph via `agent.ts`.**
+  The seam closure reaches the 510-LOC `agent.ts`.
+  Mitigation: `rollup-plugin-dts` tree-shakes to only reachable types; the self-containment guard asserts the output is minimal and alias-free.
+- **`files` allowlist drops currently-published files.**
+  Mitigation: diff `pnpm pack --dry-run` before/after; the allowlist must reproduce the existing tarball plus `dist/`.
+- **`types` condition points at a gitignored, build-time artifact.**
+  An in-repo workspace-linked consumer that imported the package would need `dist/public.d.ts` present.
+  Mitigation: tight scope — `pi-subagents-worktrees` does not import the package yet; #263 consumes the built artifact from the published tarball.
+- **Release batching / ordering with #263.**
+  Once #263 resumes and edits `pi-subagents` core, its commits batch into the same `pi-subagents` release.
+  Mitigation: publish #270 first (merge its release-please PR → `pi-subagents` publishes), then resume #263 against the published version.
+  The current `#263` scaffold commits touch only the unregistered `pi-subagents-worktrees` component, so they do not batch into `pi-subagents` today.
+- **`prepack` must fire under the publish path.**
+  `scripts/publish-released.sh` runs `pnpm --filter @gotgenes/pi-subagents publish`, which packs and therefore runs `prepack`.
+  Mitigation: the verification harness exercises the same `pnpm pack` path that publish uses.
+
+## Open Questions
+
+- Whether to add a fast vitest self-containment assertion in addition to the shell harness, or keep the guard inside the script only — defer to the build stage.
+- Whether the ADR should add a short "build process" subsection to `docs/architecture/architecture.md` — defer; the ADR is sufficient.
+- Exact `files` allowlist entries — finalize against `pnpm pack --dry-run` in Step 2.

package/docs/retro/0262-add-workspace-provider-seam.md

@@ -42,3 +42,46 @@ All deterministic gates green: `check`, `lint`, `test`, and `fallow dead-code` (
 - Used `git commit --fixup` + `--autosquash` rebase twice (unpushed history) to fold the fallow trim into the Step 1 `feat` commit and the reviewer's doc-wording fix into the Step 3 `docs` commit, keeping each commit self-consistent.
 - Pre-completion reviewer: WARN — all blocking checks pass; one non-blocking doc finding (architecture.md overstated that `Workspace` is re-exported).
   Addressed before finishing.
+
+## Stage: Final Retrospective (2026-05-29T15:40:54Z)
+
+### Session summary
+
+Shipped #262: pushed, CI green, closed the issue, and merged release-please PR #269 → `pi-subagents-v11.5.0`.
+Mid-session the user asked what `model: claude-sonnet-4-6-20260526` in `.pi/agents/pre-completion-reviewer.md` resolved to; investigation found it had no entry in Pi's model registry and was silently falling back to the parent session model, and the fix (`anthropic/claude-sonnet-4-6`) landed in `1e46c5f4`.
+Across all stages the plan's risk predictions held and TDD verification was incremental.
+
+### Observations
+
+#### What went well
+
+- The planning-stage "vacant hook" risk prediction manifested exactly as predicted at the `fallow dead-code` gate: the plan named the failure (speculative re-exports flagged dead) before it happened, and the fix (re-export only `WorkspaceProvider`) was already reasoned out — a clean closed loop from planning risk to implementation gate.
+- Incremental verification during TDD: `check` / `test` / `lint` ran after each step plus per-file vitest red→green, not just at the end.
+- The model-spec question surfaced and fixed a latent silent bug — the reviewer's configured `model:` had no registry entry and was inheriting the parent model, so the misconfiguration produced no error.
+- Cost discipline: the session model was switched to `opencode-go/deepseek-v4-flash` for the mechanical shipping stage — appropriate model-to-task matching.
+
+#### What caused friction (agent side)
+
+- `rabbit-hole` — the model-resolution investigation (≈30 tool calls, turns 119–160) grepped the Pi core monorepo (`~/development/pi/pi/packages/coding-agent`) for `.pi/agents/` frontmatter handling that does not live there, before landing on `pi-prompt-template-model/model-selection.ts` (a `pi-packages` dependency) plus the `models.generated.ts` registry.
+  Impact: long detour on a user tangent; no rework, but the answer was reachable far sooner.
+- `other` (minor, recurring) — the pre-commit `trim trailing whitespace` hook reformatted files on the first `git commit`, failing it; the immediate retry succeeded (turns 55→56 and 95→96).
+  Impact: one wasted commit attempt per occurrence, no rework.
+
+#### What caused friction (user side)
+
+- The broken model spec was pre-existing config; because the failure mode is a silent fallback, such typos never surface on their own.
+  Opportunity (not criticism): a short convention note so future `.pi/agents/*.md` authoring uses the registry-resolvable `provider/id` form.
+
+### Diagnostic details
+
+- **Model-performance correlation** — the `pre-completion-reviewer` subagent was dispatched (turn 90) while the parent model was `anthropic/claude-opus-4-8`; because its `model:` frontmatter did not resolve, it ran on opus-4-8 (strong reasoning, appropriate for judgment-heavy review) rather than the configured Sonnet.
+  No quality mismatch in outcome, but the risk was latent: a weaker parent model would have silently degraded the reviewer.
+  The shipping stage ran on `deepseek-v4-flash` (mechanical git/CI/release ops) — appropriate.
+- **Escalation-delay tracking** — the model-resolution `rabbit-hole` ran ≈30 consecutive search calls on the same goal, far past the 5-call threshold; consulting the `prompt-template-authoring` skill or reading `model-selection.ts` first would have shortcut it.
+- **Unused-tool detection** — for that investigation the `prompt-template-authoring` skill (documents template/agent `model:` format) and `code_search` were available but not used; grep over two monorepos was used instead.
+- **Feedback-loop gap analysis** — none; verification ran incrementally after each TDD step, not only at the end.
+
+### Changes made
+
+1. `AGENTS.md` (Pre-completion reviewer subsection) — added a one-line guardrail: agent `model:` frontmatter must use the `provider/id` alias form the Pi CLI/UI accepts, because an ID absent from the model registry silently falls back to the parent session model.
+2. `packages/pi-subagents/docs/retro/0262-add-workspace-provider-seam.md` — this Final Retrospective stage entry.

package/docs/retro/0270-type-consumable-public-surface.md

@@ -0,0 +1,56 @@
+---
+issue: 270
+issue_title: "Make @gotgenes/pi-subagents type-consumable by sibling workspace packages"
+---
+
+# Retro: #270 — Make @gotgenes/pi-subagents type-consumable by sibling workspace packages
+
+## Stage: Planning (2026-05-29T00:00:00Z)
+
+### Session summary
+
+Diagnosed the consumability failure empirically with `tsc --traceResolution` and planned a `.d.ts`-emit fix.
+The plan adds a `rollup-plugin-dts` build that bundles `src/service/service.ts` into a self-contained `dist/public.d.ts`, wires conditional `exports` (`types` → the bundle, `default` → the real source), generates the artifact at `prepack` time, ships it via a `files` allowlist, and proves external consumability with a `pnpm pack` → throwaway-consumer → `tsc` harness.
+
+### Observations
+
+- Root cause is two compounding failures: the stale `exports["."]` path (`./src/service.ts` does not exist) and, once fixed, an unresolvable `#src/*` cascade.
+  The trace showed the consumer's own `paths` (`#src/*` → `./src/*`) intercept first (both packages define `#src/*`), and the publisher's `imports`-field fallback cannot resolve the extensionless `.ts` target.
+- The public type closure is entangled: `WorkspaceProvider` → `AgentStatus` (in the 510-LOC `agent.ts`) → `types.ts` (which re-exports the `Agent` class).
+  This made the alias-free-entry alternative (Option 2) a substantial source restructure, so it was rejected.
+- Decisions taken via `ask_user`:
+  1. Approach — emit a bundled `.d.ts` (the repo's first build step), over alias-free restructure or type re-declaration.
+  2. Bundler — `rollup-plugin-dts` (purpose-built for flattening declarations; no JS bundle, which suits ship-source), over `tsdown`/`api-extractor`.
+  3. Artifact — not committed; generated at `prepack` and shipped in the tarball, consumed via the package interface.
+  4. Scope — tight: packaging + a `pnpm pack`-based verification harness in #270; defer the `pi-subagents-worktrees` registry-consumption flip (drop `workspace:*`, `link-workspace-packages: false`, wire the real import) to #263.
+- Scope was deliberately narrowed after a chicken-and-egg surfaced: the registry version carrying the fix does not exist until #270 publishes, so the meaningful consumer flip belongs to #263.
+- Sequencing constraint for #263 (captured in the plan): publish #270 first — merge its release-please PR so `pi-subagents` publishes — *before* resuming #263, otherwise #263's `pi-subagents` core edits batch into the same release.
+  The current `#263` scaffold commits on `main` touch only the unregistered `pi-subagents-worktrees` component, so they do not batch into `pi-subagents` and #270 ships cleanly.
+- Primary feasibility risk flagged: whether `rollup-plugin-dts` resolves `#src/*` while rolling up the type graph.
+  Build Step 1 is the explicit checkpoint (emit + assert the output is alias-free and exports the expected symbols).
+- `dist/` is gitignored and already excluded by eslint/biome; the new wrinkle is that a `files` allowlist is required so the gitignored `dist/public.d.ts` is included in the npm tarball — validate `pnpm pack --dry-run` parity so no currently-shipped file is dropped.
+
+## Stage: Implementation — Build (2026-05-29T00:00:00Z)
+
+### Session summary
+
+Executed all four build-order steps: added `rollup` + `rollup-plugin-dts` and a `build:types` script that bundles `src/service/service.ts` into a self-contained `dist/public.d.ts`; wired conditional `exports` (`types` + `default`, fixing the stale path) with a `prepack` hook and a `files` allowlist; added a `pnpm pack` → throwaway-consumer → `tsc` verification harness (`scripts/verify-public-types.sh`) plus a CI step; and recorded ADR 0003.
+A fifth commit documented the new build step in the `package-pi-subagents` skill (reviewer WARN).
+Root `pnpm run check`, root `pnpm run lint`, and `verify:public-types` all pass.
+
+### Observations
+
+- The primary feasibility risk (`rollup-plugin-dts` resolving `#src/*`) resolved cleanly out of the box: driving it with the package `tsconfig` (which carries the `#src/*` paths) produced a 178-line `dist/public.d.ts` with zero `#src/` residue and only `ThinkingLevel` kept external from `@earendil-works/pi-ai`.
+  No alias/path resolver plugin was needed.
+- Harness deviation (fixed in the same step): `pnpm add` in the isolated (`--ignore-workspace`) throwaway consumer exited non-zero with `ERR_PNPM_IGNORED_BUILDS` because it does not inherit the workspace `allowBuilds` approvals (`@google/genai`, `protobufjs`).
+  Fixed by adding `--ignore-scripts` — a type-check needs no dependency build scripts.
+  Worth remembering for any future packaged-consumer harness.
+- A subtle gotcha while debugging: `pnpm ... | tail; echo $?` reports `tail`'s exit, not pnpm's, which masked the real failure.
+  Use `set -o pipefail` or check the command directly.
+- `files` allowlist parity was validated with a before/after `pnpm pack --dry-run` diff: nothing dropped, only `dist/public.d.ts` added.
+  The allowlist reproduces the current contents (`src`, `docs`, `vitest.config.ts`, `AGENTS.md`, `CHANGELOG.md`, `.prettierignore`) plus `dist`.
+  Did not take the opportunity to slim the tarball (docs/test-config still ship) — that would be a separate deliberate change.
+- Runtime `default` → `./src/service/service.ts` is safe because that module's only internal imports are `import type`, which erase; no runtime `#src/*` resolution occurs.
+- No `src/`/`test/` `.ts` files were touched, so the vitest suite and `tsc` were unaffected (confirmed via root check).
+- Pre-completion reviewer: WARN — no findings attributable to this session.
+  Reviewer warnings: (1) the `package-pi-subagents` skill lacked a build-step note — addressed in commit `2ff5a375`; (2) `pnpm fallow dead-code` exits non-zero on a pre-existing finding in `packages/pi-subagents-worktrees/package.json` from the #263 scaffold (commit `9a7dcfc5`), out of scope for #270 and left for #263.

package/package.json

@@ -1,10 +1,22 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "11.5.0",
+  "version": "11.6.0",
   "type": "module",
   "exports": {
-    ".": "./src/service.ts"
+    ".": {
+      "types": "./dist/public.d.ts",
+      "default": "./src/service/service.ts"
+    }
   },
+  "files": [
+    "src",
+    "dist",
+    "docs",
+    "vitest.config.ts",
+    "AGENTS.md",
+    "CHANGELOG.md",
+    ".prettierignore"
+  ],
   "imports": {
     "#src/*": "./src/*",
     "#test/*": "./test/*"
@@ -51,6 +63,8 @@
     "@earendil-works/pi-coding-agent": "0.75.4",
     "@earendil-works/pi-tui": "0.75.4",
     "@types/node": "^22.15.3",
+    "rollup": "^4.60.4",
+    "rollup-plugin-dts": "^6.4.1",
     "rumdl": "^0.1.93",
     "typescript": "^6.0.3",
     "vitest": "^4.1.5"
@@ -64,6 +78,8 @@
   },
   "scripts": {
     "check": "tsc --noEmit",
+    "build:types": "rollup -c rollup.dts.config.mjs",
+    "verify:public-types": "bash scripts/verify-public-types.sh",
     "test": "vitest run",
     "test:watch": "vitest",
     "lint:md": "rumdl check *.md docs/**/*.md",