@mystilleef/pi-subagent 0.6.0 → 0.8.0

package/src/orchestration/subagent-orchestrator.ts

@@ -1,3 +1,4 @@
+import type { AgentToolUpdateCallback } from "@earendil-works/pi-agent-core";
 import { type Message, StringEnum } from "@earendil-works/pi-ai";
 import type {
   ExtensionAPI,
@@ -10,7 +11,7 @@ import type {
   AgentScope,
   ThinkingLevel,
 } from "../agent/agents.js";
-import { runSingleAgent } from "../child/process.js";
+import { runSingleAgent, SubagentAbortError } from "../child/process.js";
 import { formatSubagentResultForParent } from "../output/summary.js";
 import {
   cancelProgressState,
@@ -22,6 +23,7 @@ import {
 import {
   createSubagentError,
   getFeedbackSummaryText,
+  getLatestResult,
   getResultDisplayText,
   hasSubagentFailed,
   patchProgressFromDetails,
@@ -34,6 +36,7 @@ import type {
   SubagentDetails,
   SubagentToolResult,
 } from "../shared/types.js";
+import { getSubagentDepth } from "../shared/utils.js";
 import {
   listRunJobs,
   type RunJob,
@@ -74,6 +77,22 @@ type DetailsBuilder = (
   options?: DetailsOptions,
 ) => SubagentDetails;
 
+interface LifecycleContext {
+  pi: ExtensionAPI;
+  ctx: ExtensionContext;
+  requestId: string;
+  job: RunJob;
+  debug: boolean;
+  makeDetails: DetailsBuilder;
+  mergedSignal: AbortSignal;
+  agents: AgentConfig[];
+  agentName: string;
+  task: string;
+  parentModel: { provider: string; id: string } | undefined;
+  parentThinking: ThinkingLevel;
+  hostOnUpdate?: AgentToolUpdateCallback<SubagentDetails>;
+}
+
 function createDetailsBuilder(
   agentScope: AgentScope,
   projectAgentsDir: string | null,
@@ -108,14 +127,22 @@ function sanitizeResultDetails(
       contextWindowTokens;
   }
   if (progress !== undefined) {
-    const { activityText, lastToolPreview, ...progBase } = progress;
+    const {
+      activityText,
+      activeToolActivity,
+      lastToolPreview,
+      toolResultCompleted,
+      ...progBase
+    } = progress;
     sanitized.progress = {
       toolCalls: progBase.toolCalls.map((tc) => ({
         id: tc.id,
         preview: tc.preview,
       })),
       ...(activityText !== undefined && { activityText }),
+      ...(activeToolActivity !== undefined && { activeToolActivity }),
       ...(lastToolPreview !== undefined && { lastToolPreview }),
+      ...(toolResultCompleted !== undefined && { toolResultCompleted }),
     };
   }
   if (includeMessages) {
@@ -177,93 +204,136 @@ export function emitCompletionAlert(
   process.stdout.write("\x07");
 }
 
-async function runSubagentWorker(
-  pi: ExtensionAPI,
-  ctx: ExtensionContext,
-  agents: AgentConfig[],
-  agentName: string,
-  task: string,
-  debug: boolean,
-  parentModel: { provider: string; id: string } | undefined,
-  parentThinking: ThinkingLevel,
-  makeDetails: DetailsBuilder,
-  requestId: string,
-  job: RunJob,
-  mergedSignal: AbortSignal,
-): Promise<void> {
+function createCompletedToolResult(
+  content: string,
+  details: SubagentDetails,
+): SubagentToolResult {
+  return {
+    content: [{ type: "text", text: content }],
+    details: { ...details, renderedByMessage: true },
+  };
+}
+
+function finishLifecycleFailure(
+  lc: LifecycleContext,
+  errorMessage: string,
+  details: SubagentDetails,
+): SubagentToolResult {
+  const displayDetails = sanitizeDetailsForDisplay(details, lc.debug);
+  if (lc.mergedSignal.aborted) {
+    cancelProgressState(lc.requestId, lc.job.cancelReason ?? errorMessage);
+    if (getSubagentDepth() > 0) {
+      sendSubagentResultMessage(lc.pi, "Canceled", displayDetails);
+    }
+    return createCompletedToolResult("Canceled", displayDetails);
+  }
+  failProgressState(lc.requestId, errorMessage);
+  lc.ctx.ui?.notify(errorMessage, "error");
+  const latestResult = getLatestResult(details);
+  const content = latestResult
+    ? formatSubagentResultForParent(latestResult) || "(failed)"
+    : errorMessage;
+  sendSubagentResultMessage(lc.pi, content, displayDetails);
+  return createCompletedToolResult(content, displayDetails);
+}
+
+function finishLifecycleResult(
+  lc: LifecycleContext,
+  result: SingleResult,
+): SubagentToolResult {
+  const details = lc.makeDetails([result]);
+  if (hasSubagentFailed(result)) {
+    return finishLifecycleFailure(
+      lc,
+      lc.mergedSignal.aborted ? "Aborted" : createSubagentError(result).message,
+      details,
+    );
+  }
+  const displayDetails = sanitizeDetailsForDisplay(details, lc.debug);
+  const content = formatSubagentResultForParent(result) || "(no output)";
+  const toolResult = createCompletedToolResult(content, displayDetails);
+  finalizeProgressState(lc.requestId, getFeedbackSummaryText(toolResult));
+  sendSubagentResultMessage(
+    lc.pi,
+    getResultDisplayText(toolResult),
+    displayDetails,
+  );
+  return toolResult;
+}
+
+function createPayloadFingerprint(payload: {
+  content: { type: string; text?: string }[];
+  details: SubagentDetails;
+}): string {
+  const contentText = payload.content[0]?.text ?? "";
+  const latestResult = payload.details.results[0];
+  const activityText = latestResult?.progress?.activityText ?? "";
+  const toolCallIds =
+    [...new Set(latestResult?.progress?.toolCalls?.map((tc) => tc.id))]
+      .sort()
+      .join(",") ?? "";
+  const exitCode = latestResult?.exitCode ?? 0;
+  const stopReason = latestResult?.stopReason ?? "";
+  return `${contentText}|${activityText}|${toolCallIds}|${exitCode}|${stopReason}`;
+}
+
+async function runSubagentLifecycle(
+  lc: LifecycleContext,
+): Promise<SubagentToolResult> {
   const seenToolCallIds = new Set<string>();
-  const requestProgressRender = createProgressRenderRequester(ctx, requestId);
+  const requestProgressRender = createProgressRenderRequester(
+    lc.ctx,
+    lc.requestId,
+  );
+  let lastDeliveredFingerprint: string | undefined;
   const onUpdate: OnUpdateCallback = (result) => {
-    patchProgressFromDetails(requestId, result.details, seenToolCallIds);
+    patchProgressFromDetails(lc.requestId, result.details, seenToolCallIds);
     requestProgressRender();
-  };
-  function handleWorkerFailure(
-    errorMessage: string,
-    isAborted: boolean,
-    details: SubagentDetails,
-  ) {
-    if (isAborted) {
-      cancelProgressState(requestId, job.cancelReason ?? errorMessage);
-    } else {
-      failProgressState(requestId, errorMessage);
-      ctx.ui?.notify(errorMessage, "error");
-      const content = details.results[0]
-        ? formatSubagentResultForParent(details.results[0] as SingleResult) ||
-          "(failed)"
-        : errorMessage;
-      sendSubagentResultMessage(
-        pi,
-        content,
-        sanitizeDetailsForDisplay(details, debug),
+    if (lc.hostOnUpdate) {
+      const sanitizedDetails = sanitizeDetailsForDisplay(
+        result.details,
+        lc.debug,
       );
+      const { renderedByMessage, ...partialDetails } = sanitizedDetails;
+      const payload = {
+        content: result.content,
+        details: partialDetails,
+      };
+      const fingerprint = createPayloadFingerprint(payload);
+      if (fingerprint !== lastDeliveredFingerprint) {
+        lastDeliveredFingerprint = fingerprint;
+        lc.hostOnUpdate(payload);
+      }
     }
-  }
+  };
+  const timerTick = setInterval(requestProgressRender, 500);
   try {
     const result = await runSingleAgent(
-      ctx.cwd,
-      agents,
-      agentName,
-      task,
-      mergedSignal,
+      lc.ctx.cwd,
+      lc.agents,
+      lc.agentName,
+      lc.task,
+      lc.mergedSignal,
       onUpdate,
-      makeDetails,
-      parentModel,
-      parentThinking,
+      lc.makeDetails,
+      lc.parentModel,
+      lc.parentThinking,
     );
-    if (hasSubagentFailed(result)) {
-      handleWorkerFailure(
-        mergedSignal.aborted ? "Aborted" : createSubagentError(result).message,
-        mergedSignal.aborted,
-        makeDetails([result]),
-      );
-    } else {
-      const toolResult: SubagentToolResult = {
-        content: [
-          {
-            type: "text" as const,
-            text: formatSubagentResultForParent(result) || "(no output)",
-          },
-        ],
-        details: makeDetails([result]),
-      };
-      finalizeProgressState(requestId, getFeedbackSummaryText(toolResult));
-      sendSubagentResultMessage(
-        pi,
-        getResultDisplayText(toolResult),
-        sanitizeDetailsForDisplay(toolResult.details, debug),
-      );
-    }
+    return finishLifecycleResult(lc, result);
   } catch (error) {
-    handleWorkerFailure(
+    const abortResult =
+      error instanceof SubagentAbortError ? error.result : undefined;
+    return finishLifecycleFailure(
+      lc,
       error instanceof Error ? error.message : String(error),
-      mergedSignal.aborted,
-      makeDetails([]),
+      abortResult ? lc.makeDetails([abortResult]) : lc.makeDetails([]),
     );
   } finally {
+    clearInterval(timerTick);
     requestProgressRender();
-    removeRunJob(requestId);
+    removeRunJob(lc.requestId);
     if (listRunJobs().length === 0) {
-      const state = getProgressState(requestId);
+      const state = getProgressState(lc.requestId);
       if (state) {
         emitCompletionAlert(state);
       }
@@ -271,23 +341,43 @@ async function runSubagentWorker(
   }
 }
 
-export type StartJobResult =
+type StartJobResult =
   | {
       kind: "started";
       requestId: string;
       instanceName: string;
       makeDetails: DetailsBuilder;
     }
+  | { kind: "completed"; result: SubagentToolResult }
   | { kind: "cancelled"; makeDetails: DetailsBuilder }
   | { kind: "not_found"; makeDetails: DetailsBuilder };
 
-export function formatStartJobStatus(
+type PrepareSubagentJobResult =
+  | {
+      kind: "ready";
+      lc: LifecycleContext;
+      instanceName: string;
+      requestProgressRender: () => void;
+      hostOnUpdate?: AgentToolUpdateCallback<SubagentDetails>;
+    }
+  | { kind: "not_found"; makeDetails: DetailsBuilder }
+  | { kind: "cancelled"; makeDetails: DetailsBuilder }
+  | { kind: "aborted"; makeDetails: DetailsBuilder };
+
+export function formatSubagentToolResult(
   agentName: string,
   result: StartJobResult,
-): string {
-  if (result.kind === "not_found") return `Unknown agent: "${agentName}"`;
-  if (result.kind === "cancelled") return "Canceled";
-  return `Subagent ${agentName} ${result.instanceName} started (job: ${result.requestId})`;
+): SubagentToolResult {
+  if (result.kind === "completed") return result.result;
+  let text: string;
+  if (result.kind === "not_found") text = `Unknown agent: "${agentName}"`;
+  else if (result.kind === "cancelled") text = "Canceled";
+  else
+    text = `Subagent ${agentName} ${result.instanceName} started (job: ${result.requestId})`;
+  return {
+    content: [{ type: "text", text }],
+    details: result.makeDetails([]),
+  };
 }
 
 function needsProjectAgentConfirmation(
@@ -309,12 +399,13 @@ function confirmProjectAgentRun(
   );
 }
 
-export async function startSubagentJob(
+async function prepareSubagentJob(
   pi: ExtensionAPI,
   ctx: ExtensionContext,
   params: Static<typeof SubagentParams>,
   hostSignal: AbortSignal | undefined,
-): Promise<StartJobResult> {
+  hostOnUpdate?: AgentToolUpdateCallback<SubagentDetails>,
+): Promise<PrepareSubagentJobResult> {
   const agentScope: AgentScope = params.agentScope ?? "both";
   const discovery = await getCachedAgentDiscovery(ctx.cwd, agentScope);
   const agents = discovery.agents;
@@ -380,32 +471,70 @@ export async function startSubagentJob(
     details: { agent: params.agent, instanceName, requestId },
   });
   const requestProgressRender = createProgressRenderRequester(ctx, requestId);
-  setImmediate(() => {
-    if (mergedSignal.aborted) {
-      cancelStartedJob(job, job.cancelReason ?? "Aborted");
-      requestProgressRender();
-      return;
-    }
-    void runSubagentWorker(
+  if (mergedSignal.aborted) {
+    cancelStartedJob(job, job.cancelReason ?? "Aborted");
+    requestProgressRender();
+    return { kind: "aborted", makeDetails: makeStartedDetails };
+  }
+  return {
+    kind: "ready",
+    lc: {
       pi,
       ctx,
+      requestId,
+      job,
+      debug,
+      makeDetails: makeStartedDetails,
+      mergedSignal,
       agents,
-      params.agent,
+      agentName: params.agent,
       task,
-      debug,
       parentModel,
       parentThinking,
-      makeStartedDetails,
-      requestId,
-      job,
-      mergedSignal,
-    );
+      hostOnUpdate,
+    },
+    instanceName,
+    requestProgressRender,
+    hostOnUpdate,
+  };
+}
+
+export async function startSubagentJob(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  params: Static<typeof SubagentParams>,
+  hostSignal: AbortSignal | undefined,
+  hostOnUpdate?: AgentToolUpdateCallback<SubagentDetails>,
+): Promise<StartJobResult> {
+  const prepared = await prepareSubagentJob(
+    pi,
+    ctx,
+    params,
+    hostSignal,
+    hostOnUpdate,
+  );
+  if (prepared.kind !== "ready") {
+    if (prepared.kind === "aborted")
+      return { kind: "cancelled", makeDetails: prepared.makeDetails };
+    return prepared;
+  }
+  const { lc, instanceName, requestProgressRender } = prepared;
+  if (getSubagentDepth() > 0) {
+    const result = await runSubagentLifecycle(lc);
+    return { kind: "completed", result };
+  }
+  setImmediate(() => {
+    if (lc.mergedSignal.aborted) {
+      cancelStartedJob(lc.job, lc.job.cancelReason ?? "Aborted");
+      requestProgressRender();
+      return;
+    }
+    runSubagentLifecycle(lc);
   });
-  if (mergedSignal.aborted) return { kind: "cancelled", makeDetails };
   return {
     kind: "started",
-    requestId,
+    requestId: lc.requestId,
     instanceName,
-    makeDetails: makeStartedDetails,
+    makeDetails: lc.makeDetails,
   };
 }

package/src/output/normalize.ts

@@ -7,35 +7,37 @@ export function normalizeSummaryValue(value: string): string {
   return normalized;
 }
 
+const SECRET_KEY_RE = /secret|token|password|passwd|credential|auth/i;
+const JWT_RE = /^eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+
 export function extractSemanticToolTarget(
-  toolName: string,
   args: Record<string, unknown>,
   forceJson = false,
 ): string {
   if (forceJson) return JSON.stringify(args);
-  if (toolName === "bash" && typeof args.command === "string")
-    return args.command;
-  if (
-    ["read", "write", "edit", "file_search"].includes(toolName) &&
-    typeof args.path === "string"
-  )
-    return args.path;
-  if (toolName === "subagent") {
-    const parts = [];
-    if (typeof args.agent === "string") parts.push(args.agent);
-    if (typeof args.task === "string")
-      parts.push(normalizeSummaryValue(args.task));
-    if (typeof args.agentScope === "string") parts.push(`[${args.agentScope}]`);
-    if (parts.length) return parts.join(" ");
-    return JSON.stringify(args);
+  const semanticKeys = [
+    "command",
+    "path",
+    "agent",
+    "query",
+    "url",
+    "action",
+    "name",
+  ];
+  for (const key of semanticKeys) {
+    const value = args[key];
+    if (typeof value === "string" && value.trim()) return value;
+  }
+  for (const key of Object.keys(args)) {
+    const value = args[key];
+    if (typeof value !== "string" || !value.trim()) continue;
+    if (SECRET_KEY_RE.test(key)) continue;
+    if (value.length > 60 || JWT_RE.test(value)) continue;
+    return value;
   }
   return "";
 }
 
-export function stripTerminalStatusPrefixes(value: string): string {
-  return value.replace(/^(?:(?:success|failure):\s*)+/i, "");
-}
-
 export function truncateText(text: string, limit: number): string {
   if (text.length <= limit) return text;
   return `${text.slice(0, limit - 1)}…`;
@@ -51,7 +53,10 @@ export function normalizeTerminalSentence(
     .replace(/^\s*`{1,3}([^`]+)`{1,3}\s*$/, "$1")
     .replace(/^\s*\*\*([^*]+)\*\*\s*$/, "$1")
     .replace(/^\s*__([^_]+)__\s*$/, "$1");
-  const withoutStatusPrefix = stripTerminalStatusPrefixes(unwrapped);
+  const withoutStatusPrefix = unwrapped.replace(
+    /^(?:(?:success|failure):\s*)+/i,
+    "",
+  );
   const withoutLabel = withoutStatusPrefix.replace(
     /^\s*(?:status|summary|result|output|message|error|check|outcome|project summary):\s+/i,
     "",
@@ -64,19 +69,21 @@ export function normalizeTerminalSentence(
 
 export const TOOL_PREVIEW_MAX_CHARS = 120;
 
+export function normalizeAndTruncate(
+  text: string,
+  limit = TOOL_PREVIEW_MAX_CHARS,
+): string {
+  return truncateText(normalizeSummaryValue(text), limit);
+}
+
 export function makeToolPreview(
   toolName: string,
   args: Record<string, unknown> | undefined,
 ): string {
   if (!args || Object.keys(args).length === 0) return toolName;
-  const target = normalizeSummaryValue(
-    extractSemanticToolTarget(toolName, args),
-  );
+  const target = normalizeSummaryValue(extractSemanticToolTarget(args));
   if (!target) return toolName;
-  return truncateText(
-    normalizeSummaryValue(`${toolName}: ${target}`),
-    TOOL_PREVIEW_MAX_CHARS,
-  );
+  return normalizeAndTruncate(`${toolName}: ${target}`);
 }
 
 export function isStatusOnlySuccess(value: string): boolean {

package/src/output/ui.ts

@@ -25,8 +25,6 @@ import {
   normalizeSummaryValue,
 } from "./normalize.js";
 
-export type { ThemeBg };
-
 /**
  * Abstraction for theme-aware text formatting.
  */
@@ -127,7 +125,7 @@ export function formatToolCall(
   forceJson = false,
 ): string {
   const target = normalizeSummaryValue(
-    extractSemanticToolTarget(toolName, args, forceJson),
+    extractSemanticToolTarget(args, forceJson),
   );
   if (!target) return themeFg("accent", toolName);
   return themeFg("accent", toolName) + themeFg("dim", ` ${target}`);
@@ -183,7 +181,8 @@ export function renderSubagentCall(
 ): Text {
   const scope: AgentScope = args.agentScope ?? "both";
   const agentName = args.agent || "...";
-  const target = extractSemanticToolTarget("subagent", args);
+  // Parser-owned preview suppresses task text: show agent + scope only
+  const target = args.agent ? `[${scope}]` : JSON.stringify(args);
   let text =
     theme.fg("toolTitle", theme.bold("subagent ")) +
     theme.fg("accent", agentName) +
@@ -192,15 +191,17 @@ export function renderSubagentCall(
   return new Text(text, 0, 0, (line) => theme.bg("toolPendingBg", line));
 }
 
-/**
- * Renders the subagent result box.
- *
- * Invariants:
- * - Red background indicates failure (exit code, error reason, or message error).
- * - Green background indicates success.
- * - Trims redundant "Outcome:" lines from the body.
- * - Displays usage stats and duration in the footer.
- */
+export function renderSubagentToolResult(
+  result: { content: { type: string; text?: string }[]; details?: unknown },
+  theme: SubagentTheme,
+  display?: { isPartial?: boolean },
+): Component {
+  const details = result.details as SubagentDetails | undefined;
+  if (details?.renderedByMessage) return new Text("", 0, 0);
+  return renderSubagentResult(result, theme, display);
+}
+
+// Invariants: Red background = failure, green = success. Trims redundant "Outcome:" lines. Shows usage stats + duration in footer.
 export function renderSubagentResult(
   result: { content: { type: string; text?: string }[]; details?: unknown },
   theme: SubagentTheme,
@@ -226,7 +227,15 @@ export function renderSubagentResult(
       : "success";
   const finalOutput = r.finalOutput ?? getFinalOutput(r.messages ?? []);
   const title = formatSubagentTitle(r.agent, r.instanceName, theme);
-  const bodyText = stripOutcomeLineForResultUi(bodyOverride ?? finalOutput);
+  let effectiveBody = bodyOverride ?? finalOutput;
+  if (_display?.isPartial && !finalOutput?.trim() && !bodyOverride) {
+    effectiveBody =
+      result.content[0]?.text ||
+      r.progress?.activityText ||
+      r.progress?.lastToolPreview ||
+      "(running...)";
+  }
+  const bodyText = stripOutcomeLineForResultUi(effectiveBody);
   const toolCount = r.progress?.toolCalls?.length ?? 0;
   const toolLabel = `${toolCount} ${toolCount === 1 ? "tool" : "tools"}`;
   const ctxPercent = formatContextPercent({
@@ -339,7 +348,6 @@ function renderJobCard(
   );
 }
 
-/** Sort states by startTime descending (newest first). */
 function sortByStartTimeDesc(
   a: SubagentProgressState,
   b: SubagentProgressState,
@@ -355,11 +363,8 @@ const BOARD_SECTIONS: [string, ProgressStatus][] = [
   ["SUCCEEDED", "success"],
 ];
 
-/**
- * Renders a unified job board for the `/jobs` command.
- * Jobs render in status-specific sections, each sorted by `startTime` descending.
- * Status icons preserve the existing /jobs contract for running and cancelled jobs.
- */
+// Jobs render in status-specific sections, each sorted by `startTime` descending.
+// Status icons preserve the existing /jobs contract for running and cancelled jobs.
 export function renderRunsBoard(
   states: SubagentProgressState[],
   theme: SubagentTheme,