@gotgenes/pi-subagents 6.17.2 → 6.18.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.18.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.17.2...pi-subagents-v6.18.0) (2026-05-24)
+
+
+### Features
+
+* add eslint config with type-aware rules and import enforcement ([4fb3cc6](https://github.com/gotgenes/pi-packages/commit/4fb3cc678da10d350b85c464318476ba9ae99dca))
+
+
+### Bug Fixes
+
+* **pi-subagents:** add missing "type": "module" to package.json ([8cfd07d](https://github.com/gotgenes/pi-packages/commit/8cfd07dfbfd44f52dc43ac7ae67d5824304825ae))
+
+
+### Documentation
+
+* **retro:** add retro notes for issue [#164](https://github.com/gotgenes/pi-packages/issues/164) ([d8e2861](https://github.com/gotgenes/pi-packages/commit/d8e28615d6adabc86415f4d41ffd1bd90184fd0f))
+
 ## [6.17.2](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.17.1...pi-subagents-v6.17.2) (2026-05-23)
 
 

package/docs/retro/0164-reorganize-into-domain-directories.md

@@ -44,3 +44,39 @@ Updated `docs/architecture/architecture.md` to reflect the completed restructuri
   This eliminates all `../` relative cross-directory imports from `src/`.
   Future file moves in `src/` now only require updating the `#src/domain/name` string — no relative depth arithmetic.
 - Biome auto-fixed 14 files (import sorting / trailing whitespace) during the `#src/` conversion step; committed via `git add -A` after the pre-commit hook run.
+
+## Stage: Final Retrospective (2026-05-23T17:10:00Z)
+
+### Session summary
+
+Shipped #164 (6 commits, `pi-subagents-v6.17.2`), filed #174 (ESLint for type-aware rules + import path enforcement), and reviewed the full issue lifecycle across planning, implementation, and shipping sessions.
+
+### Observations
+
+#### What went well
+
+- The user's mid-implementation redirect to use `#src/` aliases in `src/` files was the highest-impact intervention across the entire issue.
+  It eliminated the `../` depth-arithmetic problem, simplified the final commit to a one-liner `sed` command across 40 files, and directly motivated #174.
+- `pnpm run check` (`tsc --noEmit`) caught every missed consumer immediately — no broken commit ever landed.
+- The four-step dependency ordering (config → session → lifecycle+observation → service) kept every commit green despite the circular dependency between `lifecycle` and `observation`.
+
+#### What caused friction (agent side)
+
+- `wrong-abstraction` — Used ~60 individual `Edit` tool calls across steps 1–4 for what was a mechanical find-and-replace.
+  The fifth commit proved `sed` handles bulk import rewrites across 40 files in a single command.
+  Impact: hundreds of unnecessary tool calls and significant token waste across four commits.
+- `missing-context` — The plan's consumer tables missed 4 files (`src/ui/widget-renderer.ts`, `src/session-config.ts`, `src/service-adapter.ts`, `test/parent-snapshot.test.ts` `vi.mock` path).
+  The plan manually traced imports instead of using `grep` to enumerate all consumers of each moving module.
+  Impact: mid-step rework in steps 1, 2, and 3 to fix un-updated imports caught by `tsc`.
+- `missing-context` — Did not recognize that `src/` files should use `#src/` aliases (same as `test/` files) even though #157 set up the aliases for exactly this purpose.
+  Impact: all four domain-move commits used relative `../` imports, requiring a fifth unplanned commit to convert them.
+  User-caught.
+- `wrong-abstraction` — The agent lacks access to LSP-level refactoring tools ("Move to file", "Rename symbol") that a human developer would use for this kind of reorganization.
+  A human with an LSP would have completed the entire issue in minutes with zero missed consumers.
+  This is a fundamental capability gap — the agent compensated with low-level text manipulation, which is error-prone and token-expensive.
+
+#### What caused friction (user side)
+
+- The `#src/` alias convention was established in #157 but the user didn't flag it during the planning session.
+  Had this been raised during planning, all four domain-move commits would have used `#src/` from the start.
+  The user did catch it during implementation, which was still early enough to save the final result.

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "6.17.2",
+  "version": "6.18.0",
+  "type": "module",
   "exports": {
     ".": "./src/service.ts"
   },
@@ -66,6 +67,6 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "lint:md": "rumdl check *.md docs/**/*.md",
-    "lint": "biome check . && pnpm run lint:md"
+    "lint": "biome check . && eslint . && pnpm run lint:md"
   }
 }

package/src/config/custom-agents.ts

@@ -51,7 +51,7 @@ function loadFromDir(dir: string, agents: Map<string, AgentConfig>, source: "pro
       continue;
     }
 
-    const { frontmatter: fm, body } = parseFrontmatter<Record<string, unknown>>(content);
+    const { frontmatter: fm, body } = parseFrontmatter(content);
 
     agents.set(name, {
       name,
@@ -95,6 +95,7 @@ function nonNegativeInt(val: unknown): number | undefined {
  */
 function parseCsvField(val: unknown): string[] | undefined {
   if (val === undefined || val === null) return undefined;
+  // eslint-disable-next-line @typescript-eslint/no-base-to-string -- val is already narrowed past null/undefined; String() is the intended coercion here
   const s = String(val).trim();
   if (!s || s === "none") return undefined;
   const items = s.split(",").map(t => t.trim()).filter(Boolean);

package/src/handlers/lifecycle.ts

@@ -52,11 +52,12 @@ export class SessionLifecycleHandler {
   // 3. Abort all agents — stop running work
   // 4. Dispose notifications — cancel pending nudges/timers
   // 5. Dispose manager — final cleanup
-  async handleSessionShutdown(): Promise<void> {
+  handleSessionShutdown(): Promise<void> {
     this.unpublishService();
     this.runtime.clearSessionContext();
     this.manager.abortAll();
     this.disposeNotifications();
     this.manager.dispose();
+    return Promise.resolve();
   }
 }

package/src/index.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-argument -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
 /**
  * pi-agents — A pi extension providing Claude Code-style autonomous sub-agents.
  *

package/src/lifecycle/agent-manager.ts

@@ -235,6 +235,7 @@ export class AgentManager {
       onSessionCreated: (session) => {
         // Capture the session file path early so it's available for display
         // before the run completes (e.g. in background agent status messages).
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- sessionManager is typed as always present but Pi SDK may not provide it
         const outputFile = session.sessionManager?.getSessionFile?.() ?? undefined;
         // Set the execution-state collaborator — born complete at session creation.
         record.execution = { session, outputFile };
@@ -282,7 +283,7 @@ export class AgentManager {
         }
         return responseText;
       })
-      .catch((err) => {
+      .catch((err: unknown) => {
         record.markError(err);
 
         unsubRecordObserver?.();
@@ -313,7 +314,7 @@ export class AgentManager {
     while (this.queue.length > 0 && this.runningBackground < this._getMaxConcurrent()) {
       const next = this.queue.shift()!;
       const record = this.agents.get(next.id);
-      if (!record || record.status !== "queued") continue;
+      if (record?.status !== "queued") continue;
       try {
         this.startAgent(next.id, record, next.args);
       } catch (err) {
@@ -402,6 +403,7 @@ export class AgentManager {
 
   /** Dispose a record's session and remove it from the map. */
   private removeRecord(id: string, record: AgentRecord): void {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- dispose may not exist on all session implementations
     record.session?.dispose?.();
     this.agents.delete(id);
     this.pendingSteers.delete(id);
@@ -464,12 +466,13 @@ export class AgentManager {
   async waitForAll(): Promise<void> {
     // Loop because drainQueue respects the concurrency limit — as running
     // agents finish they start queued ones, which need awaiting too.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- intentional infinite loop with explicit break
     while (true) {
       this.drainQueue();
       const pending = [...this.agents.values()]
         .filter(r => r.status === "running" || r.status === "queued")
         .map(r => r.promise)
-        .filter(Boolean);
+        .filter((p): p is Promise<string> => p != null);
       if (pending.length === 0) break;
       await Promise.allSettled(pending);
     }

package/src/lifecycle/agent-runner.ts

@@ -246,7 +246,7 @@ function forwardAbortSignal(
   signal?: AbortSignal,
 ): () => void {
   if (!signal) return () => {};
-  const onAbort = () => session.abort();
+  const onAbort = (): void => { void session.abort(); };
   signal.addEventListener("abort", onAbort, { once: true });
   return () => signal.removeEventListener("abort", onAbort);
 }
@@ -375,12 +375,12 @@ export async function runAgent(
       if (maxTurns != null) {
         if (!softLimitReached && turnCount >= maxTurns) {
           softLimitReached = true;
-          session.steer(
+          void session.steer(
             "You have reached your turn limit. Wrap up immediately — provide your final answer now.",
           );
         } else if (softLimitReached && turnCount >= maxTurns + (options.graceTurns ?? 5)) {
           aborted = true;
-          session.abort();
+          void session.abort();
         }
       }
     }

package/src/lifecycle/parent-snapshot.ts

@@ -41,6 +41,7 @@ export function buildParentSnapshot(
     systemPrompt: ctx.getSystemPrompt(),
     model: ctx.model,
     modelRegistry: ctx.modelRegistry,
+    // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- || intentional: converts empty string to undefined as well as null/undefined
     parentContext: parentContext || undefined,
   };
 }

package/src/observation/record-observer.ts

@@ -1,3 +1,4 @@
+/* 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.
  *

package/src/service/service-adapter.ts

@@ -26,7 +26,7 @@ export interface AgentManagerLike {
 /** Create a SubagentsService backed by the given dependencies. */
 export function createSubagentsService(
   manager: AgentManagerLike,
-  resolveModel: (input: string, registry: ModelRegistry) => unknown | string,
+  resolveModel: (input: string, registry: ModelRegistry) => unknown,
   getCtx: () => { pi: unknown; ctx: unknown } | undefined,
   getModelRegistry: () => ModelRegistry | undefined,
 ): SubagentsService {
@@ -85,7 +85,7 @@ export function createSubagentsService(
 
     async steer(id: string, message: string): Promise<boolean> {
       const record = manager.getRecord(id);
-      if (!record || record.status !== "running") {
+      if (record?.status !== "running") {
         return false;
       }
       const session = record.session;

package/src/service/service.ts

@@ -100,5 +100,6 @@ export function getSubagentsService(): SubagentsService | undefined {
 
 /** Remove the SubagentsService from globalThis (call on shutdown/reload). */
 export function unpublishSubagentsService(): void {
+  // eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- Symbol-keyed global property; Map.delete() is not applicable
   delete (globalThis as Record<symbol, unknown>)[SERVICE_KEY];
 }

package/src/session/context.ts

@@ -1,3 +1,4 @@
+/* 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.
  */
@@ -19,6 +20,7 @@ export function extractText(content: unknown[]): string {
  */
 export function buildParentContext(ctx: ExtensionContext): string {
   const entries = ctx.sessionManager.getBranch();
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- getBranch() may return undefined at runtime despite its type
   if (!entries || entries.length === 0) return "";
 
   const parts: string[] = [];

package/src/session/model-resolver.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-redundant-type-constituents -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
 /**
  * Model resolution: exact match ("provider/modelId") with fuzzy fallback.
  */
@@ -16,7 +17,7 @@ export interface ModelRegistry {
 
 /** Successful model resolution — `model` is the resolved or inherited model instance. */
 export interface ModelResolutionResult {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+
   model: any;
   error?: undefined;
 }

package/src/session/prompts.ts

@@ -57,7 +57,7 @@ Platform: ${env.platform}`;
     extraSections.length > 0 ? "\n\n" + extraSections.join("\n") : "";
 
   if (config.promptMode === "append") {
-    const identity = parentSystemPrompt || genericBase;
+    const identity = parentSystemPrompt ?? genericBase;
 
     const bridge = `<sub_agent_context>
 You are operating as a sub-agent invoked to handle a specific task.
@@ -72,7 +72,7 @@ You are operating as a sub-agent invoked to handle a specific task.
 - Be concise but complete
 </sub_agent_context>`;
 
-    const customSection = config.systemPrompt?.trim()
+    const customSection = config.systemPrompt.trim()
       ? `\n\n<agent_instructions>\n${config.systemPrompt}\n</agent_instructions>`
       : "";
 

package/src/session/skill-loader.ts

@@ -69,7 +69,7 @@ function findSkillDirectory(root: string, name: string): string | undefined {
     const current = queue.shift();
     if (current === undefined) continue;
 
-    let entries: Dirent<string>[];
+    let entries: Dirent[];
     try {
       entries = readdirSync(current, { withFileTypes: true });
     } catch (err) {

package/src/tools/agent-tool.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-base-to-string, @typescript-eslint/restrict-template-expressions -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
 import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
@@ -170,7 +171,7 @@ Guidelines:
       const displayName = args.subagent_type
         ? getDisplayName(args.subagent_type as string, registry)
         : "Agent";
-      const desc = (args.description as string) ?? "";
+      const desc = (args.description as string | undefined) ?? "";
       return new Text(
         "▸ " +
           theme.fg("toolTitle", theme.bold(displayName)) +
@@ -325,7 +326,7 @@ Guidelines:
           return textResult(`Failed to resume agent "${params.resume}".`);
         }
         return textResult(
-          record.result?.trim() || record.error?.trim() || "No output.",
+          record.result?.trim() ?? record.error?.trim() ?? "No output.",
           buildDetails(config.detailBase, record),
         );
       }

package/src/tools/foreground-runner.ts

@@ -80,6 +80,7 @@ export async function runForeground(
     };
     onUpdate?.({
       content: [{ type: "text", text: `${toolUses} tool uses...` }],
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- Pi SDK ToolCallUpdate details type is not exported
       details: details as any,
     });
   };
@@ -151,7 +152,7 @@ export async function runForeground(
   if (tokenText) statsParts.push(tokenText);
   return textResult(
     `${fallbackNote}Agent completed in ${formatMs(durationMs)} (${statsParts.join(", ")})${getStatusNote(record.status)}.\n\n` +
-      (record.result?.trim() || "No output."),
+      (record.result?.trim() ?? "No output."),
     details,
   );
 }

package/src/tools/get-result-tool.ts

@@ -79,7 +79,7 @@ export function createGetResultTool(
       } else if (record.status === "error") {
         output += `Error: ${record.error}`;
       } else {
-        output += record.result?.trim() || "No output.";
+        output += record.result?.trim() ?? "No output.";
       }
 
       // Mark result as consumed — suppresses the completion notification

package/src/tools/spawn-config.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-argument -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
 /**
  * spawn-config.ts — Pure config resolution for the Agent tool.
  *

package/src/ui/agent-config-editor.ts

@@ -115,7 +115,7 @@ export function createAgentConfigEditor(
     const fmFields: string[] = [];
     fmFields.push(`description: ${cfg.description}`);
     if (cfg.displayName) fmFields.push(`display_name: ${cfg.displayName}`);
-    fmFields.push(`tools: ${cfg.builtinToolNames?.join(", ") || "all"}`);
+    fmFields.push(`tools: ${cfg.builtinToolNames?.join(", ") ?? "all"}`);
     if (cfg.model) fmFields.push(`model: ${cfg.model}`);
     if (cfg.thinking) fmFields.push(`thinking: ${cfg.thinking}`);
     if (cfg.maxTurns) fmFields.push(`max_turns: ${cfg.maxTurns}`);
@@ -174,6 +174,7 @@ export function createAgentConfigEditor(
     ui.notify(`Disabled ${name} (${targetPath})`, "info");
   }
 
+  // eslint-disable-next-line @typescript-eslint/require-await
   async function enableAgent(ui: MenuUI, name: string) {
     const file = fileOps.findAgentFile(name, agentDirs());
     if (!file) return;

package/src/ui/agent-menu.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
 import { wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import { AgentTypeRegistry } from "#src/config/agent-types";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";

package/src/ui/agent-widget.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-redundant-type-constituents -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
 /**
  * agent-widget.ts — Persistent widget showing running/completed agents above the editor.
  *
@@ -76,9 +77,7 @@ export class AgentWidget {
   /** Ensure the widget update timer is running. */
   // fallow-ignore-next-line unused-class-member
   ensureTimer() {
-    if (!this.widgetInterval) {
-      this.widgetInterval = setInterval(() => this.update(), 80);
-    }
+    this.widgetInterval ??= setInterval(() => this.update(), 80);
   }
 
   /** Check if a finished agent should still be shown in the widget. */

package/src/ui/conversation-viewer.ts

@@ -299,7 +299,7 @@ export class ConversationViewer implements Component {
       } else if (isBashExecution(msg)) {
         if (needsSeparator) lines.push(th.fg("dim", "───"));
         lines.push(truncateToWidth(th.fg("muted", `  $ ${msg.command}`), width));
-        if (msg.output?.trim()) {
+        if (msg.output.trim()) {
           const out = msg.output.length > 500
             ? msg.output.slice(0, 500) + "... (truncated)"
             : msg.output;

package/src/ui/ui-observer.ts

@@ -1,3 +1,4 @@
+/* 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.
  *