@mystilleef/pi-subagent 0.3.0

package/src/run.ts

@@ -0,0 +1,53 @@
+import type { SubagentDetails } from "./types.js";
+import { renderSubagentResult, type SubagentTheme } from "./ui.js";
+
+/**
+ * Pi message renderer adapter for `"subagent-result"` messages.
+ *
+ * Normalizes the Pi message payload into the canonical shape expected by
+ * {@link renderSubagentResult}, bridging the gap between Pi's
+ * `MessageRenderer` contract and the internal result component.
+ *
+ * ## Rationale
+ *
+ * Pi's message renderer interface passes `content` as `unknown` — it can be
+ * a raw string or an array of content blocks from a tool call. The internal
+ * `renderSubagentResult` expects a uniform `{ type: string; text?: string }[]`
+ * array. This adapter handles both shapes.
+ *
+ * The first text block is extracted as `bodyOverride`. When set, it
+ * replaces the result body that `renderSubagentResult` would normally
+ * extract from `details.results[0].finalOutput`. This lets callers
+ * inject a pre-formatted summary (e.g., from `/run` summarization)
+ * while keeping the details-derived header metadata intact.
+ *
+ * The `_options` parameter is part of Pi's `MessageRenderer` contract
+ * but not consumed — the result card always renders at full width.
+ *
+ * @param message - Pi message with optional string/array content and details.
+ *   `details` is cast to {@link SubagentDetails}; non-conforming payloads
+ *   produce a fallback `"(no output)"` text block inside the callee.
+ * @param _options - Unused; Pi `MessageRenderer` contract.
+ * @param theme - TUI theme forwarded to `renderSubagentResult`.
+ * @returns Rendered `Component` for the subagent result card.
+ */
+export function renderSubagentResultMessage(
+  message: { content?: unknown; details?: unknown },
+  _options: { expanded: boolean },
+  theme: SubagentTheme,
+) {
+  const content =
+    typeof message.content === "string"
+      ? [{ type: "text", text: message.content }]
+      : Array.isArray(message.content)
+        ? (message.content as { type: string; text?: string }[])
+        : [];
+  const details = message.details as SubagentDetails | undefined;
+  const bodyOverride = content.find((item) => item.type === "text")?.text;
+  return renderSubagentResult(
+    { content, details },
+    theme,
+    undefined,
+    bodyOverride,
+  );
+}

package/src/subagent-orchestrator.ts

@@ -0,0 +1,377 @@
+import { type Message, StringEnum } from "@earendil-works/pi-ai";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import { getCachedAgentDiscovery } from "./agent-cache.js";
+import {
+  type AgentConfig,
+  type AgentScope,
+  discoverAgents,
+  type ThinkingLevel,
+} from "./agents.js";
+import { runSingleAgent } from "./process.js";
+import {
+  cancelProgressState,
+  createProgressState,
+  failProgressState,
+  finalizeProgressState,
+} from "./progress.js";
+import {
+  createSubagentError,
+  getFeedbackSummaryText,
+  getResultDisplayText,
+  hasSubagentFailed,
+  patchProgressFromDetails,
+  sanitizeDetailsForDisplay,
+} from "./result-details.js";
+import { type RunJob, registerRunJob, removeRunJob } from "./run-registry.js";
+import { formatSubagentResultForParent } from "./summary.js";
+import type {
+  OnUpdateCallback,
+  SingleResult,
+  SubagentDetails,
+  SubagentToolResult,
+} from "./types.js";
+
+const AgentScopeSchema = StringEnum(["user", "project", "both"] as const, {
+  description:
+    'Which agent directories to use. Default: "both" (user + project-local agents).',
+  default: "both",
+});
+
+export const SubagentParams = Type.Object({
+  agent: Type.String({
+    description: "Name of the agent to invoke",
+  }),
+  task: Type.Optional(
+    Type.String({
+      description: "Task to delegate. Optional for agents with defaults.",
+    }),
+  ),
+  agentScope: Type.Optional(AgentScopeSchema),
+  debug: Type.Optional(
+    Type.Boolean({
+      description:
+        "Internal debug option. Include full child messages in result details.",
+      default: false,
+    }),
+  ),
+});
+
+export type { SubagentToolResult };
+
+type DetailsOptions = { includeMessages?: boolean; recentMessages?: Message[] };
+type DetailsBuilder = (
+  results: SingleResult[],
+  options?: DetailsOptions,
+) => SubagentDetails;
+
+function createDetailsBuilder(
+  agentScope: AgentScope,
+  projectAgentsDir: string | null,
+  includeDebugMessages: boolean,
+): DetailsBuilder {
+  return (results, options) => ({
+    mode: "single",
+    agentScope,
+    projectAgentsDir,
+    results: results.map((result) =>
+      sanitizeResultDetails(result, includeDebugMessages, options),
+    ),
+  });
+}
+
+function sanitizeResultDetails(
+  result: SingleResult,
+  includeDebugMessages: boolean,
+  options: DetailsOptions | undefined,
+): SingleResult {
+  const includeMessages =
+    includeDebugMessages && (options?.includeMessages ?? true);
+  const { messages, termination, progress, stderr, usage, ...core } = result;
+  const { contextWindowTokens, ...usageBase } = usage;
+
+  const sanitized: Record<string, unknown> = {
+    ...core,
+    stderr: includeDebugMessages ? stderr : "",
+    usage: { ...usageBase },
+  };
+
+  if (contextWindowTokens !== undefined) {
+    (sanitized.usage as Record<string, unknown>).contextWindowTokens =
+      contextWindowTokens;
+  }
+
+  if (progress !== undefined) {
+    const { activityText, lastToolPreview, ...progBase } = progress;
+    sanitized.progress = {
+      toolCalls: progBase.toolCalls.map((tc) => ({
+        id: tc.id,
+        preview: tc.preview,
+      })),
+      ...(activityText !== undefined && { activityText }),
+      ...(lastToolPreview !== undefined && { lastToolPreview }),
+    };
+  }
+
+  if (includeMessages) {
+    sanitized.messages = options?.recentMessages
+      ? [...options.recentMessages]
+      : messages !== undefined
+        ? [...messages]
+        : undefined;
+
+    if (includeDebugMessages && termination !== undefined) {
+      const { cancelReason, terminationSignal, fallbackCause, ...termBase } =
+        termination;
+      sanitized.termination = {
+        ...termBase,
+        ...(cancelReason !== undefined && { cancelReason }),
+        ...(terminationSignal !== undefined && { terminationSignal }),
+        ...(fallbackCause !== undefined && { fallbackCause }),
+      };
+    }
+  }
+
+  return sanitized as unknown as SingleResult;
+}
+
+function createProgressRenderRequester(
+  ctx: ExtensionContext,
+  requestId: string,
+): () => void {
+  const progressRenderKey = `subagent-progress:${requestId}`;
+  return () => {
+    ctx.ui?.setStatus?.(progressRenderKey, `${Date.now()}`);
+    ctx.ui?.setStatus?.(progressRenderKey, undefined);
+  };
+}
+
+function cancelStartedJob(job: RunJob, reason: string): void {
+  cancelProgressState(job.requestId, reason);
+  removeRunJob(job.requestId);
+}
+
+function sendSubagentResultMessage(
+  pi: ExtensionAPI,
+  content: string,
+  details: SubagentDetails,
+): void {
+  pi.sendMessage({
+    customType: "subagent-result",
+    content,
+    display: true,
+    details,
+  });
+}
+
+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> {
+  const seenToolCallIds = new Set<string>();
+  const requestProgressRender = createProgressRenderRequester(ctx, requestId);
+  const onUpdate: OnUpdateCallback = (result) => {
+    patchProgressFromDetails(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),
+      );
+    }
+  }
+  try {
+    const result = await runSingleAgent(
+      ctx.cwd,
+      agents,
+      agentName,
+      task,
+      mergedSignal,
+      onUpdate,
+      makeDetails,
+      parentModel,
+      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),
+      );
+    }
+  } catch (error) {
+    handleWorkerFailure(
+      error instanceof Error ? error.message : String(error),
+      mergedSignal.aborted,
+      makeDetails([]),
+    );
+  } finally {
+    requestProgressRender();
+    removeRunJob(requestId);
+  }
+}
+
+export type StartJobResult =
+  | { kind: "started"; requestId: string; makeDetails: DetailsBuilder }
+  | { kind: "cancelled"; makeDetails: DetailsBuilder }
+  | { kind: "not_found"; makeDetails: DetailsBuilder };
+
+export function formatStartJobStatus(
+  agentName: string,
+  result: StartJobResult,
+): string {
+  if (result.kind === "not_found") return `Unknown agent: "${agentName}"`;
+  if (result.kind === "cancelled") return "Canceled";
+  return `Subagent ${agentName} started (job: ${result.requestId})`;
+}
+
+function needsProjectAgentConfirmation(
+  ctx: ExtensionContext,
+  agent: AgentConfig,
+): boolean {
+  return ctx.hasUI && agent.source === "project";
+}
+
+function confirmProjectAgentRun(
+  ctx: ExtensionContext,
+  agent: AgentConfig,
+  projectAgentsDir: string | null,
+): Promise<boolean> {
+  const dir = projectAgentsDir ?? "(unknown)";
+  return ctx.ui.confirm(
+    "Run project-local agent?",
+    `Agent: ${agent.name}\nSource: ${dir}\n\nProject agents are repo-controlled. Only continue for trusted repositories.`,
+  );
+}
+
+export async function startSubagentJob(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  params: Static<typeof SubagentParams>,
+  hostSignal: AbortSignal | undefined,
+): Promise<StartJobResult> {
+  const agentScope: AgentScope = params.agentScope ?? "both";
+  const discovery = getCachedAgentDiscovery(ctx.cwd, agentScope);
+  const agents = discovery.agents;
+  const debug = params.debug === true;
+  const makeDetails = createDetailsBuilder(
+    agentScope,
+    discovery.projectAgentsDir,
+    debug,
+  );
+  const requested = agents.find((a) => a.name === params.agent);
+  if (!requested) return { kind: "not_found", makeDetails };
+  if (requested.source === "project") {
+    const userAgents = discoverAgents(ctx.cwd, "user");
+    const hasUserCollision = userAgents.agents.some(
+      (a) => a.name === requested.name,
+    );
+    if (hasUserCollision) {
+      pi.sendMessage({
+        customType: "subagent-progress",
+        content: `Using project agent "${requested.name}"; user agent with same name also exists.`,
+        display: true,
+        details: {},
+      });
+    }
+  }
+  const task = params.task?.trim() ?? "";
+  if (needsProjectAgentConfirmation(ctx, requested)) {
+    const confirmed = await confirmProjectAgentRun(
+      ctx,
+      requested,
+      discovery.projectAgentsDir,
+    );
+    if (!confirmed) return { kind: "cancelled", makeDetails };
+  }
+  const parentModel = ctx.model
+    ? { provider: ctx.model.provider, id: ctx.model.id }
+    : undefined;
+  const parentThinking = pi.getThinkingLevel() as ThinkingLevel;
+  const requestId = crypto.randomUUID();
+  const controller = new AbortController();
+  const job: RunJob = registerRunJob({
+    requestId,
+    agentName: params.agent,
+    controller,
+    startedAt: Date.now(),
+  });
+  const mergedSignal = hostSignal
+    ? AbortSignal.any([hostSignal, job.controller.signal])
+    : job.controller.signal;
+  createProgressState(requestId, params.agent, task);
+  pi.sendMessage({
+    customType: "subagent-progress",
+    content: "",
+    display: true,
+    details: { requestId },
+  });
+  const requestProgressRender = createProgressRenderRequester(ctx, requestId);
+  setImmediate(() => {
+    if (mergedSignal.aborted) {
+      cancelStartedJob(job, job.cancelReason ?? "Aborted");
+      requestProgressRender();
+      return;
+    }
+    void runSubagentWorker(
+      pi,
+      ctx,
+      agents,
+      params.agent,
+      task,
+      debug,
+      parentModel,
+      parentThinking,
+      makeDetails,
+      requestId,
+      job,
+      mergedSignal,
+    );
+  });
+  if (mergedSignal.aborted) return { kind: "cancelled", makeDetails };
+  return { kind: "started", requestId, makeDetails };
+}

package/src/summary.ts

@@ -0,0 +1,63 @@
+import { normalizeTerminalSentence } from "./normalize.js";
+import type { SingleResult } from "./types.js";
+
+export const FEEDBACK_UI_SUMMARY_MAX_CHARS = 120;
+
+const FEEDBACK_UI_GENERIC_CANDIDATES = new Set([
+  "cause",
+  "done",
+  "next",
+  "output",
+  "project summary",
+  "result",
+  "status",
+  "success",
+  "summary",
+  "verification",
+]);
+
+const FEEDBACK_UI_LABEL_PATTERN =
+  /^\s*(outcome|project summary|result|summary|status|output|message|error|check):\s*/i;
+
+export function formatSubagentResultForParent(result: SingleResult): string {
+  return result.finalOutput;
+}
+
+export function summarizeFeedbackUiFinalOutput(finalOutput: string): string {
+  const candidates = finalOutput
+    .split(/\r?\n|(?<=[.!?])\s+/)
+    .map((candidate) => normalizeFeedbackUiSummaryCandidate(candidate))
+    .filter(({ text }) => hasSummaryValue(text));
+  const selected =
+    candidates.find(({ label }) => label === "outcome") ??
+    candidates.find(({ label }) => label) ??
+    candidates[0];
+  return (selected?.text ?? "completed task").toLowerCase();
+}
+
+type FeedbackUiSummaryCandidate = {
+  text: string;
+  label: string | null;
+};
+
+function normalizeFeedbackUiSummaryCandidate(
+  candidate: string,
+): FeedbackUiSummaryCandidate {
+  const label =
+    candidate.match(FEEDBACK_UI_LABEL_PATTERN)?.[1]?.toLowerCase() ?? null;
+  const text = normalizeTerminalSentence(
+    candidate,
+    FEEDBACK_UI_SUMMARY_MAX_CHARS,
+  );
+  return { text, label };
+}
+
+function hasSummaryValue(candidate: string): boolean {
+  const normalized = candidate.toLowerCase();
+  return (
+    !!normalized &&
+    !FEEDBACK_UI_GENERIC_CANDIDATES.has(normalized) &&
+    /[a-z]/i.test(candidate) &&
+    /\s/.test(candidate)
+  );
+}

package/src/termination.ts

@@ -0,0 +1,209 @@
+import type { ChildProcess } from "node:child_process";
+
+export type TerminationSignal = "SIGTERM" | "SIGKILL";
+
+export type TerminationMetadata = {
+  cancelRequestedAt: number;
+  cancelReason?: string;
+  terminationSignal?: TerminationSignal;
+  escalated: boolean;
+  processTreeKilled: boolean;
+  target: "direct" | "tree";
+  fallbackCause?: string;
+};
+
+type TimerHandle = unknown;
+
+type TerminationState = {
+  metadata: TerminationMetadata;
+  promise: Promise<TerminationMetadata>;
+  settled: boolean;
+  timer?: TimerHandle;
+  clearTimeout: (timer: TimerHandle) => void;
+  resolve: (metadata: TerminationMetadata) => void;
+};
+
+export type TerminateChildProcessOptions = {
+  reason?: string;
+  timeoutMs?: number;
+  tree?: boolean;
+  platform?: NodeJS.Platform;
+  now?: () => number;
+  setTimeout?: (callback: () => void, ms: number) => TimerHandle;
+  clearTimeout?: (timer: TimerHandle) => void;
+  killProcess?: (proc: ChildProcess, signal: TerminationSignal) => unknown;
+  processTreeDetached?: boolean;
+  killProcessTree?: (
+    proc: ChildProcess,
+    signal: TerminationSignal,
+    platform: NodeJS.Platform,
+  ) => unknown;
+  killProcessGroup?: (pid: number, signal: TerminationSignal) => unknown;
+  runTaskkill?: (args: string[]) => unknown;
+};
+
+const DEFAULT_TIMEOUT_MS = 4_000;
+const terminationStates = new WeakMap<ChildProcess, TerminationState>();
+
+export function getProcessTreeSpawnOptions(
+  tree: boolean,
+  platform: NodeJS.Platform = process.platform,
+): { detached?: boolean } {
+  return tree && platform !== "win32" ? { detached: true } : {};
+}
+
+function childHasExited(proc: ChildProcess): boolean {
+  return proc.exitCode !== null || proc.signalCode != null;
+}
+
+function hasPid(proc: ChildProcess): proc is ChildProcess & { pid: number } {
+  return typeof proc.pid === "number" && Number.isFinite(proc.pid);
+}
+
+function settleState(state: TerminationState): void {
+  if (state.settled) return;
+  state.settled = true;
+  if (state.timer) state.clearTimeout(state.timer);
+  state.timer = undefined;
+  state.resolve(state.metadata);
+}
+
+function makeState(
+  proc: ChildProcess,
+  options: TerminateChildProcessOptions,
+): TerminationState {
+  let resolveState!: (metadata: TerminationMetadata) => void;
+  const metadata: TerminationMetadata = {
+    cancelRequestedAt: options.now?.() ?? Date.now(),
+    cancelReason: options.reason,
+    escalated: false,
+    processTreeKilled: false,
+    target: options.tree ? "tree" : "direct",
+  };
+  const state: TerminationState = {
+    metadata,
+    promise: new Promise((resolve) => {
+      resolveState = resolve;
+    }),
+    settled: false,
+    clearTimeout:
+      options.clearTimeout ?? ((timer) => clearTimeout(timer as never)),
+    resolve: resolveState,
+  };
+  const settle = () => settleState(state);
+  proc.once("exit", settle);
+  proc.once("close", settle);
+  proc.once("error", settle);
+  return state;
+}
+
+function sendDirectSignal(
+  proc: ChildProcess,
+  signal: TerminationSignal,
+  state: TerminationState,
+  options: TerminateChildProcessOptions,
+): void {
+  (options.killProcess ?? ((child, nextSignal) => child.kill(nextSignal)))(
+    proc,
+    signal,
+  );
+  state.metadata.target = "direct";
+  state.metadata.processTreeKilled = false;
+}
+
+function sendTreeSignal(
+  proc: ChildProcess,
+  signal: TerminationSignal,
+  state: TerminationState,
+  options: TerminateChildProcessOptions,
+): void {
+  const platform = options.platform ?? process.platform;
+  if (!hasPid(proc)) throw new Error("missing child PID");
+  const pid = proc.pid;
+  if (!options.tree) {
+    sendDirectSignal(proc, signal, state, options);
+    return;
+  }
+  if (options.killProcessTree) {
+    options.killProcessTree(proc, signal, platform);
+    state.metadata.target = "tree";
+    state.metadata.processTreeKilled = true;
+    return;
+  }
+  if (platform !== "win32") {
+    if (!options.processTreeDetached)
+      throw new Error("process tree not detached");
+    (
+      options.killProcessGroup ??
+      ((pid, nextSignal) => process.kill(pid, nextSignal))
+    )(-pid, signal);
+    state.metadata.target = "tree";
+    state.metadata.processTreeKilled = true;
+    return;
+  }
+  if (signal === "SIGKILL") {
+    (options.runTaskkill ?? ((args) => Bun.spawnSync(["taskkill", ...args])))([
+      "/pid",
+      String(pid),
+      "/t",
+      "/f",
+    ]);
+    state.metadata.target = "tree";
+    state.metadata.processTreeKilled = true;
+    return;
+  }
+  throw new Error("unsupported tree termination platform");
+}
+
+function sendTerminationSignal(
+  proc: ChildProcess,
+  signal: TerminationSignal,
+  state: TerminationState,
+  options: TerminateChildProcessOptions,
+): void {
+  if (state.settled || childHasExited(proc) || !hasPid(proc)) {
+    settleState(state);
+    return;
+  }
+  try {
+    state.metadata.terminationSignal = signal;
+    sendTreeSignal(proc, signal, state, options);
+  } catch (error) {
+    try {
+      state.metadata.fallbackCause =
+        error instanceof Error ? error.message : "tree termination failed";
+      sendDirectSignal(proc, signal, state, options);
+    } catch {
+      settleState(state);
+    }
+  }
+}
+
+export function terminateChildProcess(
+  proc: ChildProcess,
+  options: TerminateChildProcessOptions = {},
+): Promise<TerminationMetadata> {
+  const existing = terminationStates.get(proc);
+  if (existing) return existing.promise;
+  const state = makeState(proc, options);
+  terminationStates.set(proc, state);
+  if (childHasExited(proc) || !hasPid(proc)) {
+    settleState(state);
+    return state.promise;
+  }
+  sendTerminationSignal(proc, "SIGTERM", state, options);
+  if (!state.settled) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const setTimer = options.setTimeout ?? setTimeout;
+    state.timer = setTimer(() => {
+      if (state.settled || childHasExited(proc)) {
+        settleState(state);
+        return;
+      }
+      state.metadata.escalated = true;
+      sendTerminationSignal(proc, "SIGKILL", state, options);
+    }, timeoutMs);
+    (state.timer as { unref?: () => void } | undefined)?.unref?.();
+  }
+  return state.promise;
+}