@nklisch/pi-enhanced 0.2.0 → 0.2.2

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/config/custom-agents.ts

@@ -58,23 +58,28 @@ function loadFromDir(
       continue;
     }
 
-    const { frontmatter: fm, body } = parseFrontmatter(content);
-
-    agents.set(name, {
-      name,
-      displayName: str(fm.display_name),
-      description: str(fm.description) ?? name,
-      builtinToolNames: csvList(fm.tools, BUILTIN_TOOL_NAMES),
-      model: str(fm.model),
-      thinking: str(fm.thinking) as ThinkingLevel | undefined,
-      maxTurns: nonNegativeInt(fm.max_turns),
-      systemPrompt: body.trim(),
-      promptMode: fm.prompt_mode === "replace" ? "replace" : "append",
-      inheritContext: fm.inherit_context != null ? fm.inherit_context === true : undefined,
-      runInBackground: fm.run_in_background != null ? fm.run_in_background === true : undefined,
-      enabled: fm.enabled !== false,  // default true; explicitly false disables
-      source,
-    });
+    try {
+      const { frontmatter: fm, body } = parseFrontmatter(content);
+      agents.set(name, {
+        name,
+        displayName: str(fm.display_name),
+        description: str(fm.description) ?? name,
+        builtinToolNames: csvList(fm.tools, BUILTIN_TOOL_NAMES),
+        model: str(fm.model),
+        thinking: str(fm.thinking) as ThinkingLevel | undefined,
+        maxTurns: nonNegativeInt(fm.max_turns),
+        systemPrompt: body.trim(),
+        promptMode: fm.prompt_mode === "replace" ? "replace" : "append",
+        inheritContext: fm.inherit_context != null ? fm.inherit_context === true : undefined,
+        runInBackground: fm.run_in_background != null ? fm.run_in_background === true : undefined,
+        enabled: fm.enabled !== false,  // default true; explicitly false disables
+        source,
+      });
+    } catch (err) {
+      // One malformed user file must not hide valid agents from the same tier
+      // or lower-priority discovery locations.
+      debugLog("parse custom agent frontmatter", err);
+    }
   }
 }
 

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/debug.ts

@@ -12,3 +12,21 @@ export function isDebug(): boolean {
 export function debugLog(context: string, err: unknown): void {
   if (isDebug()) console.warn(`[pi-subagents:debug] ${context}:`, err);
 }
+
+/** Run a synchronous extension-owned callback without letting it escape its boundary. */
+export function runSafely(context: string, action: () => void): void {
+  try {
+    action();
+  } catch (error) {
+    debugLog(context, error);
+  }
+}
+
+/** Start extension-owned async work and consume both synchronous and rejected failures. */
+export function runDetached(context: string, action: () => PromiseLike<unknown> | void): void {
+  try {
+    void Promise.resolve(action()).catch((error: unknown) => debugLog(context, error));
+  } catch (error) {
+    debugLog(context, error);
+  }
+}

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/lifecycle/child-lifecycle.ts

@@ -10,6 +10,8 @@
  * Pi SDK imports — `index.ts` wires it to `pi.events.emit`.
  */
 
+import { debugLog } from "#src/debug";
+
 /** Emitted at the start of a child run, before the session is created. */
 export const SUBAGENT_CHILD_SPAWNING = "subagents:child:spawning";
 
@@ -75,16 +77,32 @@ export function createChildLifecyclePublisher(
 ): ChildLifecyclePublisher {
   return {
     spawning(event) {
-      emit(SUBAGENT_CHILD_SPAWNING, event);
+      publish(emit, "child lifecycle spawning", SUBAGENT_CHILD_SPAWNING, event);
     },
     sessionCreated(event) {
-      emit(SUBAGENT_CHILD_SESSION_CREATED, event);
+      publish(emit, "child lifecycle session-created", SUBAGENT_CHILD_SESSION_CREATED, event);
     },
     completed(event) {
-      emit(SUBAGENT_CHILD_COMPLETED, event);
+      publish(emit, "child lifecycle completed", SUBAGENT_CHILD_COMPLETED, event);
     },
     disposed(event) {
-      emit(SUBAGENT_CHILD_DISPOSED, event);
+      publish(emit, "child lifecycle disposed", SUBAGENT_CHILD_DISPOSED, event);
     },
   };
 }
+
+/** EventEmitter listeners are outside the extension runner; isolate their throws. */
+function publish(
+  emit: LifecycleEmit,
+  channelContext: string,
+  channel: string,
+  data: unknown,
+): void {
+  try {
+    // Pi's event bus is synchronous for child lifecycle hooks by design.
+    // Keep that ordering while preventing a subscriber from escaping into Pi.
+    emit(channel, data);
+  } catch (error) {
+    debugLog(channelContext, error);
+  }
+}

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/lifecycle/concurrency-limiter.ts

@@ -9,6 +9,8 @@
  * task runs, or resolves early if clear() drops it before it starts.
  */
 
+import { debugLog } from "#src/debug";
+
 export class ConcurrencyLimiter {
 	private active = 0;
 	private readonly pending: Array<{ start: () => void; settle: () => void }> = [];
@@ -17,7 +19,12 @@ export class ConcurrencyLimiter {
 
 	/** Whether a newly scheduled task will wait behind work already admitted. */
 	isSaturated(): boolean {
-		return this.active >= this.getLimit();
+		try {
+			return this.active >= this.getLimit();
+		} catch (error) {
+			debugLog("concurrency limiter limit", error);
+			return false;
+		}
 	}
 
 	/**
@@ -30,12 +37,25 @@ export class ConcurrencyLimiter {
 		this.pending.push({
 			start: () => {
 				this.active++;
-				task()
+				let taskPromise: Promise<void>;
+				try {
+					taskPromise = Promise.resolve(task());
+				} catch (error) {
+					taskPromise = Promise.reject(error);
+				}
+				taskPromise
 					.then(resolve, reject)
 					.finally(() => {
 						this.active--;
-						this.recheck();
-					});
+						try {
+							this.recheck();
+						} catch (error) {
+							// A failing dynamic limit must not strand the slot or
+							// reject the detached cleanup promise.
+							debugLog("concurrency limiter recheck", error);
+						}
+					})
+					.catch((error: unknown) => debugLog("concurrency limiter cleanup", error));
 			},
 			settle: resolve,
 		});
@@ -45,10 +65,14 @@ export class ConcurrencyLimiter {
 
 	/** Start pending tasks until the limit is reached. Call when the limit may have grown. */
 	recheck(): void {
-		while (this.active < this.getLimit()) {
-			const next = this.pending.shift();
-			if (!next) break;
-			next.start();
+		try {
+			while (this.active < this.getLimit()) {
+				const next = this.pending.shift();
+				if (!next) break;
+				next.start();
+			}
+		} catch (error) {
+			debugLog("concurrency limiter recheck", error);
 		}
 	}
 

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/lifecycle/create-subagent-session.ts

@@ -227,14 +227,15 @@ export async function createSubagentSession(
     lifecycle: deps.lifecycle,
   });
 
-  // Publish session-created before bindExtensions() so observers (e.g. the
-  // permission system) can register the child synchronously and have their
-  // entry in place for the first permission check during child extension
-  // initialization. The event bus dispatches synchronously, so a synchronous
-  // subscriber completes before this returns.
-  deps.lifecycle.sessionCreated({ sessionId, parentSessionId });
-
   try {
+    // Publish session-created before bindExtensions() so observers (e.g. the
+    // permission system) can register the child synchronously and have their
+    // entry in place for the first permission check during child extension
+    // initialization. The event bus dispatches synchronously, so a synchronous
+    // subscriber completes before this returns. Keep publication in the same
+    // cleanup boundary as binding: a failing subscriber must not leak the
+    // already-created child session.
+    deps.lifecycle.sessionCreated({ sessionId, parentSessionId });
     // Bind extensions so that session_start fires and extensions can initialize.
     await session.bindExtensions({});
     // Apply recursion guard after bindExtensions so extension-registered tools

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/lifecycle/lifecycle-interceptor.ts

@@ -7,6 +7,8 @@
  * continuation bound; it does not expose sessions, records, models, or queues.
  */
 
+import { debugLog } from "#src/debug";
+
 /** The fixed bound prevents a provider from turning completion into an unbounded loop. */
 export const MAX_LIFECYCLE_CONTINUATION_ROUNDS = 3;
 
@@ -137,7 +139,7 @@ export class LifecycleInterceptorRegistry {
     if (this.shutdownController.signal.aborted) {
       throw new Error("Subagent lifecycle registry is disposed");
     }
-    if (typeof interceptor !== "object") {
+    if (interceptor === null || typeof interceptor !== "object") {
       throw new TypeError("A lifecycle interceptor object is required");
     }
 
@@ -193,10 +195,7 @@ export class LifecycleInterceptorRegistry {
   private async shutdown(): Promise<void> {
     this.shutdownController.abort(new DOMException("Subagent lifecycle registry disposed", "AbortError"));
     for (const record of this.registrations) this.unregister(record);
-    const finalizers = this.registrations.flatMap((record) =>
-      record.finalizer === undefined ? [] : [record.finalizer],
-    );
-    await Promise.all(finalizers);
+    await Promise.all(this.registrations.map((record) => this.consumeFinalizer(record)));
   }
 
   /**
@@ -206,8 +205,18 @@ export class LifecycleInterceptorRegistry {
    * unregister another interceptor while the same ordered snapshot is running.
    */
   private disposeRegistration(record: RegistrationRecord): Promise<void> {
+    const wasInFlight = record.inFlight > 0;
     this.unregister(record);
-    return Promise.resolve();
+    // A callback may unregister another provider from inside the same ordered
+    // snapshot. Do not await its idle finalizer there; consume it independently
+    // while preserving the synchronous interceptor ordering contract. External
+    // disposal still gets a completion promise once the provider is idle.
+    const finalizer = this.consumeFinalizer(record);
+    if (wasInFlight) {
+      void finalizer;
+      return Promise.resolve();
+    }
+    return finalizer;
   }
 
   private unregister(record: RegistrationRecord): void {
@@ -218,6 +227,16 @@ export class LifecycleInterceptorRegistry {
     })();
   }
 
+  /** Consume disposer failures so detached manager shutdown cannot become an unhandled rejection. */
+  private async consumeFinalizer(record: RegistrationRecord): Promise<void> {
+    if (!record.finalizer) return;
+    try {
+      await record.finalizer;
+    } catch (error) {
+      debugLog("lifecycle interceptor dispose", error);
+    }
+  }
+
   private async waitForIdle(record: RegistrationRecord): Promise<void> {
     if (record.inFlight === 0) return;
     await new Promise<void>((resolve) => record.idleWaiters.push(resolve));

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/lifecycle/run-listeners.ts

@@ -6,6 +6,8 @@
  * both atomically when the run ends or the agent is resumed.
  */
 
+import { runSafely } from "#src/debug";
+
 /** Owns the per-run observer-unsubscribe and signal-detach handles. */
 export class RunListeners {
 	private unsub?: () => void;
@@ -29,9 +31,11 @@ export class RunListeners {
 
 	/** Release the observer + signal handles. Idempotent. */
 	release(): void {
-		this.unsub?.();
+		const unsub = this.unsub;
 		this.unsub = undefined;
-		this.detach?.();
+		const detach = this.detach;
 		this.detach = undefined;
+		runSafely("subagent observer unsubscribe", () => unsub?.());
+		runSafely("subagent abort listener detach", () => detach?.());
 	}
 }

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/lifecycle/subagent-manager.ts

@@ -8,7 +8,7 @@
 
 import { randomUUID } from "node:crypto";
 import type { Model } from "@earendil-works/pi-ai";
-import { debugLog } from "#src/debug";
+import { debugLog, runSafely } from "#src/debug";
 import type { ConcurrencyLimiter } from "#src/lifecycle/concurrency-limiter";
 import type { CreateSubagentSessionParams } from "#src/lifecycle/create-subagent-session";
 import {
@@ -102,7 +102,15 @@ export class SubagentManager {
     this.observer = options.observer;
     this.getRunConfig = options.getRunConfig;
     // Periodically release heavy terminal sessions according to retention policy.
-    this.cleanupInterval = setInterval(() => this.cleanup(), 60_000);
+    // Timer callbacks sit outside Pi's extension runner, so a malformed setting
+    // or disposal failure must remain diagnostic rather than escape into Node.
+    this.cleanupInterval = setInterval(() => {
+      try {
+        this.cleanup();
+      } catch (error) {
+        debugLog("retention cleanup", error);
+      }
+    }, 60_000);
     this.cleanupInterval.unref();
   }
 
@@ -133,23 +141,29 @@ export class SubagentManager {
   /** Compose a per-agent lifecycle observer from manager and spawn-config concerns. */
   private buildObserver(options: AgentSpawnConfig): SubagentLifecycleObserver {
     return {
-      onStarted: (agent) => {
-        this.observer?.onSubagentStarted(agent);
-      },
+      onStarted: (agent) => runSafely(
+        "onSubagentStarted observer",
+        () => this.observer?.onSubagentStarted(agent),
+      ),
       onSessionCreated: options.observer?.onSessionCreated
-        ? (agent) => options.observer!.onSessionCreated!(agent)
+        ? (agent) => runSafely(
+          "onSessionCreated observer",
+          () => options.observer!.onSessionCreated!(agent),
+        )
         : undefined,
       onRunFinished: (agent) => {
         if (options.isBackground) {
-          try { this.observer?.onSubagentCompleted(agent); } catch (err) { debugLog("onSubagentCompleted observer", err); }
+          runSafely("onSubagentCompleted observer", () => this.observer?.onSubagentCompleted(agent));
         }
       },
-      onResumedFinished: (agent) => {
-        try { this.observer?.onSubagentResumed?.(agent); } catch (err) { debugLog("onSubagentResumed observer", err); }
-      },
-      onCompacted: (agent, info) => {
-        this.observer?.onSubagentCompacted(agent, info);
-      },
+      onResumedFinished: (agent) => runSafely(
+        "onSubagentResumed observer",
+        () => this.observer?.onSubagentResumed?.(agent),
+      ),
+      onCompacted: (agent, info) => runSafely(
+        "onSubagentCompacted observer",
+        () => this.observer?.onSubagentCompacted(agent, info),
+      ),
     };
   }
 
@@ -202,7 +216,7 @@ export class SubagentManager {
     this.agents.set(id, record);
 
     if (options.isBackground) {
-      this.observer?.onSubagentCreated(record);
+      runSafely("onSubagentCreated observer", () => this.observer?.onSubagentCreated(record));
     }
 
     if (options.isBackground && !options.bypassQueue) {
@@ -370,8 +384,9 @@ export class SubagentManager {
   dispose() {
     clearInterval(this.cleanupInterval);
     // Lifecycle callbacks observe the shutdown signal before their registration
-    // disposer runs. Existing no-provider teardown stays synchronous.
-    void this.lifecycleInterceptors.dispose();
+    // disposer runs. Existing no-provider teardown stays synchronous. Consume
+    // async disposer failures because manager disposal is intentionally sync.
+    void this.lifecycleInterceptors.dispose().catch((error) => debugLog("lifecycle interceptor shutdown", error));
     // Drop pending thunks
     this.limiter.clear();
     for (const record of this.agents.values()) {

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/lifecycle/subagent-session.ts

@@ -16,6 +16,7 @@ import {
   type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import type { Model } from "@earendil-works/pi-ai";
+import { debugLog, runDetached, runSafely } from "#src/debug";
 import type { ChildLifecyclePublisher } from "#src/lifecycle/child-lifecycle";
 import {
   type SubagentLifecycleOutcome,
@@ -73,6 +74,8 @@ export interface SubagentSessionMeta {
  * One child AgentSession plus its turn-driving and teardown — born complete.
  */
 export class SubagentSession {
+  private disposed = false;
+
   constructor(
     private readonly _session: AgentSession,
     private readonly meta: SubagentSessionMeta,
@@ -118,20 +121,24 @@ export class SubagentSession {
     let aborted = false;
 
     const unsubTurns = session.subscribe((event: AgentSessionEvent) => {
-      if (event.type === "turn_end") {
-        turnCount++;
-        if (maxTurns != null) {
-          if (!softLimitReached && turnCount >= maxTurns) {
-            softLimitReached = true;
-            void session.steer(
-              "You have reached your turn limit. Wrap up immediately - provide your final answer now.",
-            );
-          } else if (softLimitReached && turnCount >= maxTurns + (opts.graceTurns ?? 5)) {
-            aborted = true;
-            void session.abort();
+      runSafely("subagent turn-limit observer", () => {
+        if (event.type === "turn_end") {
+          turnCount++;
+          if (maxTurns != null) {
+            if (!softLimitReached && turnCount >= maxTurns) {
+              softLimitReached = true;
+              runDetached("turn-limit steer", () =>
+                session.steer(
+                  "You have reached your turn limit. Wrap up immediately - provide your final answer now.",
+                ),
+              );
+            } else if (softLimitReached && turnCount >= maxTurns + (opts.graceTurns ?? 5)) {
+              aborted = true;
+              runDetached("turn-limit abort", () => session.abort());
+            }
           }
         }
-      }
+      });
     });
 
     const startIndex = session.messages.length;
@@ -165,9 +172,11 @@ export class SubagentSession {
         () => ({ aborted, steered: softLimitReached }),
       );
     } finally {
-      unsubTurns();
-      collector.unsubscribe();
-      cleanupAbort();
+      releaseTurnLoopHandles([
+        ["subagent turn-limit unsubscribe", unsubTurns],
+        ["subagent response collector unsubscribe", collector.unsubscribe],
+        ["subagent abort forwarder detach", cleanupAbort],
+      ]);
     }
   }
 
@@ -188,8 +197,10 @@ export class SubagentSession {
         failure: finalTurnError(session, startIndex),
       };
     } finally {
-      collector.unsubscribe();
-      cleanupAbort();
+      releaseTurnLoopHandles([
+        ["subagent response collector unsubscribe", collector.unsubscribe],
+        ["subagent abort forwarder detach", cleanupAbort],
+      ]);
     }
   }
 
@@ -214,8 +225,10 @@ export class SubagentSession {
         () => ({ aborted: false, steered: false }),
       );
     } finally {
-      collector.unsubscribe();
-      cleanupAbort();
+      releaseTurnLoopHandles([
+        ["subagent response collector unsubscribe", collector.unsubscribe],
+        ["subagent abort forwarder detach", cleanupAbort],
+      ]);
     }
   }
 
@@ -338,9 +351,21 @@ export class SubagentSession {
 
   /** Tear down: session.dispose() + emit `disposed` (registry unregister). */
   dispose(): void {
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- dispose may not exist on all session implementations
-    this._session.dispose?.();
-    this.meta.lifecycle.disposed({ sessionId: this.meta.sessionId });
+    if (this.disposed) return;
+    this.disposed = true;
+
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- dispose may not exist on all session implementations
+      this._session.dispose?.();
+    } catch (error) {
+      debugLog("child session dispose", error);
+    }
+
+    try {
+      this.meta.lifecycle.disposed({ sessionId: this.meta.sessionId });
+    } catch (error) {
+      debugLog("child lifecycle disposed", error);
+    }
   }
 }
 
@@ -361,15 +386,17 @@ function toLifecycleOutcome(
 function collectResponseText(session: AgentSession) {
   let text = "";
   const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
-    if (event.type === "message_start" && event.message?.role === "assistant") {
-      text = "";
-    }
-    if (
-      event.type === "message_update" &&
-      event.assistantMessageEvent.type === "text_delta"
-    ) {
-      text += event.assistantMessageEvent.delta;
-    }
+    runSafely("subagent response observer", () => {
+      if (event.type === "message_start" && event.message?.role === "assistant") {
+        text = "";
+      }
+      if (
+        event.type === "message_update" &&
+        event.assistantMessageEvent.type === "text_delta"
+      ) {
+        text += event.assistantMessageEvent.delta;
+      }
+    });
   });
   return { getText: () => text, unsubscribe };
 }
@@ -401,6 +428,17 @@ function finalTurnError(session: AgentSession, startIndex = 0): string | undefin
   return undefined;
 }
 
+/**
+ * Release the turn loop's SDK-owned cleanup handles one by one. Each handle is
+ * code outside this extension, so a throwing unsubscribe must neither skip the
+ * remaining handles nor mask the primary turn-loop outcome settling above.
+ */
+function releaseTurnLoopHandles(handles: ReadonlyArray<readonly [string, () => void]>): void {
+  for (const [context, release] of handles) {
+    runSafely(context, release);
+  }
+}
+
 /**
  * Wire an AbortSignal to abort a session.
  * Returns a cleanup function to remove the listener.
@@ -411,7 +449,7 @@ function forwardAbortSignal(
 ): () => void {
   if (!signal) return () => {};
   const onAbort = (): void => {
-    void session.abort();
+    runDetached("parent-signal abort", () => session.abort());
   };
   signal.addEventListener("abort", onAbort, { once: true });
   return () => signal.removeEventListener("abort", onAbort);