@nklisch/pi-enhanced 0.2.6 → 0.3.0

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

@@ -1,14 +1,4 @@
-/**
- * subagent-session.ts — The born-complete child-session value object (issue #265).
- *
- * A SubagentSession wraps one SDK AgentSession plus its turn-driving and teardown.
- * It is born complete: `createSubagentSession()` returns a fully usable instance
- * (session created, extensions bound, recursion guard applied), so the only thing
- * left for `Subagent` to do is coordinate — drive the turn loop, steer, dispose.
- *
- * Turn driving lives here, on the object that owns the AgentSession, rather than
- * reaching through `subagentSession.session` from `Subagent` (Law of Demeter).
- */
+/** Born-complete child session: turn driving, steering, and teardown. */
 
 import {
   type AgentSession,
@@ -18,9 +8,9 @@ import {
 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,
-  type SubagentTurnLifecycle,
+import type {
+  SubagentLifecycleOutcome,
+  SubagentTurnLifecycle,
 } from "#src/lifecycle/lifecycle-interceptor";
 import { normalizeMaxTurns } from "#src/lifecycle/turn-limits";
 import { getSessionContextPercent, type SessionStatsLike } from "#src/lifecycle/usage";
@@ -28,51 +18,34 @@ import { extractText } from "#src/session/context";
 import { getAgentConversation } from "#src/session/conversation";
 import type { SessionMessage, ThinkingLevel } from "#src/types";
 
-/** Outcome of one turn loop. */
+export type TurnLimitReason = "turn_limit_graceful" | "turn_limit_hard";
+
 export interface TurnLoopResult {
   responseText: string;
-  /** Normally-resolved provider failure from the final assistant turn. */
+  /** Provider failure reported by a normally-resolved assistant turn. */
   failure?: string;
-  /** True if the agent was hard-aborted (max turns + grace exceeded). */
-  aborted: boolean;
-  /** True if the agent was steered to wrap up (soft turn limit) but finished in time. */
-  steered: boolean;
-  /** A lifecycle provider denied finalization; no child completion is emitted. */
-  lifecycleAborted?: boolean;
+  /** Turn-limit or lifecycle result owned by the session loop. */
+  terminalReason?: TurnLimitReason | "lifecycle_abort";
 }
 
-/** Per-call options for the initial run's turn loop. */
 export interface TurnLoopOptions {
-  /** Per-call max-turns override — highest precedence. */
   maxTurns?: number;
-  /** Runtime-config fallback when neither per-call nor per-agent limit is set. */
   defaultMaxTurns?: number;
-  /** Grace turns after the soft-limit steer message before a hard abort. */
   graceTurns?: number;
   signal?: AbortSignal;
-  /** Present only for an execution that captured active lifecycle providers. */
   lifecycle?: SubagentTurnLifecycle;
 }
 
-/** Session-level facts known at creation, supplied by the factory. */
 export interface SubagentSessionMeta {
-  /** Path to the persisted session JSONL file, if the session was persisted. */
   outputFile: string | undefined;
-  /** Child session id — the registry key carried on session-created/disposed events. */
   sessionId: string;
-  /** Child session directory — carried on the completed event as transcript location. */
   sessionDir: string;
   agentName: string;
-  /** Per-agent max-turns from the resolved agent config — middle precedence. */
   agentMaxTurns: number | undefined;
-  /** Parent context prepended to the run prompt, captured at spawn time. */
   parentContext: string | undefined;
   lifecycle: ChildLifecyclePublisher;
 }
 
-/**
- * One child AgentSession plus its turn-driving and teardown — born complete.
- */
 export class SubagentSession {
   private disposalPromise?: Promise<void>;
 
@@ -81,62 +54,32 @@ export class SubagentSession {
     private readonly meta: SubagentSessionMeta,
   ) {}
 
-  /**
-   * Wrapped session — for lifecycle-internal use only.
-   * @internal consumers outside lifecycle/ use the delegate methods below.
-   */
-  get session(): AgentSession {
-    return this._session;
-  }
-
-  get outputFile(): string | undefined {
-    return this.meta.outputFile;
-  }
-
-  /** Stable child session identity for lifecycle provider metadata. */
-  get sessionId(): string {
-    return this.meta.sessionId;
-  }
+  /** @internal lifecycle-only access to SDK teardown hooks. */
+  get session(): AgentSession { return this._session; }
+  get outputFile(): string | undefined { return this.meta.outputFile; }
+  get sessionId(): string { return this.meta.sessionId; }
+  get model(): Model<any> | undefined { return this._session.model; }
+  get thinkingLevel(): ThinkingLevel { return this._session.thinkingLevel; }
 
-  /** Current model selected by the child session. */
-  get model(): Model<any> | undefined {
-    return this._session.model;
-  }
-
-  /** Effective level after the child session applied defaults and clamping. */
-  get thinkingLevel(): ThinkingLevel {
-    return this._session.thinkingLevel;
-  }
-
-  /** Drive the initial run's turn loop; emits `completed` on accepted success. */
   async runTurnLoop(prompt: string, opts: TurnLoopOptions): Promise<TurnLoopResult> {
     const session = this._session;
-
-    // Track turns for graceful max_turns enforcement.
     let turnCount = 0;
-    const maxTurns = normalizeMaxTurns(
-      opts.maxTurns ?? this.meta.agentMaxTurns ?? opts.defaultMaxTurns,
-    );
+    const maxTurns = normalizeMaxTurns(opts.maxTurns ?? this.meta.agentMaxTurns ?? opts.defaultMaxTurns);
     let softLimitReached = false;
-    let aborted = false;
+    let turnLimitReason: TurnLimitReason | undefined;
 
     const unsubTurns = session.subscribe((event: AgentSessionEvent) => {
       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());
-            }
-          }
+        if (event.type !== "turn_end" || maxTurns == null) return;
+        turnCount++;
+        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)) {
+          turnLimitReason = "turn_limit_hard";
+          runDetached("turn-limit abort", () => session.abort());
         }
       });
     });
@@ -144,33 +87,26 @@ export class SubagentSession {
     const startIndex = session.messages.length;
     const collector = collectResponseText(session);
     const cleanupAbort = forwardAbortSignal(session, opts.signal);
-
-    // Prepend parent context before lifecycle providers see the exact prompt.
-    const effectivePrompt = this.meta.parentContext
-      ? this.meta.parentContext + prompt
-      : prompt;
+    const effectivePrompt = this.meta.parentContext ? this.meta.parentContext + prompt : prompt;
 
     try {
-      if (!opts.lifecycle) {
-        // Preserve the released no-provider order byte-for-byte: completion is
-        // published immediately after prompt resolution and before extraction.
-        await session.prompt(effectivePrompt);
-        this.publishCompleted(aborted, softLimitReached);
-        const responseText = collector.getText().trim() || getLastAssistantText(session, startIndex);
-        return {
-          responseText,
-          failure: finalTurnError(session, startIndex),
-          aborted,
-          steered: softLimitReached,
-        };
+      if (opts.lifecycle) {
+        return await this.driveLifecycleTurns(
+          effectivePrompt,
+          opts.lifecycle,
+          () => collector.getText().trim() || getLastAssistantText(session, startIndex),
+          () => finalTurnError(session, startIndex),
+          () => turnLimitReason,
+          () => softLimitReached,
+        );
       }
-      return await this.driveLifecycleTurns(
-        effectivePrompt,
-        opts.lifecycle,
-        () => collector.getText().trim() || getLastAssistantText(session, startIndex),
-        () => finalTurnError(session, startIndex),
-        () => ({ aborted, steered: softLimitReached }),
-      );
+
+      await session.prompt(effectivePrompt);
+      const responseText = collector.getText().trim() || getLastAssistantText(session, startIndex);
+      const failure = finalTurnError(session, startIndex);
+      const terminalReason = failure ? undefined : turnLimitReason ?? (softLimitReached ? "turn_limit_graceful" : undefined);
+      if (!failure) this.publishCompleted(terminalReason ?? "completed");
+      return { responseText, failure, ...(terminalReason ? { terminalReason } : {}) };
     } finally {
       releaseTurnLoopHandles([
         ["subagent turn-limit unsubscribe", unsubTurns],
@@ -180,22 +116,16 @@ export class SubagentSession {
     }
   }
 
-  /** Re-prompt the same session (resume); preserves the released no-provider path. */
-  async resumeTurnLoop(
-    prompt: string,
-    signal?: AbortSignal,
-  ): Promise<{ text: string; failure?: string }> {
-    const session = this._session;
-    const startIndex = session.messages.length;
-    const collector = collectResponseText(session);
-    const cleanupAbort = forwardAbortSignal(session, signal);
-
+  async resumeTurnLoop(prompt: string, signal?: AbortSignal): Promise<{ text: string; failure?: string; terminalReason?: TurnLimitReason }> {
+    const startIndex = this._session.messages.length;
+    const collector = collectResponseText(this._session);
+    const cleanupAbort = forwardAbortSignal(this._session, signal);
     try {
-      await session.prompt(prompt);
-      return {
-        text: collector.getText().trim() || getLastAssistantText(session, startIndex),
-        failure: finalTurnError(session, startIndex),
-      };
+      await this._session.prompt(prompt);
+      const text = collector.getText().trim() || getLastAssistantText(this._session, startIndex);
+      const failure = finalTurnError(this._session, startIndex);
+      if (!failure) this.publishCompleted("completed");
+      return { text, failure };
     } finally {
       releaseTurnLoopHandles([
         ["subagent response collector unsubscribe", collector.unsubscribe],
@@ -204,10 +134,6 @@ export class SubagentSession {
     }
   }
 
-  /**
-   * Resume with active providers. This is separate from resumeTurnLoop so the
-   * historical no-provider method signature and event behavior remain intact.
-   */
   async resumeLifecycleTurnLoop(
     prompt: string,
     signal: AbortSignal | undefined,
@@ -222,7 +148,8 @@ export class SubagentSession {
         lifecycle,
         () => collector.getText().trim() || getLastAssistantText(this._session, startIndex),
         () => finalTurnError(this._session, startIndex),
-        () => ({ aborted: false, steered: false }),
+        () => undefined,
+        () => false,
       );
     } finally {
       releaseTurnLoopHandles([
@@ -237,38 +164,35 @@ export class SubagentSession {
     lifecycle: SubagentTurnLifecycle,
     responseText: () => string,
     failure: () => string | undefined,
-    outcome: () => Readonly<{ aborted: boolean; steered: boolean }>,
+    turnLimitReason: () => TurnLimitReason | undefined,
+    softLimitReached: () => boolean,
   ): Promise<TurnLoopResult> {
     const start = await lifecycle.beforeStart(initialPrompt);
-    if (start?.action === "abort") {
-      return this.lifecycleAbort(start.reason, outcome());
-    }
+    if (start?.action === "abort") return this.lifecycleAbort(start.reason);
 
     let prompt = start?.prompt ?? initialPrompt;
     let continuationRound = 0;
     for (;;) {
       lifecycle.signal.throwIfAborted();
       await this._session.prompt(prompt);
-      const turnOutcome = outcome();
       const proposedResult = responseText();
       const turnFailure = failure();
       if (turnFailure) {
-        return { responseText: proposedResult, failure: turnFailure, ...turnOutcome };
+        // Provider failure is a record terminal reason, not a lifecycle outcome;
+        // do not publish a misleading child-completed event.
+        return { responseText: proposedResult, failure: turnFailure };
       }
+
+      const turnReason = turnLimitReason() ?? (softLimitReached() ? "turn_limit_graceful" : undefined);
       const completion = await lifecycle.beforeComplete(
         proposedResult,
-        toLifecycleOutcome(turnOutcome),
+        turnReason === "turn_limit_hard" ? "turn_limit_hard" : turnReason === "turn_limit_graceful" ? "turn_limit_graceful" : "completed",
         continuationRound,
       );
-      if (completion?.action === "abort") {
-        return this.lifecycleAbort(completion.reason, turnOutcome);
-      }
+      if (completion?.action === "abort") return this.lifecycleAbort(completion.reason);
       if (completion?.action === "continue") {
         if (continuationRound >= lifecycle.maxContinuationRounds) {
-          return this.lifecycleAbort(
-            `Lifecycle continuation limit of ${lifecycle.maxContinuationRounds} reached`,
-            turnOutcome,
-          );
+          return this.lifecycleAbort(`Lifecycle continuation limit of ${lifecycle.maxContinuationRounds} reached`);
         }
         continuationRound++;
         prompt = completion.prompt;
@@ -278,51 +202,28 @@ export class SubagentSession {
       const finalResult = completion?.action === "complete"
         ? completion.result ?? proposedResult
         : proposedResult;
-      this.publishCompleted(turnOutcome.aborted, turnOutcome.steered);
-      return {
-        responseText: finalResult,
-        aborted: turnOutcome.aborted,
-        steered: turnOutcome.steered,
-      };
+      this.publishCompleted(turnReason ?? "completed");
+      return { responseText: finalResult, ...(turnReason ? { terminalReason: turnReason } : {}) };
     }
   }
 
-  private lifecycleAbort(
-    reason: string,
-    outcome: Readonly<{ aborted: boolean; steered: boolean }>,
-  ): TurnLoopResult {
-    // No child completion is emitted: the provider declined to accept a turn.
-    return {
-      responseText: reason,
-      aborted: true,
-      steered: outcome.steered,
-      lifecycleAborted: true,
-    };
+  private lifecycleAbort(reason: string): TurnLoopResult {
+    return { responseText: reason, terminalReason: "lifecycle_abort" };
   }
 
-  private publishCompleted(aborted: boolean, steered: boolean): void {
+  private publishCompleted(terminalReason: "completed" | TurnLimitReason): void {
     this.meta.lifecycle.completed({
       sessionDir: this.meta.sessionDir,
       agentName: this.meta.agentName,
-      aborted,
-      steered,
+      terminalReason,
     });
   }
 
-  /** Whether Pi has fully settled the child, including post-run continuation. */
-  get isIdle(): boolean {
-    return this._session.isIdle;
-  }
+  get isIdle(): boolean { return this._session.isIdle; }
 
-  /**
-   * Wait for Pi's authoritative idle boundary before starting another prompt.
-   * A record can already look terminal while AgentSession is still finishing an
-   * extension-driven continuation, so domain status alone is insufficient.
-   */
   async waitUntilIdle(signal?: AbortSignal): Promise<void> {
     if (this._session.isIdle) return;
     signal?.throwIfAborted();
-
     await new Promise<void>((resolve, reject) => {
       let settled = false;
       let unsubscribe: () => void = () => {};
@@ -342,67 +243,24 @@ export class SubagentSession {
         cleanup();
         reject(signal?.reason ?? new Error("Resume wait aborted"));
       };
-
       unsubscribe = this._session.subscribe((event: AgentSessionEvent) => {
         if (event.type === "agent_settled" || this._session.isIdle) finish();
       });
       signal?.addEventListener("abort", onAbort, { once: true });
-
-      // Close the check/subscribe race: Pi may have settled between the first
-      // isIdle read and listener registration.
       if (this._session.isIdle) finish();
       else if (signal?.aborted) onAbort();
     });
   }
 
-  /** Deliver a steer to the live session. */
-  async steer(message: string): Promise<void> {
-    await this._session.steer(message);
-  }
-
-  /** Return the session's conversation as formatted text. */
-  getConversation(): string {
-    return getAgentConversation(this._session);
-  }
-
-  /** Return the session context window utilization (0-100), or null when unavailable. */
-  getContextPercent(): number | null {
-    return getSessionContextPercent(this._session);
-  }
-
-  /** Subscribe to session events. Satisfies `SubscribableSession`. */
-  subscribe(fn: (event: AgentSessionEvent) => void): () => void {
-    return this._session.subscribe(fn);
-  }
-
-  /** Return session token statistics. Satisfies `SessionLike`. */
-  getSessionStats(): SessionStatsLike {
-    return this._session.getSessionStats();
-  }
-
-  /** The session's message history. */
-  get messages(): readonly unknown[] {
-    return this._session.messages as readonly unknown[];
-  }
-
-  /** The session's message history, typed for Pi's session-rendering machinery. */
-  get agentMessages(): readonly SessionMessage[] {
-    return this._session.messages;
-  }
-
-  /** Resolve a registered tool definition by name, for Pi's tool-execution components. */
-  getToolDefinition(name: string): ToolDefinition | undefined {
-    return this._session.getToolDefinition(name);
-  }
+  async steer(message: string): Promise<void> { await this._session.steer(message); }
+  getConversation(): string { return getAgentConversation(this._session); }
+  getContextPercent(): number | null { return getSessionContextPercent(this._session); }
+  subscribe(fn: (event: AgentSessionEvent) => void): () => void { return this._session.subscribe(fn); }
+  getSessionStats(): SessionStatsLike { return this._session.getSessionStats(); }
+  get messages(): readonly unknown[] { return this._session.messages as readonly unknown[]; }
+  get agentMessages(): readonly SessionMessage[] { return this._session.messages; }
+  getToolDefinition(name: string): ToolDefinition | undefined { return this._session.getToolDefinition(name); }
 
-  /**
-   * Tear down the child session exactly once.
-   *
-   * AgentSession.dispose() revokes extension contexts immediately but does not
-   * emit the extension lifecycle event. Child-owned extensions need the same
-   * awaited shutdown boundary as root-session replacement so they can cancel
-   * detached work before their Pi API is invalidated.
-   */
   dispose(): Promise<void> {
     this.disposalPromise ??= this.disposeOnce();
     return this.disposalPromise;
@@ -410,21 +268,15 @@ export class SubagentSession {
 
   private async disposeOnce(): Promise<void> {
     try {
-      await this._session.extensionRunner.emit({
-        type: "session_shutdown",
-        reason: "quit",
-      });
+      await this._session.extensionRunner.emit({ type: "session_shutdown", reason: "quit" });
     } catch (error) {
-      // A faulty extension must not prevent the SDK session from being revoked.
       debugLog("child extension session_shutdown", error);
     }
-
     try {
       this._session.dispose();
     } catch (error) {
       debugLog("child session dispose", error);
     }
-
     try {
       this.meta.lifecycle.disposed({ sessionId: this.meta.sessionId });
     } catch (error) {
@@ -433,39 +285,17 @@ export class SubagentSession {
   }
 }
 
-// ── Private turn-loop helpers ───────────────────────────────────────────────────
-
-function toLifecycleOutcome(
-  outcome: Readonly<{ aborted: boolean; steered: boolean }>,
-): SubagentLifecycleOutcome {
-  if (outcome.aborted) return "aborted";
-  if (outcome.steered) return "steered";
-  return "completed";
-}
-
-/**
- * Subscribe to a session and collect the last assistant message text.
- * Returns an object with a `getText()` getter and an `unsubscribe` function.
- */
 function collectResponseText(session: AgentSession) {
   let text = "";
   const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
     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;
-      }
+      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 };
 }
 
-/** Get the last assistant text from the completed session history. */
 function getLastAssistantText(session: AgentSession, startIndex = 0): string {
   for (let i = session.messages.length - 1; i >= startIndex; i--) {
     const msg = session.messages[i];
@@ -476,45 +306,25 @@ function getLastAssistantText(session: AgentSession, startIndex = 0): string {
   return "";
 }
 
-/** Classify a normally-resolved failure from this invocation's final assistant turn. */
 function finalTurnError(session: AgentSession, startIndex = 0): string | undefined {
   for (let i = session.messages.length - 1; i >= startIndex; i--) {
     const msg = session.messages[i];
     if (msg.role !== "assistant") continue;
-    if (msg.stopReason === "error") {
-      return msg.errorMessage?.trim() || "provider error with no output";
-    }
-    if (msg.stopReason === "length" && !extractText(msg.content).trim()) {
-      return "run hit the output token limit before producing any text";
-    }
+    if (msg.stopReason === "error") return msg.errorMessage?.trim() || "provider error with no output";
+    if (msg.stopReason === "length" && !extractText(msg.content).trim()) return "run hit the output token limit before producing any text";
     return undefined;
   }
   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);
-  }
+  for (const [context, release] of handles) runSafely(context, release);
 }
 
-/**
- * Wire an AbortSignal to abort a session.
- * Returns a cleanup function to remove the listener.
- */
-function forwardAbortSignal(
-  session: AgentSession,
-  signal?: AbortSignal,
-): () => void {
+function forwardAbortSignal(session: AgentSession, signal?: AbortSignal): () => void {
   if (!signal) return () => {};
-  const onAbort = (): void => {
-    runDetached("parent-signal abort", () => session.abort());
-  };
+  const onAbort = (): void => runDetached("parent-signal abort", () => session.abort());
   signal.addEventListener("abort", onAbort, { once: true });
+  if (signal.aborted) onAbort();
   return () => signal.removeEventListener("abort", onAbort);
 }