@mystilleef/pi-subagent 0.5.0 → 0.7.0

package/src/{process.ts → child/process.ts}

@@ -7,23 +7,27 @@
 import { type ChildProcess, spawn } from "node:child_process";
 import * as fs from "node:fs";
 import readline from "node:readline";
-import { getModel, type Message } from "@earendil-works/pi-ai";
-import type { AgentConfig, ThinkingLevel } from "./agents.js";
-import { parseChildEventLine } from "./child-events.js";
-import { makeToolPreview } from "./progress.js";
-import { isToolCallPart } from "./progress-state.js";
-import { appendSubagentResultContract } from "./prompt-contract.js";
 import {
-  getProcessTreeSpawnOptions,
-  terminateChildProcess,
-} from "./termination.js";
+  clampThinkingLevel,
+  getModel,
+  getSupportedThinkingLevels,
+  type Message,
+  type ModelThinkingLevel,
+} from "@earendil-works/pi-ai";
+import type { AgentConfig, ThinkingLevel } from "../agent/agents.js";
+import { getFinalOutput } from "../output/ui.js";
+import { makeToolPreview, renderToolActivity } from "../progress/progress.js";
+import {
+  isToolCallPart,
+  SENSITIVE_PATTERN,
+} from "../progress/progress-state.js";
 import type {
   OnUpdateCallback,
   SingleResult,
   StreamingProgress,
   SubagentDetails,
-} from "./types.js";
-import { getFinalOutput } from "./ui.js";
+  ToolActivity,
+} from "../shared/types.js";
 import {
   detectMessageError,
   getPiInvocation,
@@ -32,16 +36,59 @@ import {
   subagentDepthEnv,
   truncateOutput,
   writePromptToTempFile,
-} from "./utils.js";
+} from "../shared/utils.js";
+import {
+  type ChildKnownEvent,
+  parseChildEventLine,
+  TOOL_EXECUTION_UPDATE_EVENT,
+} from "./child-events.js";
+import { appendSubagentResultContract } from "./prompt-contract.js";
+import {
+  getProcessTreeSpawnOptions,
+  terminateChildProcess,
+} from "./termination.js";
 
 const MAX_STDERR_BYTES = 10_000;
 const AGENT_END_GRACE_MS = 250;
+export function resolveThinkingLevel(
+  requested: ThinkingLevel,
+  provider: string,
+  modelId: string,
+): { level: ThinkingLevel; warning?: string } {
+  const model = getModel(provider as never, modelId as never);
+  if (!model) return { level: requested };
+  const mkWarning = (effective: ThinkingLevel) =>
+    `Thinking level "${requested}" not supported by model "${provider}/${modelId}"; using "${effective}" instead`;
+  if (model.reasoning === false) {
+    return { level: "off", warning: mkWarning("off") };
+  }
+  if (!model.thinkingLevelMap) return { level: requested };
+  const supported = getSupportedThinkingLevels(model);
+  if (supported.length === 0) return { level: requested };
+  const clamped = clampThinkingLevel(
+    model,
+    requested as ModelThinkingLevel,
+  ) as ThinkingLevel;
+  if (clamped === requested) return { level: requested };
+  return { level: clamped, warning: mkWarning(clamped) };
+}
 
-const MAX_SUBAGENT_DEPTH = 1;
+const MAX_SUBAGENT_DEPTH = 2;
 export const TOOL_RESULT_FAILED_MESSAGE = "Subagent tool result failed.";
 
 type RuntimeResult = SingleResult & { messages: Message[] };
 
+export class SubagentAbortError extends Error {
+  constructor(public readonly result: SingleResult) {
+    super("Subagent was aborted");
+    this.name = "SubagentAbortError";
+  }
+}
+
+type TempPrompt = { dir: string; filePath: string };
+
+type PromptSetupResult = { tmpPrompt: TempPrompt | null } | { error: unknown };
+
 interface SubagentState {
   result: RuntimeResult;
   spawnError?: Error;
@@ -50,10 +97,6 @@ interface SubagentState {
   terminationPromise?: Promise<unknown>;
 }
 
-/**
- * Appends data to a string while ensuring the result does not exceed a maximum byte limit.
- * Used to prevent memory exhaustion when capturing child process stderr.
- */
 function appendWithByteLimit(
   current: string,
   data: string,
@@ -72,7 +115,10 @@ function resolveContextWindowTokens(msg: Message): number | undefined {
   const m = msg as unknown as Record<string, unknown>;
   if (typeof m.provider !== "string" || typeof m.model !== "string") return;
   try {
-    const { contextWindow } = getModel(m.provider as never, m.model as never);
+    const contextWindow = getModel(
+      m.provider as never,
+      m.model as never,
+    )?.contextWindow;
     return Number.isFinite(contextWindow) && contextWindow > 0
       ? contextWindow
       : undefined;
@@ -81,9 +127,6 @@ function resolveContextWindowTokens(msg: Message): number | undefined {
   }
 }
 
-/**
- * Normalizes AbortSignal reasons into human-readable strings.
- */
 function getAbortReason(signal: AbortSignal): string {
   const { reason } = signal;
   if (reason instanceof Error && reason.message) return reason.message;
@@ -129,6 +172,25 @@ function getAgentEndTimeoutExitCode(
  * Safety: Implements a dual-timer strategy (idle and hard) to ensure streams
  * are destroyed and promises settled even if the process or its pipes hang.
  */
+function createProcessCleanup(proc: ChildProcess, idleMs: number) {
+  let idleTimer: NodeJS.Timeout | undefined;
+  const destroyStreams = () => {
+    proc.stdout?.destroy();
+    proc.stderr?.destroy();
+  };
+  return {
+    armIdleTimer: () => {
+      if (idleTimer) clearTimeout(idleTimer);
+      idleTimer = setTimeout(destroyStreams, idleMs);
+      idleTimer.unref?.();
+    },
+    clearIdleTimer: () => {
+      if (idleTimer) clearTimeout(idleTimer);
+    },
+    destroyStreams,
+  };
+}
+
 async function waitForSubagentProcess(
   proc: ChildProcess,
   idleMs = 100,
@@ -138,27 +200,13 @@ async function waitForSubagentProcess(
     let exitCode: number | null = null;
     let exited = false;
     let settled = false;
-    let idleTimer: NodeJS.Timeout | undefined;
-
+    const cleanup = createProcessCleanup(proc, idleMs);
     const done = () => {
       if (settled) return;
       settled = true;
-      if (idleTimer) clearTimeout(idleTimer);
+      cleanup.clearIdleTimer();
       resolve(exitCode);
     };
-
-    const destroyStreams = () => {
-      proc.stdout?.destroy();
-      proc.stderr?.destroy();
-    };
-
-    const armIdleTimer = () => {
-      if (!exited) return;
-      if (idleTimer) clearTimeout(idleTimer);
-      idleTimer = setTimeout(destroyStreams, idleMs);
-      idleTimer.unref?.();
-    };
-
     proc.on("close", done);
     proc.on("error", () => {
       exitCode = 1;
@@ -168,12 +216,15 @@ async function waitForSubagentProcess(
     proc.on("exit", (code) => {
       exitCode = code;
       exited = true;
-      armIdleTimer();
-      const hardTimer = setTimeout(destroyStreams, hardMs);
+      cleanup.armIdleTimer();
+      const hardTimer = setTimeout(cleanup.destroyStreams, hardMs);
       hardTimer.unref?.();
     });
-    proc.stdout?.on("data", armIdleTimer);
-    proc.stderr?.on("data", armIdleTimer);
+    const onStreamData = () => {
+      if (exited) cleanup.armIdleTimer();
+    };
+    proc.stdout?.on("data", onStreamData);
+    proc.stderr?.on("data", onStreamData);
   });
 }
 
@@ -187,6 +238,16 @@ function buildModelDisplay(
   return thinking ? `thinking:${thinking}` : undefined;
 }
 
+const EMPTY_USAGE = {
+  input: 0,
+  output: 0,
+  cacheRead: 0,
+  cacheWrite: 0,
+  cost: 0,
+  contextTokens: 0,
+  turns: 0,
+};
+
 function initRuntimeResult(
   agentName: string,
   source: "user" | "project" | "unknown",
@@ -201,52 +262,42 @@ function initRuntimeResult(
     finalOutput: "",
     messages: [],
     stderr: "",
-    usage: {
-      input: 0,
-      output: 0,
-      cacheRead: 0,
-      cacheWrite: 0,
-      cost: 0,
-      contextTokens: 0,
-      turns: 0,
-    },
+    usage: { ...EMPTY_USAGE },
     model: modelDisplay,
   };
 }
 
+function accumulateUsage(result: RuntimeResult, msg: Message): void {
+  if (msg.role !== "assistant") return;
+  result.usage.turns++;
+  const { usage } = msg;
+  if (!usage) return;
+  result.usage.input += usage.input || 0;
+  result.usage.output += usage.output || 0;
+  result.usage.cacheRead += usage.cacheRead || 0;
+  result.usage.cacheWrite += usage.cacheWrite || 0;
+  result.usage.cost += usage.cost?.total || 0;
+  result.usage.contextTokens = usage.totalTokens || 0;
+  result.usage.contextWindowTokens =
+    resolveContextWindowTokens(msg) ?? result.usage.contextWindowTokens;
+}
+
 function addMessageToResult(result: RuntimeResult, msg: Message): void {
   result.messages.push(msg);
   result.finalOutput = truncateOutput(getFinalOutput(result.messages));
-
   if (msg.role === "toolResult" && msg.isError) {
     result.errorMessage ||= TOOL_RESULT_FAILED_MESSAGE;
   } else if (result.errorMessage === TOOL_RESULT_FAILED_MESSAGE) {
     result.errorMessage = undefined;
   }
-
-  if (msg.role !== "assistant") return;
-  result.usage.turns++;
-
-  const { usage } = msg;
-  if (usage) {
-    result.usage.input += usage.input || 0;
-    result.usage.output += usage.output || 0;
-    result.usage.cacheRead += usage.cacheRead || 0;
-    result.usage.cacheWrite += usage.cacheWrite || 0;
-    result.usage.cost += usage.cost?.total || 0;
-    result.usage.contextTokens = usage.totalTokens || 0;
-    result.usage.contextWindowTokens =
-      resolveContextWindowTokens(msg) ?? result.usage.contextWindowTokens;
+  if (msg.role === "assistant") {
+    accumulateUsage(result, msg);
+    if (!result.model && msg.model) result.model = msg.model;
+    if (msg.stopReason) result.stopReason = msg.stopReason;
+    if (msg.errorMessage) result.errorMessage = msg.errorMessage;
   }
-
-  if (!result.model && msg.model) result.model = msg.model;
-  if (msg.stopReason) result.stopReason = msg.stopReason;
-  if (msg.errorMessage) result.errorMessage = msg.errorMessage;
 }
 
-/**
- * Standardized error result generator.
- */
 function createErrorResult(
   agent: string,
   source: "user" | "project" | "unknown",
@@ -261,15 +312,7 @@ function createErrorResult(
     exitCode: 1,
     finalOutput: "",
     stderr: error,
-    usage: {
-      input: 0,
-      output: 0,
-      cacheRead: 0,
-      cacheWrite: 0,
-      cost: 0,
-      contextTokens: 0,
-      turns: 0,
-    },
+    usage: { ...EMPTY_USAGE },
     model,
   };
 }
@@ -304,10 +347,7 @@ function errorForDepthLimit(
   );
 }
 
-async function cleanupTempPrompt(tmpPrompt: {
-  dir: string;
-  filePath: string;
-}): Promise<void> {
+async function cleanupTempPrompt(tmpPrompt: TempPrompt): Promise<void> {
   try {
     await fs.promises.unlink(tmpPrompt.filePath);
     await fs.promises.rmdir(tmpPrompt.dir);
@@ -316,6 +356,22 @@ async function cleanupTempPrompt(tmpPrompt: {
   }
 }
 
+function beginPromptSetup(agent: AgentConfig): Promise<PromptSetupResult> {
+  if (!agent.systemPrompt.trim()) return Promise.resolve({ tmpPrompt: null });
+  return writePromptToTempFile(agent.name, agent.systemPrompt).then(
+    (tmpPrompt) => ({ tmpPrompt }),
+    (error: unknown) => ({ error }),
+  );
+}
+
+async function cleanupPromptSetupResult(
+  setup: PromptSetupResult,
+): Promise<void> {
+  if ("tmpPrompt" in setup && setup.tmpPrompt) {
+    await cleanupTempPrompt(setup.tmpPrompt);
+  }
+}
+
 function findRecentMessagesAnchor(messages: Message[]): number {
   for (let i = messages.length - 1; i >= 0; i--) {
     const msg = messages[i];
@@ -334,10 +390,13 @@ function findRecentMessagesAnchor(messages: Message[]): number {
 /**
  * Derives current execution progress from accumulated messages.
  * Maps tool calls to UI-safe previews for real-time feedback.
+ * Builds activeToolActivity from the most recent tool call, providing
+ * a compact parent summary for subagent tools before nested child data arrives.
  */
 function deriveStreamingProgress(messages: Message[]): StreamingProgress {
   const toolCalls: { id: string; preview: string }[] = [];
   let lastToolPreview: string | undefined;
+  let activeToolActivity: ToolActivity | undefined;
   for (const msg of messages) {
     if (msg.role !== "assistant" || !Array.isArray(msg.content)) continue;
     for (const part of msg.content) {
@@ -348,9 +407,15 @@ function deriveStreamingProgress(messages: Message[]): StreamingProgress {
       );
       toolCalls.push({ id: part.id, preview });
       lastToolPreview = preview;
+      activeToolActivity = { toolName: part.name, inputSummary: preview };
     }
   }
-  return { activityText: lastToolPreview, toolCalls, lastToolPreview };
+  return {
+    activeToolActivity,
+    activityText: renderToolActivity(activeToolActivity),
+    toolCalls,
+    lastToolPreview,
+  };
 }
 
 /**
@@ -358,23 +423,62 @@ function deriveStreamingProgress(messages: Message[]): StreamingProgress {
  * Redacts values if the preview contains sensitive keywords.
  */
 function sanitizeProgressPreview(preview: string, toolName: string): string {
-  return /secret|token|password/i.test(preview) ? toolName : preview;
+  return SENSITIVE_PATTERN.test(preview) ? toolName : preview;
 }
 
-function makeEmitUpdate(
+export function makeEmitUpdate(
   result: RuntimeResult,
   onUpdate: OnUpdateCallback | undefined,
   makeDetails: (
     results: RuntimeResult[],
     options?: { includeMessages?: boolean; recentMessages?: Message[] },
   ) => SubagentDetails,
-): () => void {
-  return () => {
+): (options?: {
+  toolActivity?: ToolActivity;
+  toolResultCompleted?: boolean;
+}) => void {
+  return (options) => {
     const msgs = result.messages;
     const anchorIdx = findRecentMessagesAnchor(msgs);
     const recentMessages =
       anchorIdx >= 0 ? msgs.slice(anchorIdx) : msgs.slice(-5);
     const progress = deriveStreamingProgress(msgs);
+    // Preserve stored activity tree for tool-result completion signals
+    // so the parent retains nested context until newer activity arrives
+    if (options?.toolResultCompleted && result.progress?.activeToolActivity) {
+      progress.activeToolActivity = result.progress.activeToolActivity;
+      progress.activityText = renderToolActivity(progress.activeToolActivity);
+    }
+    // Handle parsed tool activity from child events
+    // Merge with parent activity if this is a nested update
+    if (options?.toolActivity) {
+      if (
+        progress.activeToolActivity &&
+        progress.activeToolActivity.toolName === options.toolActivity.toolName
+      ) {
+        // Merge: prefer parser inputSummary when non-empty and richer than bare toolName fallback
+        const incomingSummary = options.toolActivity.inputSummary;
+        const preferIncoming =
+          incomingSummary && incomingSummary !== options.toolActivity.toolName;
+        progress.activeToolActivity = {
+          ...progress.activeToolActivity,
+          inputSummary: preferIncoming
+            ? incomingSummary
+            : progress.activeToolActivity.inputSummary,
+          instanceName:
+            options.toolActivity.instanceName ??
+            progress.activeToolActivity.instanceName,
+          child:
+            options.toolActivity.child ?? progress.activeToolActivity.child,
+        };
+      } else {
+        progress.activeToolActivity = options.toolActivity;
+      }
+      progress.activityText = renderToolActivity(progress.activeToolActivity);
+    }
+    if (options?.toolResultCompleted) {
+      progress.toolResultCompleted = true;
+    }
     result.progress = progress;
     onUpdate?.({
       content: [
@@ -414,33 +518,49 @@ function clearGraceTimer(state: SubagentState): void {
   state.agentEndGraceTimer = undefined;
 }
 
-function processEventLine(
-  line: string,
+function handleMessageEvent(
+  event: ChildKnownEvent,
   state: SubagentState,
-  emitUpdate: () => void,
-  requestTermination: (reason: string) => Promise<unknown>,
+  emitUpdate: (options?: {
+    toolActivity?: ToolActivity;
+    toolResultCompleted?: boolean;
+  }) => void,
 ): void {
-  const parseResult = parseChildEventLine(line);
-  if (parseResult.kind !== "known") return;
-  const { event } = parseResult;
-
-  if (
-    (event.type === "message_end" || event.type === "tool_result_end") &&
-    event.message
-  ) {
+  if (event.type !== "message_end" && event.type !== "tool_result_end") return;
+  if (event.message) {
     addMessageToResult(state.result, event.message as Message);
-    emitUpdate();
+    const toolResultCompleted = event.type === "tool_result_end";
+    emitUpdate({ toolResultCompleted });
   }
+}
 
-  if (event.type !== "agent_end") return;
+function handleToolExecutionUpdateEvent(
+  event: ChildKnownEvent,
+  emitUpdate: (options?: {
+    toolActivity?: ToolActivity;
+    toolResultCompleted?: boolean;
+  }) => void,
+): void {
+  if (event.type !== TOOL_EXECUTION_UPDATE_EVENT) return;
+  emitUpdate({ toolActivity: event.toolActivity });
+}
 
+function handleAgentEndEvent(
+  event: ChildKnownEvent,
+  state: SubagentState,
+  emitUpdate: (options?: {
+    toolActivity?: ToolActivity;
+    toolResultCompleted?: boolean;
+  }) => void,
+  requestTermination: (reason: string) => Promise<unknown>,
+): void {
+  if (event.type !== "agent_end") return;
   if (state.result.messages.length === 0 && Array.isArray(event.messages)) {
     for (const msg of event.messages as Message[]) {
       addMessageToResult(state.result, msg);
     }
     emitUpdate();
   }
-
   if (state.agentEndGraceTimer || state.terminationPromise) return;
   state.agentEndGraceTimer = setTimeout(() => {
     state.agentEndGraceTimer = undefined;
@@ -449,6 +569,23 @@ function processEventLine(
   state.agentEndGraceTimer.unref?.();
 }
 
+function processEventLine(
+  line: string,
+  state: SubagentState,
+  emitUpdate: (options?: {
+    toolActivity?: ToolActivity;
+    toolResultCompleted?: boolean;
+  }) => void,
+  requestTermination: (reason: string) => Promise<unknown>,
+): void {
+  const parseResult = parseChildEventLine(line);
+  if (parseResult.kind !== "known") return;
+  const { event } = parseResult;
+  handleMessageEvent(event, state, emitUpdate);
+  handleToolExecutionUpdateEvent(event, emitUpdate);
+  handleAgentEndEvent(event, state, emitUpdate, requestTermination);
+}
+
 function setupAbortHandler(
   signal: AbortSignal | undefined,
   state: SubagentState,
@@ -497,7 +634,10 @@ function buildPiArgs(
 function setupChildProcess(
   proc: ChildProcess,
   state: SubagentState,
-  emitUpdate: () => void,
+  emitUpdate: (options?: {
+    toolActivity?: ToolActivity;
+    toolResultCompleted?: boolean;
+  }) => void,
   requestTermination: (reason: string) => Promise<unknown>,
 ): void {
   proc.once("error", (error) => {
@@ -544,7 +684,7 @@ async function finalizeResult(
   if (agentEndTimeoutExitCode !== undefined) {
     state.result.exitCode = agentEndTimeoutExitCode;
   }
-  if (state.wasAborted) throw new Error("Subagent was aborted");
+  if (state.wasAborted) throw new SubagentAbortError(state.result);
   return state.result;
 }
 
@@ -556,7 +696,7 @@ async function finalizeResult(
  * the main conversation.
  *
  * Safety:
- * - Enforces a strict recursion limit (depth 1) via environment variables.
+ * - Enforces a strict recursion limit (depth 2) via environment variables.
  * - Uses temporary prompt files to pass large system prompts without shell limits.
  * - Streams JSON events from the child to provide real-time UI updates to the parent.
  * - Implements aggressive process tree termination to prevent orphan processes.
@@ -579,18 +719,28 @@ export async function runSingleAgent(
 ): Promise<SingleResult> {
   const agent = agents.find((a) => a.name === agentName);
   if (!agent) return errorForUnknownAgent(agentName, agents, task);
-
   const depth = getSubagentDepth();
   if (depth >= MAX_SUBAGENT_DEPTH) {
     return errorForDepthLimit(agentName, agent.source, task, depth);
   }
-
-  const thinking = agent.thinking ?? parentThinking;
+  const requestedThinking = agent.thinking ?? parentThinking;
+  const { level: thinking, warning: thinkingWarning } = parentModel
+    ? resolveThinkingLevel(
+        requestedThinking,
+        parentModel.provider,
+        parentModel.id,
+      )
+    : { level: requestedThinking };
   const modelDisplay = buildModelDisplay(parentModel, thinking);
-  const resolvedSkills = agent.skills
-    ? await resolveAgentSkillArgs(defaultCwd, agent.skills)
-    : { args: [] };
+  const resolvedSkillsPromise: Promise<{ args: string[] } | { error: string }> =
+    agent.skills
+      ? resolveAgentSkillArgs(defaultCwd, agent.skills)
+      : Promise.resolve({ args: [] });
+  const promptSetupPromise = beginPromptSetup(agent);
+  const resolvedSkills = await resolvedSkillsPromise;
   if ("error" in resolvedSkills) {
+    const promptSetup = await promptSetupPromise;
+    await cleanupPromptSetupResult(promptSetup);
     return createErrorResult(
       agentName,
       agent.source,
@@ -599,18 +749,16 @@ export async function runSingleAgent(
       modelDisplay,
     );
   }
-
+  const promptSetup = await promptSetupPromise;
+  if ("error" in promptSetup) throw promptSetup.error;
   const startedAt = Date.now();
   const state: SubagentState = {
     result: initRuntimeResult(agentName, agent.source, task, modelDisplay),
     wasAborted: false,
   };
-
-  let tmpPrompt: { dir: string; filePath: string } | null = null;
+  if (thinkingWarning) state.result.thinkingWarning = thinkingWarning;
+  const tmpPrompt = promptSetup.tmpPrompt;
   try {
-    tmpPrompt = agent.systemPrompt.trim()
-      ? await writePromptToTempFile(agent.name, agent.systemPrompt)
-      : null;
     const args = buildPiArgs(
       agent,
       task,
@@ -632,7 +780,6 @@ export async function runSingleAgent(
       env: { ...process.env, ...subagentDepthEnv() },
       ...getProcessTreeSpawnOptions(terminateOptions.tree),
     });
-
     const processDone = waitForSubagentProcess(proc);
     const emitUpdate = makeEmitUpdate(state.result, onUpdate, makeDetails);
     const requestTermination = makeRequestTerminator(
@@ -641,7 +788,6 @@ export async function runSingleAgent(
       state,
     );
     setupChildProcess(proc, state, emitUpdate, requestTermination);
-
     const onAbort = setupAbortHandler(
       signal,
       state,

package/src/{prompt-contract.ts → child/prompt-contract.ts}

@@ -3,6 +3,8 @@ export const SUBAGENT_RESULT_CONTRACT = `
 - End your final response with exactly one line:
   - Outcome: <short, single, compact lower-case sentence>.
   - Outcome summarizes the result of your task in a single sentence.
+  - The outcome line is for internal use by the agent.
+  - Don't present outcome line in the main agent's response.
 `;
 
 export function appendSubagentResultContract(prompt: string): string {