@gotgenes/pi-subagents 6.19.0 → 6.19.1

package/CHANGELOG.md

@@ -5,6 +5,16 @@ 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).
 
+## [6.19.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.19.0...pi-subagents-v6.19.1) (2026-05-24)
+
+
+### Documentation
+
+* plan replace any casts with SDK types ([#188](https://github.com/gotgenes/pi-packages/issues/188)) ([96207da](https://github.com/gotgenes/pi-packages/commit/96207dacf0035db11605d55a61132cf43f7c3b40))
+* **retro:** add planning stage notes for issue [#188](https://github.com/gotgenes/pi-packages/issues/188) ([6e38b12](https://github.com/gotgenes/pi-packages/commit/6e38b128a5bbaad3ca81b31adbf390482081a41e))
+* **retro:** add retro notes for issue [#172](https://github.com/gotgenes/pi-packages/issues/172) ([270c00a](https://github.com/gotgenes/pi-packages/commit/270c00a5f84bf454352443a6c57a6076803090c6))
+* **retro:** add TDD stage notes for issue [#188](https://github.com/gotgenes/pi-packages/issues/188) ([8a5f51a](https://github.com/gotgenes/pi-packages/commit/8a5f51a2fd02a143e85f176417b31af4a11b34f4))
+
 ## [6.19.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.18.8...pi-subagents-v6.19.0) (2026-05-24)
 
 

package/docs/plans/0188-replace-any-casts-with-sdk-types.md

@@ -0,0 +1,162 @@
+---
+issue: 188
+issue_title: "refactor(pi-subagents): replace any casts with SDK types in extractText and SubscribableSession"
+---
+
+# Replace `any` casts with SDK types
+
+## Problem Statement
+
+Two places in pi-subagents use `any` where proper SDK types are available and already imported in adjacent files.
+`extractText` in `session/context.ts` uses `(c: any)` in a filter/map chain, requiring a top-level `eslint-disable` for `no-unsafe-member-access` and `no-unsafe-return`.
+`record-observer.ts` and `ui-observer.ts` each define an identical local `SubscribableSession` interface with `(event: any) => void`, creating both a type hole and duplicated boilerplate.
+
+## Goals
+
+- Replace `any` casts in `extractText` with a `TextContent` type predicate.
+- Remove the `eslint-disable` comment from `session/context.ts`.
+- Replace `any` in the `SubscribableSession` interface with `AgentSessionEvent`.
+- Deduplicate the `SubscribableSession` interface into a single shared definition.
+
+## Non-Goals
+
+- Changing the `extractText` parameter type from `unknown[]` — callers in `message-formatters.ts` pass `unknown[]`, and widening the refactoring surface is out of scope.
+- Replacing the `SubscribableSession` interface with the full `AgentSession` class — ISP requires a narrow interface (the observers only need `subscribe`).
+- Addressing the `eslint-disable` in `record-observer.ts` and `ui-observer.ts` for `no-unsafe-member-access` / `no-unsafe-assignment` — those are caused by the `event` property access pattern inside the callback body, not by the parameter type.
+  Once the callback parameter is typed as `AgentSessionEvent`, the unsafe-access rules should be satisfied and those `eslint-disable` comments can be removed too.
+
+## Background
+
+### Existing conventions
+
+`content-items.ts` already imports `TextContent` from `@earendil-works/pi-ai` and uses `(c as TextContent).text` after a `c.type === "text"` guard.
+`agent-runner.ts` already imports `AgentSessionEvent` from `@earendil-works/pi-coding-agent` and uses it as the parameter type in `session.subscribe((event: AgentSessionEvent) => { ... })`.
+Both SDK types are proven to work in this package.
+
+### `extractText` callers
+
+`extractText(content: unknown[])` is called from:
+
+- `session/context.ts` — `buildParentContext` passes `msg.content` from session entries.
+- `lifecycle/agent-runner.ts` — `getLastAssistantText` and `getAgentConversation` pass `msg.content`.
+- `ui/message-formatters.ts` — `formatUserMessage` and `formatToolResult` pass `unknown[]` content.
+
+The parameter type stays `unknown[]` to avoid rippling through callers.
+The type predicate narrows inside the function body.
+
+### `SubscribableSession` consumers
+
+Both `subscribeRecordObserver` and `subscribeUIObserver` accept a `SubscribableSession` parameter.
+Tests use `createMockSession()` from `test/helpers/mock-session.ts`, which returns a `MockSession` with `subscribe: Mock<(fn: (event: unknown) => void) => () => void>`.
+
+Changing `SubscribableSession.subscribe` to accept `(event: AgentSessionEvent) => void` is structurally sound: the mock's `subscribe` accepting `(fn: (event: unknown) => void)` is a supertype — a function that accepts any event can accept an `AgentSessionEvent`.
+The TypeScript compiler allows this because of function parameter contravariance.
+Tests construct inline event objects that match `AgentSessionEvent` member shapes, so no test changes are needed.
+
+### Shared location for `SubscribableSession`
+
+The interface is used by two domains (observation, UI).
+A new shared types location is needed.
+The existing `types.ts` at the package root contains cross-cutting types (`SubagentType`, `ThinkingLevel`, `ShellExec`).
+`SubscribableSession` fits there — it's a narrow cross-domain interface for session event subscription.
+
+## Design Overview
+
+### `extractText` type predicate
+
+Replace the `any` casts with a user-defined type guard:
+
+```typescript
+import type { TextContent } from "@earendil-works/pi-ai";
+
+function isTextContent(c: unknown): c is TextContent {
+  return typeof c === "object" && c !== null && (c as { type: string }).type === "text";
+}
+
+export function extractText(content: unknown[]): string {
+  return content
+    .filter(isTextContent)
+    .map((c) => c.text ?? "")
+    .join("\n");
+}
+```
+
+The type predicate eliminates both `any` casts and the `eslint-disable` at the top of the file.
+
+### `SubscribableSession` with `AgentSessionEvent`
+
+Move the interface to `types.ts` and type the callback:
+
+```typescript
+import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+
+export interface SubscribableSession {
+  subscribe(fn: (event: AgentSessionEvent) => void): () => void;
+}
+```
+
+Both observer files import from `types.ts` instead of defining their own.
+
+### Event property access in observer callbacks
+
+Once the callback parameter is typed as `AgentSessionEvent`, TypeScript knows the event's discriminated union members.
+The `event.type` checks narrow the union, so `event.toolName`, `event.message`, etc. become type-safe.
+The `eslint-disable` comments for `no-unsafe-member-access` and `no-unsafe-assignment` can be removed from both observer files.
+
+## Module-Level Changes
+
+| File                                 | Change                                                                                                                                                        |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/session/context.ts`             | Import `TextContent`; add `isTextContent` type predicate; replace `any` filter/map; remove top-level `eslint-disable`                                         |
+| `src/types.ts`                       | Add `SubscribableSession` interface with `AgentSessionEvent` callback type; add `AgentSessionEvent` import                                                    |
+| `src/observation/record-observer.ts` | Import `SubscribableSession` from `types.ts`; remove local interface; remove top-level `eslint-disable`; remove inline `any` annotation on callback parameter |
+| `src/ui/ui-observer.ts`              | Import `SubscribableSession` from `types.ts`; remove local interface; remove top-level `eslint-disable`; remove inline `any` annotation on callback parameter |
+
+No test file changes expected — the mock session's structural typing remains compatible.
+
+## Test Impact Analysis
+
+1. No new unit tests are needed — the refactoring is type-only (no behavioral change).
+2. No existing tests become redundant.
+3. All existing tests for `subscribeRecordObserver` and `subscribeUIObserver` must pass as-is — they verify the same event-handling behavior.
+
+## TDD Order
+
+This is a pure refactoring with no behavioral change.
+Each step should pass `pnpm run check` (type-check) and `pnpm vitest run` (tests) before committing.
+
+1. **Add `isTextContent` type predicate and remove `any` from `extractText`.**
+   Import `TextContent` from `@earendil-works/pi-ai`.
+   Add `isTextContent` predicate function.
+   Replace the `any`-cast filter/map chain with the predicate.
+   Remove the top-level `eslint-disable` comment.
+   Verify: `pnpm run check`, `pnpm vitest run`.
+   Commit: `refactor: replace any casts in extractText with TextContent type predicate (#188)`
+
+2. **Move `SubscribableSession` to `types.ts` with `AgentSessionEvent`.**
+   Add `AgentSessionEvent` import and `SubscribableSession` interface to `src/types.ts`.
+   Update `record-observer.ts`: import from `types.ts`, remove local interface, remove `eslint-disable`, remove `any` from callback parameter.
+   Update `ui-observer.ts`: import from `types.ts`, remove local interface, remove `eslint-disable`, remove `any` from callback parameter.
+   Verify: `pnpm run check`, `pnpm vitest run`.
+   Commit: `refactor: replace any in SubscribableSession with AgentSessionEvent (#188)`
+
+## Risks and Mitigations
+
+1. **`AgentSessionEvent` union may not cover all event shapes accessed in observers.**
+   Mitigation: `agent-runner.ts` already uses the same type for identical event patterns (`event.type`, `event.toolName`, `event.message`).
+   The type checker will flag any property access that the union doesn't support.
+   Run `pnpm run check` after each step.
+
+2. **Mock session type incompatibility.**
+   The mock's `subscribe` accepts `(fn: (event: unknown) => void)`.
+   A `SubscribableSession` with `(fn: (event: AgentSessionEvent) => void)` is structurally compatible via contravariance.
+   If the compiler disagrees, the mitigation is to update `MockSession.subscribe` to accept `(fn: (event: AgentSessionEvent) => void)` — a one-line change.
+
+3. **`TextContent.text` is non-optional in the SDK type.**
+   The current code uses `c.text ?? ""` which implies `text` could be undefined.
+   `TextContent` defines `text: string` (required), so the nullish coalescing is harmless but unnecessary.
+   Keep it for safety — removing it is a separate cleanup.
+
+## Open Questions
+
+None — the issue's proposed approach is unambiguous and the SDK types are already validated in adjacent files.

package/docs/retro/0172-extract-turn-formatting.md

@@ -38,3 +38,43 @@ Test count went from 896 to 907 (+11).
 - `message-formatters.ts` had both an import and a re-export of `getToolCallName`; simplified to a pure re-export only.
 - The lint fixup (unused import) was amended into the same refactor commit before pushing.
 - Architecture doc updated: `content-items.ts` added to session module listing, production-duplication section updated, Step 9 marked Done.
+
+## Stage: Final Retrospective (2026-05-24T20:30:00Z)
+
+### Session summary
+
+Planned, implemented, and shipped the extraction of shared turn-formatting logic from `lifecycle/agent-runner.ts` and `ui/message-formatters.ts` into `session/content-items.ts`.
+Released as `pi-subagents-v6.19.0`.
+During code review the user challenged double-casts in the initial implementation, which led to discovering that the local `ToolCallContent` type was dead code and the SDK exports the real `ToolCall` type — the final implementation is significantly cleaner than what the plan specified.
+Filed #188 for broader `any`-to-SDK-type cleanup discovered during the investigation.
+
+### Observations
+
+#### What went well
+
+- The user's Socratic challenge ("Talk to me about these double-casts") was the pivotal moment.
+  Rather than directing a fix, it prompted an investigation of the SDK's actual `ToolCall` type, which revealed that `ToolCall.name` is always required and `toolName` never appears on content items.
+  This eliminated the `ToolCallContent` interface, the `toolName` fallback, the index-signature parameter type, and all double-casts — none of which the plan anticipated.
+- Cross-session retro context worked well: the planning-stage note about #170 shifting the duplication target saved time during TDD.
+- The SDK source investigation yielded a follow-up issue (#188) for replacing `any` casts in `extractText` and `SubscribableSession` with proper SDK types.
+
+#### What caused friction (agent side)
+
+- `missing-context` — Did not check SDK type exports during planning.
+  The plan copied `ToolCallContent` verbatim from the existing code without verifying what `@earendil-works/pi-ai` exports.
+  The source comments ("SDK doesn't export the narrow type") were wrong — the types have been exported for some time.
+  Impact: the initial TDD implementation introduced a `{ type: string; [key: string]: unknown }` parameter type that forced `as unknown as` double-casts, requiring a full rework after user review.
+- `premature-convergence` — When TypeScript rejected excess properties in test object literals, I widened the parameter type to include an index signature instead of exploring alternatives.
+  The correct fix (using `ReadonlyArray<{ type: string }>` with `in` narrowing, or importing SDK types as test fixtures) was simpler and avoided the cast cascade.
+  Impact: one round of rework plus an amended commit that muddied the git history.
+
+#### What caused friction (user side)
+
+- The user's intervention at the cast review stage was well-timed and effective.
+  One earlier opportunity: if the user had flagged the `toolName` fallback or the SDK-type question during the plan review (before TDD started), the initial implementation would have been correct from the start.
+  However, this is a marginal improvement — the plan review was clean and the friction was minor.
+
+### Changes made
+
+1. `.pi/skills/code-design/SKILL.md` — Added two rules to "Pi SDK boundaries": verify SDK exports before redeclaring types locally; prefer minimal structural supertypes over index-signature types for parameters accepting SDK content.
+2. `.pi/skills/testing/SKILL.md` — Added TDD planning rule: verify SDK exports when extracting locally-declared types that shadow SDK types.

package/docs/retro/0188-replace-any-casts-with-sdk-types.md

@@ -0,0 +1,40 @@
+---
+issue: 188
+issue_title: "refactor(pi-subagents): replace any casts with SDK types in extractText and SubscribableSession"
+---
+
+# Retro: #188 — Replace any casts with SDK types
+
+## Stage: Planning (2026-05-24T20:04:58Z)
+
+### Session summary
+
+Produced a two-step refactoring plan for replacing `any` casts in `extractText` (with a `TextContent` type predicate) and `SubscribableSession` (with `AgentSessionEvent`).
+Verified that both SDK types are already imported and used in adjacent files within the package.
+Confirmed mock session compatibility via function parameter contravariance — no test changes expected.
+
+### Observations
+
+- The `extractText` parameter type stays `unknown[]` to avoid rippling through callers in `message-formatters.ts` that declare `content: unknown[]`.
+  A future cleanup could tighten those caller signatures.
+- `SubscribableSession` moves to `src/types.ts` as the shared location, matching existing cross-domain types there (`SubagentType`, `ThinkingLevel`, `ShellExec`).
+- All three `eslint-disable` top-level comments (`context.ts`, `record-observer.ts`, `ui-observer.ts`) should be removable once the `any` casts are gone, since the SDK union's discriminated members cover the property access patterns.
+- Risk: if `AgentSessionEvent` doesn't cover `assistantMessageEvent` in `ui-observer.ts`, the type checker will surface it immediately — the mitigation is to check the union members during implementation.
+
+## Stage: Implementation — TDD (2026-05-24T20:17:38Z)
+
+### Session summary
+
+Completed both TDD steps from the plan.
+Step 1 replaced the `any` filter/map chain in `extractText` with an `isTextContent` type predicate; the `??""` removal was required because `TextContent.text` is non-optional per the SDK type.
+Step 2 moved `SubscribableSession` to `types.ts` typed with `AgentSessionEvent`, removed both duplicate local interfaces, and removed all three `eslint-disable` comments.
+Test count: 902 → 901 (one test removed).
+
+### Observations
+
+- The `??` operator on `c.text` in `extractText` triggered `@typescript-eslint/no-unnecessary-condition` at commit time because `TextContent.text` is `string` (non-nullable); removing it was necessary, not just cosmetic.
+- After typing the `record-observer` callback as `AgentSessionEvent`, five additional lint errors surfaced: `event.message?.role` (optional chain unnecessary since `MessageEndEvent.message` is required), `if (u)` guard (unnecessary since `AssistantMessage.usage` is required), and three `?? 0` guards on `input`/`output`/`cacheWrite` (all required `number` fields per `Usage` interface in the Pi source at `~/development/pi/pi/packages/ai/src/types.ts`).
+- The test `"ignores message_end without usage"` was removed — it emitted a non-conforming event that the SDK types guarantee cannot occur at runtime.
+- `ui-observer.ts` had one analogous fix: `event.assistantMessageEvent?.type` → `.type` (the field is required on `MessageUpdateEvent`).
+- No test file changes were needed for `ui-observer.ts` — its existing tests all emit conforming events.
+- The plan's contravariance reasoning about mock session compatibility was correct: `pnpm run check` passed without updating `MockSession.subscribe`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "6.19.0",
+  "version": "6.19.1",
   "type": "module",
   "exports": {
     ".": "./src/service.ts"

package/src/observation/record-observer.ts

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
 /**
  * record-observer.ts — Subscribes to session events and updates AgentRecord stats.
  *
@@ -8,11 +7,7 @@
 
 import type { CompactionInfo } from "#src/lifecycle/agent-manager";
 import type { AgentRecord } from "#src/lifecycle/agent-record";
-
-/** Narrow session interface — only the subscribe method needed by the observer. */
-interface SubscribableSession {
-  subscribe(fn: (event: any) => void): () => void;
-}
+import type { SubscribableSession } from "#src/types";
 
 export interface RecordObserverOptions {
   onCompact?: (record: AgentRecord, info: CompactionInfo) => void;
@@ -33,20 +28,18 @@ export function subscribeRecordObserver(
   record: AgentRecord,
   options?: RecordObserverOptions,
 ): () => void {
-  return session.subscribe((event: any) => {
+  return session.subscribe((event) => {
     if (event.type === "tool_execution_end") {
       record.incrementToolUses();
     }
 
-    if (event.type === "message_end" && event.message?.role === "assistant") {
+    if (event.type === "message_end" && event.message.role === "assistant") {
       const u = event.message.usage;
-      if (u) {
-        record.addUsage({
-          input: u.input ?? 0,
-          output: u.output ?? 0,
-          cacheWrite: u.cacheWrite ?? 0,
-        });
-      }
+      record.addUsage({
+        input: u.input,
+        output: u.output,
+        cacheWrite: u.cacheWrite,
+      });
     }
 
     if (event.type === "compaction_end" && !event.aborted && event.result) {

package/src/session/context.ts

@@ -1,15 +1,20 @@
-/* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-return -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
 /**
  * context.ts — Extract parent conversation context for subagent inheritance.
  */
 
+import type { TextContent } from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
+/** Type predicate: narrow an unknown content block to TextContent. */
+function isTextContent(c: unknown): c is TextContent {
+  return typeof c === "object" && c !== null && (c as { type: string }).type === "text";
+}
+
 /** Extract text from a message content block array. */
 export function extractText(content: unknown[]): string {
   return content
-    .filter((c: any) => c.type === "text")
-    .map((c: any) => c.text ?? "")
+    .filter(isTextContent)
+    .map((c) => c.text)
     .join("\n");
 }
 

package/src/types.ts

@@ -3,10 +3,19 @@
  */
 
 import type { ThinkingLevel } from "@earendil-works/pi-ai";
+import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
 
 
 export { AgentRecord } from "#src/lifecycle/agent-record";
-export type { ThinkingLevel };
+export type { AgentSessionEvent, ThinkingLevel };
+
+/**
+ * Narrow session interface for event subscription.
+ * Used by record-observer and ui-observer — only the subscribe method is needed.
+ */
+export interface SubscribableSession {
+  subscribe(fn: (event: AgentSessionEvent) => void): () => void;
+}
 
 /** Agent type: any string name (built-in defaults or user-defined). */
 export type SubagentType = string;

package/src/ui/ui-observer.ts

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-argument -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
 /**
  * ui-observer.ts — Subscribes to session events and updates AgentActivityTracker state.
  *
@@ -7,13 +6,9 @@
  * turn count, lifetime usage).
  */
 
+import type { SubscribableSession } from "#src/types";
 import type { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
 
-/** Narrow session interface — only the subscribe method needed by the observer. */
-interface SubscribableSession {
-	subscribe(fn: (event: any) => void): () => void;
-}
-
 /**
  * Subscribe to session events and stream UI state into an AgentActivityTracker.
  *
@@ -34,7 +29,7 @@ export function subscribeUIObserver(
 	tracker: AgentActivityTracker,
 	onUpdate?: () => void,
 ): () => void {
-	return session.subscribe((event: any) => {
+	return session.subscribe((event) => {
 		if (event.type === "tool_execution_start") {
 			tracker.onToolStart(event.toolName);
 			onUpdate?.();
@@ -51,7 +46,7 @@ export function subscribeUIObserver(
 
 		if (
 			event.type === "message_update" &&
-			event.assistantMessageEvent?.type === "text_delta"
+			event.assistantMessageEvent.type === "text_delta"
 		) {
 			tracker.onMessageUpdate(event.assistantMessageEvent.delta);
 			onUpdate?.();