@fitchmultz/pi-subagents 0.44.7 → 0.46.0

package/src/runs/background/runner-child-executor.ts

@@ -0,0 +1,232 @@
+import * as path from "node:path";
+import type { ReadonlyDeep } from "type-fest";
+import { appendJsonl } from "../../shared/artifacts.ts";
+import { buildControlEvent } from "../shared/subagent-control.ts";
+import { flattenSteps } from "../shared/parallel-utils.ts";
+import type { RunnerSubagentStep } from "../../shared/types.ts";
+import type { ParallelStopReason } from "../shared/workflow-policy.ts";
+import type {
+  SubagentRunConfig,
+  RunSingleStepResult,
+  SingleStepContext,
+} from "./runner-contract.ts";
+import type { RunnerMonitor } from "./runner-monitor.ts";
+import type { RunnerLifecycle } from "./runner-lifecycle.ts";
+import {
+  markStepPaused,
+  startRunnerStep,
+  finishRunnerStep,
+  runnerResultEvent,
+  tokenUsageFromAttempts,
+} from "./runner-status.ts";
+import { runSingleStep } from "./runner-step.ts";
+
+export type AsyncParallelStepResult = ReadonlyDeep<RunSingleStepResult & { skipped?: boolean }>;
+
+export interface ChildRunInput {
+  readonly task: RunnerSubagentStep;
+  readonly worktreePath?: string;
+  readonly flatIndex: number;
+  readonly interruptSignal?: AbortSignal;
+  readonly sequential?: boolean;
+  readonly item?: { readonly name: string; readonly value: unknown };
+  readonly taskCwd: string;
+  readonly sessionDir?: string;
+  readonly flatStepCount: number;
+  readonly resetTiming?: boolean;
+  readonly trackSession?: boolean;
+  readonly notifyCompletionGuard?: boolean;
+  readonly beforeFinish?: (result: ReadonlyDeep<RunSingleStepResult>) => void;
+}
+
+/** Executes one scheduled child; shared workflow policy still owns scheduling and admission. */
+export class RunnerChildExecutor {
+  latestSessionFile: string | undefined;
+  private readonly config: ReadonlyDeep<SubagentRunConfig>;
+  private readonly monitor: RunnerMonitor;
+  private readonly lifecycle: RunnerLifecycle;
+  private readonly renderTask: (
+    template: string,
+    item?: Readonly<{ name: string; value: unknown }>,
+  ) => string;
+  private readonly sessionEnabled: boolean;
+
+  constructor(
+    config: ReadonlyDeep<SubagentRunConfig>,
+    monitor: RunnerMonitor,
+    lifecycle: RunnerLifecycle,
+    renderTask: (template: string, item?: Readonly<{ name: string; value: unknown }>) => string,
+  ) {
+    this.config = config;
+    this.monitor = monitor;
+    this.lifecycle = lifecycle;
+    this.renderTask = renderTask;
+    this.sessionEnabled =
+      (config.sessionDir !== undefined && config.sessionDir.length > 0) ||
+      config.share === true ||
+      flattenSteps(config.steps).some(
+        (step) => step.sessionFile !== undefined && step.sessionFile.length > 0,
+      );
+  }
+
+  async run(input: ReadonlyDeep<ChildRunInput>): Promise<AsyncParallelStepResult> {
+    const { task, flatIndex } = input;
+    const startedAt = startRunnerStep(this.monitor.statusPayload, task, {
+      asyncDir: this.config.asyncDir,
+      index: flatIndex,
+      sequential: input.sequential,
+      resetTiming: input.resetTiming,
+    });
+    this.monitor.writeStatusPayload();
+    this.append({
+      type: "subagent.step.started",
+      ts: startedAt,
+      runId: this.config.id,
+      stepIndex: flatIndex,
+      agent: task.agent,
+    });
+    const result = await runSingleStep(
+      { ...task, task: this.renderTask(task.task, input.item) },
+      this.stepContext(input),
+    );
+    this.lifecycle.register(flatIndex, undefined);
+    if (
+      input.trackSession === true &&
+      task.sessionFile !== undefined &&
+      task.sessionFile.length > 0
+    ) {
+      this.latestSessionFile = task.sessionFile;
+    }
+    // Sequential workflow outputs must be admitted before terminal step status is published.
+    input.beforeFinish?.(result);
+    this.finish(input, result, startedAt);
+    return input.sequential === true ? result : { ...result, skipped: false };
+  }
+
+  private stepContext(input: ReadonlyDeep<ChildRunInput>): SingleStepContext {
+    const { config, monitor, lifecycle } = this;
+    const index = input.flatIndex;
+    const childTarget = monitor.childTarget(index);
+    return {
+      nativeFinalization: config.runtimeVersion === 2,
+      worktreePath: input.worktreePath,
+      cwd: input.taskCwd,
+      sessionEnabled: this.sessionEnabled,
+      sessionDir: input.sessionDir,
+      artifactsDir: config.artifactsDir,
+      id: config.id,
+      flatIndex: index,
+      flatStepCount: input.flatStepCount,
+      outputFile: path.join(config.asyncDir, `output-${index}.log`),
+      childIntercomTarget: childTarget,
+      orchestratorIntercomTarget:
+        childTarget === undefined || childTarget.length === 0
+          ? undefined
+          : config.controlIntercomTarget,
+      nestedRoute: config.nestedRoute,
+      projectTrust: config.projectTrust,
+      rootSessionId: config.rootSessionId,
+      signal: lifecycle.cancellation.signal,
+      interruptSignal: input.interruptSignal,
+      registerInterrupt: (interrupt) => {
+        lifecycle.register(index, interrupt);
+      },
+      onAttemptStart: (attempt) => {
+        monitor.updateStepModel(index, attempt.model, attempt.thinking);
+      },
+      onChildEvent: (event, mutation) => {
+        monitor.updateStepFromChildEvent(index, event, mutation);
+      },
+    };
+  }
+
+  private finish(
+    input: ReadonlyDeep<ChildRunInput>,
+    result: ReadonlyDeep<RunSingleStepResult>,
+    startedAt: number,
+  ): void {
+    const endedAt = finishRunnerStep(this.monitor.statusPayload, result, {
+      index: input.flatIndex,
+      startedAt,
+      sequential: input.sequential,
+    });
+    this.monitor.writeStatusPayload();
+    this.append({
+      type: runnerResultEvent(result),
+      ts: endedAt,
+      runId: this.config.id,
+      stepIndex: input.flatIndex,
+      agent: input.task.agent,
+      exitCode: result.exitCode,
+      durationMs: endedAt - startedAt,
+      interrupted: result.interrupted,
+      agentProcessExit: result.agentProcessExit,
+      ...(input.sequential === true
+        ? { tokens: tokenUsageFromAttempts(result.modelAttempts) }
+        : {}),
+      resourceLimitExceeded: result.resourceLimitExceeded,
+    });
+    if (input.notifyCompletionGuard === true && result.completionGuardTriggered === true) {
+      this.monitor.appendControlEvent(
+        buildControlEvent({
+          from: this.monitor.statusPayload.steps[input.flatIndex].activityState,
+          to: "needs_attention",
+          runId: this.config.id,
+          agent: input.task.agent,
+          index: input.flatIndex,
+          ts: endedAt,
+          message: `${input.task.agent} completed without making edits for an implementation task`,
+          reason: "completion_guard",
+        }),
+      );
+    }
+  }
+
+  stop(
+    task: RunnerSubagentStep,
+    index: number,
+    reason: ParallelStopReason,
+  ): AsyncParallelStepResult {
+    const now = Date.now();
+    const step = this.monitor.statusPayload.steps[index];
+    const paused = reason === "interrupted";
+    const error = `Skipped due to ${reason}`;
+    const exitCode = paused ? 0 : -1;
+    if (paused) {
+      markStepPaused(step, now);
+    } else {
+      Object.assign(step, {
+        status: "failed",
+        error,
+        startedAt: now,
+        endedAt: now,
+        durationMs: 0,
+        exitCode,
+      });
+    }
+    this.monitor.statusPayload.lastUpdate = now;
+    this.monitor.writeStatusPayload();
+    this.append({
+      type: paused ? "subagent.step.paused" : "subagent.step.failed",
+      ts: now,
+      runId: this.config.id,
+      stepIndex: index,
+      agent: task.agent,
+      exitCode,
+      interrupted: paused,
+      durationMs: 0,
+    });
+    return {
+      agent: task.agent,
+      output: error,
+      error,
+      exitCode,
+      interrupted: paused,
+      skipped: true,
+    };
+  }
+
+  private append(event: ReadonlyDeep<Record<string, unknown>>): void {
+    appendJsonl(path.join(this.config.asyncDir, "events.jsonl"), JSON.stringify(event));
+  }
+}

package/src/runs/background/runner-child-observer.ts

@@ -0,0 +1,270 @@
+import type { ReadonlyDeep } from "type-fest";
+import type { ChildEvent } from "../shared/child-attempt.ts";
+import type { ResolvedControlConfig } from "../../shared/types.ts";
+import { extractTextFromContent, extractToolArgsPreview } from "../../shared/utils.ts";
+import { buildControlEvent } from "../shared/subagent-control.ts";
+import {
+  createMutatingFailureState,
+  type MutationToolResult,
+  recordMutatingFailure,
+  resetMutatingFailureState,
+  resolveCurrentPath,
+  shouldEscalateMutatingFailures,
+  summarizeRecentMutatingFailures,
+} from "../shared/mutating-tool-guard.ts";
+import { stripAcceptanceReport } from "../shared/acceptance.ts";
+import { updateStreamingText } from "../shared/streaming-text.ts";
+import {
+  appendRecentStepOutput,
+  clearStepCurrentActivity,
+  type RunnerStatusPayload,
+} from "./runner-status.ts";
+
+interface ObserverHooks {
+  readonly clearAttention: (index: number) => void;
+  readonly notify: (event: ReadonlyDeep<ReturnType<typeof buildControlEvent>>) => void;
+  readonly scheduleWrite: () => void;
+}
+
+function messageUsage(message: unknown): Readonly<{ input: number; output: number }> | undefined {
+  if (typeof message !== "object" || message === null || !("usage" in message)) {
+    return;
+  }
+  const usage = message.usage;
+  if (typeof usage !== "object" || usage === null) {
+    return;
+  }
+  return {
+    input: "input" in usage && typeof usage.input === "number" ? usage.input : 0,
+    output: "output" in usage && typeof usage.output === "number" ? usage.output : 0,
+  };
+}
+
+/** Owns the live event projection and mutating-tool failure windows. */
+export class RunnerChildObserver {
+  private readonly statusPayload: RunnerStatusPayload;
+  private readonly controlConfig: ReadonlyDeep<ResolvedControlConfig>;
+  private readonly id: string;
+  private readonly hooks: ObserverHooks;
+  private readonly mutatingFailureStates;
+  private readonly mutatingFailureWindowMs = 5 * 60_000;
+
+  constructor(
+    statusPayload: RunnerStatusPayload,
+    config: ReadonlyDeep<{ id: string; controlConfig: ResolvedControlConfig }>,
+    hooks: ObserverHooks,
+  ) {
+    this.statusPayload = statusPayload;
+    this.controlConfig = config.controlConfig;
+    this.id = config.id;
+    this.hooks = hooks;
+    this.mutatingFailureStates = statusPayload.steps.map(() => createMutatingFailureState());
+  }
+
+  expandChildren(flatIndex: number, count: number): void {
+    this.mutatingFailureStates.splice(
+      flatIndex,
+      1,
+      ...Array.from({ length: count }, () => createMutatingFailureState()),
+    );
+  }
+
+  private syncTopLevelCurrentTool(): void {
+    const active = this.statusPayload.steps
+      .filter(
+        (step) =>
+          step.status === "running" &&
+          typeof step.currentTool === "string" &&
+          step.currentTool.length > 0,
+      )
+      .sort((left, right) => (right.currentToolStartedAt ?? 0) - (left.currentToolStartedAt ?? 0))
+      .at(0);
+    this.statusPayload.currentTool = active?.currentTool;
+    this.statusPayload.currentToolStartedAt = active?.currentToolStartedAt;
+    this.statusPayload.currentPath = active?.currentPath;
+  }
+
+  updateStepFromChildEvent(
+    flatIndex: number,
+    event: ReadonlyDeep<ChildEvent>,
+    toolSnapshot?: ReadonlyDeep<MutationToolResult>,
+  ): void {
+    const step = this.statusPayload.steps.at(flatIndex);
+    if (!step) {
+      return;
+    }
+    const now = Date.now();
+    this.statusPayload.currentStep = flatIndex;
+    if (step.activityState === "needs_attention") {
+      step.activityState = undefined;
+      this.hooks.clearAttention(flatIndex);
+      this.statusPayload.activityState = this.statusPayload.steps.some(
+        (candidate) => candidate.activityState === "needs_attention",
+      )
+        ? "needs_attention"
+        : undefined;
+    }
+    step.streamingText = updateStreamingText(step.streamingText, event);
+    this.recordChildActivity(flatIndex, event, toolSnapshot, now);
+    this.syncTopLevelCurrentTool();
+    step.lastActivityAt = now;
+    this.statusPayload.lastActivityAt = now;
+    this.statusPayload.lastUpdate = now;
+    this.hooks.scheduleWrite();
+  }
+  private recordChildActivity(
+    flatIndex: number,
+    event: ReadonlyDeep<ChildEvent>,
+    toolSnapshot: ReadonlyDeep<MutationToolResult> | undefined,
+    now: number,
+  ): void {
+    const step = this.statusPayload.steps[flatIndex];
+    switch (event.type) {
+      case "tool_execution_start":
+        this.recordToolStart(flatIndex, event, now);
+        return;
+      case "tool_execution_end":
+        if (step.currentTool !== undefined && step.currentTool.length > 0) {
+          step.recentTools ??= [];
+          step.recentTools.push({
+            tool: step.currentTool,
+            args: step.currentToolArgs ?? "",
+            endMs: now,
+          });
+        }
+        clearStepCurrentActivity(step);
+        return;
+      case "message_end":
+        this.recordCompletedMessage(flatIndex, event, toolSnapshot, now);
+        return;
+      case undefined:
+      default:
+        return;
+    }
+  }
+
+  private recordToolStart(flatIndex: number, event: ReadonlyDeep<ChildEvent>, now: number): void {
+    if (event.toolName === undefined || event.toolName.length === 0) {
+      return;
+    }
+    const step = this.statusPayload.steps[flatIndex];
+    step.toolCount = (step.toolCount ?? 0) + 1;
+    step.currentTool = event.toolName;
+    step.currentToolArgs = extractToolArgsPreview(event.args ?? {});
+    step.currentToolStartedAt = now;
+    step.currentPath = resolveCurrentPath(event.toolName, event.args);
+    this.statusPayload.toolCount = (this.statusPayload.toolCount ?? 0) + 1;
+  }
+
+  private recordCompletedMessage(
+    flatIndex: number,
+    event: ReadonlyDeep<ChildEvent>,
+    toolSnapshot: ReadonlyDeep<MutationToolResult> | undefined,
+    now: number,
+  ): void {
+    const step = this.statusPayload.steps[flatIndex];
+    const message = event.message;
+    if (message?.role === "toolResult") {
+      const text = extractTextFromContent(message.content);
+      appendRecentStepOutput(step, text.split("\n").slice(-10));
+      if (toolSnapshot?.mutates === true) {
+        this.recordMutationResult(flatIndex, toolSnapshot, text, now);
+      }
+    } else if (message?.role === "assistant") {
+      appendRecentStepOutput(
+        step,
+        stripAcceptanceReport(extractTextFromContent(message.content)).split("\n").slice(-10),
+      );
+      step.turnCount = (step.turnCount ?? 0) + 1;
+      const usage = messageUsage(message);
+      if (usage) {
+        this.recordUsage(flatIndex, usage);
+      }
+      this.statusPayload.turnCount = Math.max(this.statusPayload.turnCount ?? 0, step.turnCount);
+    }
+  }
+
+  private recordUsage(flatIndex: number, usage: Readonly<{ input: number; output: number }>): void {
+    const step = this.statusPayload.steps[flatIndex];
+    const { input, output } = usage;
+    const previousInput = step.tokens?.input ?? 0;
+    const previousOutput = step.tokens?.output ?? 0;
+    step.tokens = {
+      input: previousInput + input,
+      output: previousOutput + output,
+      total: previousInput + previousOutput + input + output,
+    };
+    const totalInput = this.statusPayload.totalTokens?.input ?? 0;
+    const totalOutput = this.statusPayload.totalTokens?.output ?? 0;
+    this.statusPayload.totalTokens = {
+      input: totalInput + input,
+      output: totalOutput + output,
+      total: totalInput + totalOutput + input + output,
+    };
+  }
+
+  private recordMutationResult(
+    flatIndex: number,
+    snapshot: ReadonlyDeep<MutationToolResult>,
+    text: string,
+    now: number,
+  ): void {
+    const state = this.mutatingFailureStates[flatIndex];
+    if (!snapshot.errored) {
+      resetMutatingFailureState(state);
+      return;
+    }
+    recordMutatingFailure(
+      state,
+      {
+        tool: snapshot.tool,
+        path: snapshot.path,
+        error:
+          text
+            .split("\n")
+            .find((line) => line.trim().length > 0)
+            ?.trim()
+            .slice(0, 180) ?? "mutating tool failed",
+        ts: now,
+      },
+      this.mutatingFailureWindowMs,
+    );
+    const step = this.statusPayload.steps[flatIndex];
+    if (
+      !this.controlConfig.enabled ||
+      !shouldEscalateMutatingFailures(
+        state,
+        this.controlConfig.failedToolAttemptsBeforeAttention,
+      ) ||
+      step.activityState === "needs_attention"
+    ) {
+      return;
+    }
+    const previous = step.activityState;
+    step.activityState = "needs_attention";
+    this.statusPayload.activityState = "needs_attention";
+    this.hooks.notify(
+      buildControlEvent({
+        type: "needs_attention",
+        from: previous,
+        to: "needs_attention",
+        runId: this.id,
+        agent: step.agent,
+        index: flatIndex,
+        ts: now,
+        message: `${step.agent} needs attention after repeated mutating tool failures`,
+        reason: "tool_failures",
+        turns: step.turnCount,
+        tokens: step.tokens?.total,
+        toolCount: step.toolCount,
+        currentTool: snapshot.tool,
+        currentToolDurationMs:
+          snapshot.startedAt === undefined || snapshot.startedAt === 0
+            ? undefined
+            : Math.max(0, now - snapshot.startedAt),
+        currentPath: snapshot.path,
+        recentFailureSummary: summarizeRecentMutatingFailures(state),
+      }),
+    );
+  }
+}

package/src/runs/background/runner-completion-summary.ts

@@ -0,0 +1,106 @@
+import type { ReadonlyDeep } from "type-fest";
+import {
+  type AsyncResultFile,
+  type MaxOutputConfig,
+  type SubagentRunMode,
+  truncateOutput,
+} from "../../shared/types.ts";
+import { acceptanceHumanAction } from "../shared/acceptance.ts";
+import { appendWorktreeSummary } from "../shared/worktree.ts";
+import type { StepResult } from "./runner-contract.ts";
+
+function childText(result: ReadonlyDeep<StepResult>): string {
+  if (
+    result.error !== undefined &&
+    result.error.length > 0 &&
+    !result.output.includes(result.error)
+  ) {
+    return `${result.error}\n${result.output}`.trim();
+  }
+  return result.output;
+}
+
+export function runLabel(mode: SubagentRunMode): string {
+  if (mode === "parallel") {
+    return "Parallel run";
+  }
+  return mode === "chain" ? "Chain" : "Run";
+}
+
+export function completionSummary(
+  input: ReadonlyDeep<{
+    mode: SubagentRunMode;
+    results: readonly StepResult[];
+    error?: string;
+    timedOut?: boolean;
+    worktreeSummaries: readonly string[];
+  }>,
+): string {
+  const onlyResult = input.results.at(0);
+  let summary =
+    input.mode === "single" && input.results.length === 1 && onlyResult !== undefined
+      ? childText(onlyResult)
+      : input.results.map((result) => `${result.agent}:\n${childText(result)}`).join("\n\n");
+  if (input.error !== undefined && input.error.length > 0 && !summary.includes(input.error)) {
+    summary = `${input.error}\n\n${summary}`.trim();
+  }
+  if (input.timedOut === true) {
+    summary = [`${runLabel(input.mode)} timed out.`, summary]
+      .filter((line) => line.length > 0)
+      .join("\n\n");
+  }
+  if (input.worktreeSummaries.length > 0) {
+    summary = appendWorktreeSummary(summary, input.worktreeSummaries.join("\n\n"));
+  }
+  return summary;
+}
+
+export function truncateStepResult(
+  result: ReadonlyDeep<StepResult>,
+  limits: ReadonlyDeep<Required<MaxOutputConfig>>,
+): NonNullable<AsyncResultFile["results"]>[number] {
+  const outputPath = result.artifactPaths?.outputPath;
+  const reference =
+    result.outputMode === "file-only" && result.exitCode === 0 ? result.outputReference : undefined;
+  const childOutput =
+    reference !== undefined
+      ? { text: reference.message, truncated: false }
+      : truncateOutput(result.output, limits, outputPath);
+  let finalOutput = result.finalOutput;
+  if (reference !== undefined) {
+    finalOutput = reference.message;
+  } else if (finalOutput !== undefined) {
+    finalOutput = truncateOutput(finalOutput, limits, outputPath).text;
+  }
+  const initialOutput =
+    result.initialOutput === undefined
+      ? undefined
+      : truncateOutput(result.initialOutput, limits, outputPath).text;
+  return Object.assign({}, result, {
+    output: childOutput.text,
+    finalOutput,
+    initialOutput,
+    truncated: result.truncated === true || childOutput.truncated ? true : undefined,
+  });
+}
+
+export function terminalSummary(
+  input: ReadonlyDeep<{
+    state: AsyncResultFile["state"];
+    results: readonly StepResult[];
+    summary: string;
+    setupCleanupWarning: string;
+  }>,
+): string {
+  if (input.state === "blocked") {
+    const actions = input.results
+      .map((result) => acceptanceHumanAction(result.acceptance))
+      .filter((action) => action !== undefined && action.length > 0);
+    return `Needs your action — acceptance incomplete.\n${actions.join("\n")}`;
+  }
+  if (input.state === "paused") {
+    const warning = input.setupCleanupWarning.length > 0 ? `\n\n${input.setupCleanupWarning}` : "";
+    return `Paused after interrupt. Waiting for explicit next action.${warning}`;
+  }
+  return input.summary;
+}