@fitchmultz/pi-subagents 0.44.7 → 0.46.0

package/src/runs/background/runner-attempt-output.ts

@@ -0,0 +1,281 @@
+import type { ReadonlyDeep } from "type-fest";
+import type { ChildAttemptResult, NativeAttemptSegment } from "../shared/child-attempt.ts";
+import type { RunnerSubagentStep } from "../../shared/types.ts";
+import { detectSubagentError } from "../../shared/utils.ts";
+import {
+  hasCompletedMutationToolCall,
+  resolveCompletionPolicy,
+} from "../shared/completion-guard.ts";
+import { readStructuredOutput, type StructuredOutputRuntime } from "../shared/structured-output.ts";
+import { type captureSingleOutputSnapshot, resolveSingleOutput } from "../shared/single-output.ts";
+import {
+  readFinalizationReport,
+  resolveFinalizationOutput,
+  stripAcceptanceReport,
+} from "../shared/acceptance.ts";
+
+export type StepAttempt = ReadonlyDeep<
+  ChildAttemptResult & {
+    readonly completionGuardTriggered?: boolean;
+    readonly structuredOutput?: unknown;
+    readonly reportSubmission?: ReturnType<typeof readFinalizationReport>;
+    readonly resolvedOutput: ReturnType<typeof resolveSingleOutput>;
+  }
+>;
+
+export interface AttemptReview {
+  readonly turn: number;
+  readonly sessionFile: string;
+  readonly previousOutput: string;
+  readonly reportRuntime?: StructuredOutputRuntime;
+  readonly outputSnapshot?: ReturnType<typeof captureSingleOutputSnapshot>;
+}
+
+interface OutputContext {
+  readonly model?: string;
+  readonly structuredRuntime?: StructuredOutputRuntime;
+  readonly review?: AttemptReview;
+  readonly outputSnapshot?: ReturnType<typeof captureSingleOutputSnapshot>;
+  readonly initialSegment?: NativeAttemptSegment;
+  readonly structuredResult: boolean;
+}
+
+export function formatProcessExitFailure(
+  input: Readonly<{ agent: string; exitCode: number | null; durationMs?: number }>,
+): string {
+  const duration = input.durationMs === undefined ? "" : ` after ${input.durationMs}ms`;
+  if (input.exitCode === 143) {
+    return `${input.agent} exited with code 143${duration}. The child process received SIGTERM or exited as if terminated by SIGTERM; if this was close to 300000ms, Pi's default HTTP idle timeout is a likely provider-side cause.`;
+  }
+  return `${input.agent} exited with code ${input.exitCode ?? 1}${duration} without producing a final assistant response.`;
+}
+
+function processFailure(
+  step: ReadonlyDeep<RunnerSubagentStep>,
+  run: ReadonlyDeep<ChildAttemptResult>,
+): string | undefined {
+  if (run.error !== undefined && run.error.length > 0) {
+    return run.error;
+  }
+  if (run.exitCode === 0) {
+    return;
+  }
+  const reason = formatProcessExitFailure({
+    agent: step.agent,
+    exitCode: run.exitCode,
+    durationMs: run.durationMs,
+  });
+  const stderr = run.stderr.trim();
+  return stderr.length === 0 ? reason : `${reason}\n${stderr}`;
+}
+
+function hiddenFailure(
+  error: ReturnType<typeof detectSubagentError> | undefined,
+): string | undefined {
+  if (error?.hasError !== true) {
+    return;
+  }
+  return error.details !== undefined && error.details.length > 0
+    ? `${error.errorType ?? "Subagent"} failed (exit ${error.exitCode ?? 1}): ${error.details}`
+    : `${error.errorType ?? "Subagent"} failed with exit code ${error.exitCode ?? 1}`;
+}
+
+function completionGuard(
+  step: ReadonlyDeep<RunnerSubagentStep>,
+  run: ReadonlyDeep<ChildAttemptResult>,
+  review: AttemptReview | undefined,
+): boolean {
+  return (
+    review === undefined &&
+    resolveCompletionPolicy({
+      completionGuardEnabled: step.completionGuard === true,
+      usesAcceptanceContract: step.effectiveAcceptance?.explicit === true,
+    }) === "mutation-guard" &&
+    !run.observedCompletedMutation &&
+    !hasCompletedMutationToolCall(run.messages)
+  );
+}
+
+function resolveAttemptOutput(
+  step: ReadonlyDeep<RunnerSubagentStep>,
+  fullOutput: string,
+  input: ReadonlyDeep<{
+    context: OutputContext;
+    run: ChildAttemptResult;
+    exitCode: number;
+    reportSubmission?: ReturnType<typeof readFinalizationReport>;
+  }>,
+): ReturnType<typeof resolveSingleOutput> {
+  if (input.context.initialSegment) {
+    return input.context.initialSegment.event.resolvedOutput;
+  }
+  if (
+    step.outputPath === undefined ||
+    step.outputPath.length === 0 ||
+    input.exitCode !== 0 ||
+    input.run.interrupted === true ||
+    (input.reportSubmission?.reportSubmissionError !== undefined &&
+      input.reportSubmission.reportSubmissionError.length > 0)
+  ) {
+    return { fullOutput };
+  }
+  return resolveSingleOutput(step.outputPath, fullOutput, input.context.outputSnapshot);
+}
+
+/** Classifies a completed attempt, validates structured output and publishes its single output. */
+export function interpretAttemptOutput(
+  step: ReadonlyDeep<RunnerSubagentStep>,
+  run: ReadonlyDeep<ChildAttemptResult>,
+  context: ReadonlyDeep<OutputContext>,
+): StepAttempt {
+  const { reportSubmission, hiddenError, structured, successful } = analyzeAttempt(run, context);
+  const guardTriggered = successful && completionGuard(step, run, context.review);
+  const error = attemptError(step, run, {
+    guardTriggered,
+    structuredError: structured?.error,
+    hiddenError,
+  });
+  const exitCode = failureExitCode(run.exitCode, {
+    guardTriggered,
+    structuredError: structured?.error,
+    hiddenError,
+    error,
+  });
+  const { finalOutput, fullOutput } = attemptText(run, reportSubmission, context.review);
+  const resolvedOutput = resolveAttemptOutput(step, fullOutput, {
+    context,
+    run,
+    exitCode,
+    reportSubmission,
+  });
+  const state = outputState(step, resolvedOutput, error, exitCode);
+  return {
+    ...run,
+    ...state,
+    model: context.model ?? run.model,
+    structuredOutput: structured?.value,
+    reportSubmission,
+    finalOutput,
+    resolvedOutput,
+    completionGuardTriggered: guardTriggered,
+    terminalFailure: terminalFailure(
+      guardTriggered,
+      structured?.error,
+      hiddenError,
+      resolvedOutput.saveError,
+    ),
+  };
+}
+
+function attemptError(
+  step: ReadonlyDeep<RunnerSubagentStep>,
+  run: ReadonlyDeep<ChildAttemptResult>,
+  input: ReadonlyDeep<{
+    guardTriggered: boolean;
+    structuredError?: string;
+    hiddenError?: ReturnType<typeof detectSubagentError>;
+  }>,
+): string | undefined {
+  if (input.guardTriggered) {
+    return "Subagent completed without making edits required by completionGuard: true.\nUse an acceptance contract when a valid no-op is allowed.";
+  }
+  return input.structuredError ?? hiddenFailure(input.hiddenError) ?? processFailure(step, run);
+}
+
+function attemptText(
+  run: ReadonlyDeep<ChildAttemptResult>,
+  report: ReadonlyDeep<ReturnType<typeof readFinalizationReport>> | undefined,
+  review: ReadonlyDeep<AttemptReview> | undefined,
+) {
+  const finalOutput = report?.output ?? run.finalOutput;
+  const fullOutput =
+    review === undefined
+      ? stripAcceptanceReport(finalOutput)
+      : resolveFinalizationOutput(finalOutput, review.previousOutput);
+  return { finalOutput, fullOutput };
+}
+
+function hiddenAttemptFailure(
+  run: ReadonlyDeep<ChildAttemptResult>,
+  report: ReadonlyDeep<ReturnType<typeof readFinalizationReport>> | undefined,
+) {
+  return successfulProcess(run) && (report === undefined || report.output.length === 0)
+    ? detectSubagentError(run.messages)
+    : undefined;
+}
+
+function analyzeAttempt(
+  run: ReadonlyDeep<ChildAttemptResult>,
+  context: ReadonlyDeep<OutputContext>,
+) {
+  const reportSubmission = context.review?.reportRuntime
+    ? readFinalizationReport(run.messages, context.review.reportRuntime, {
+        structuredResult: context.structuredResult,
+      })
+    : undefined;
+  const hiddenError = hiddenAttemptFailure(run, reportSubmission);
+  const successful =
+    successfulProcess(run) && hiddenError?.hasError !== true && run.interrupted !== true;
+  const structured =
+    successful && context.review === undefined && context.structuredRuntime
+      ? readStructuredOutput(context.structuredRuntime)
+      : undefined;
+  return { reportSubmission, hiddenError, structured, successful };
+}
+
+function successfulProcess(run: ReadonlyDeep<ChildAttemptResult>): boolean {
+  return run.exitCode === 0 && (run.error === undefined || run.error.length === 0);
+}
+
+function terminalFailure(
+  guard: boolean,
+  structuredError: string | undefined,
+  hiddenError: ReturnType<typeof detectSubagentError> | undefined,
+  saveError: string | undefined,
+): boolean {
+  return (
+    guard ||
+    (structuredError !== undefined && structuredError.length > 0) ||
+    hiddenError?.hasError === true ||
+    (saveError !== undefined && saveError.length > 0)
+  );
+}
+
+function outputState(
+  step: ReadonlyDeep<RunnerSubagentStep>,
+  resolvedOutput: ReadonlyDeep<ReturnType<typeof resolveSingleOutput>>,
+  error: string | undefined,
+  exitCode: number,
+) {
+  if (resolvedOutput.saveError !== undefined && resolvedOutput.saveError.length > 0) {
+    return {
+      exitCode: 1,
+      error: `Failed to save output file '${step.outputPath ?? ""}': ${resolvedOutput.saveError}`,
+    };
+  }
+  return { error, exitCode };
+}
+
+function failureExitCode(
+  exitCode: number,
+  input: ReadonlyDeep<{
+    guardTriggered: boolean;
+    structuredError?: string;
+    hiddenError?: ReturnType<typeof detectSubagentError>;
+    error?: string;
+  }>,
+): number {
+  if (
+    input.guardTriggered ||
+    (input.structuredError !== undefined && input.structuredError.length > 0)
+  ) {
+    return 1;
+  }
+  if (input.hiddenError?.hasError === true) {
+    return input.hiddenError.exitCode ?? 1;
+  }
+  if (input.error !== undefined && input.error.length > 0 && exitCode === 0) {
+    return 1;
+  }
+  return exitCode;
+}

package/src/runs/background/runner-attempt.ts

@@ -0,0 +1,354 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ReadonlyDeep } from "type-fest";
+import type { SingleStepContext } from "./runner-contract.ts";
+import {
+  interpretAttemptOutput,
+  formatProcessExitFailure,
+  type StepAttempt,
+  type AttemptReview,
+} from "./runner-attempt-output.ts";
+import { runPiStreaming } from "./runner-streaming.ts";
+import { captureSingleOutputSnapshot } from "../shared/single-output.ts";
+import type {
+  ToolCallSummary,
+  Usage,
+  RunnerSubagentStep as SubagentStep,
+} from "../../shared/types.ts";
+import { cleanupTempDir } from "../shared/pi-args.ts";
+import { isClaudeCodeModel } from "../shared/claude-code.ts";
+import type { createStructuredOutputRuntime } from "../shared/structured-output.ts";
+import {
+  buildChildInvocation,
+  type ChildAttemptResult,
+  type NativeAttemptSegment,
+} from "../shared/child-attempt.ts";
+import { createNativeFinalization } from "../shared/native-finalization.ts";
+import { compactForegroundResult } from "../../shared/utils.ts";
+import { resolveEffectiveThinking } from "../../shared/model-info.ts";
+import { resolveExecutionOutcome } from "../shared/acceptance.ts";
+
+function emptyUsage(): Usage {
+  return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
+}
+
+interface AttemptEnvironment {
+  readonly interruptSignal: AbortSignal;
+  readonly verificationSignal: AbortSignal;
+  readonly effectiveStructuredOutput?: ReturnType<typeof createStructuredOutputRuntime>;
+  readonly sessionEnabled: boolean;
+  readonly sessionDir?: string;
+}
+
+function nativeSegmentError(
+  segment: ReadonlyDeep<NativeAttemptSegment>,
+  agent: string,
+): string | undefined {
+  const state = segment.execution;
+  if (state?.error !== undefined) {
+    return state.error;
+  }
+  if (segment.event.submission.error !== undefined) {
+    return segment.event.submission.error;
+  }
+  const exitCode = state?.exitCode ?? 0;
+  if (exitCode === 0 || state?.interrupted === true) {
+    return;
+  }
+  return formatProcessExitFailure({ agent, exitCode, durationMs: segment.durationMs });
+}
+
+function nativeSegmentState(
+  segment: ReadonlyDeep<NativeAttemptSegment>,
+  error: string | undefined,
+) {
+  const {
+    exitCode = 0,
+    interrupted,
+    timedOut,
+    resourceLimitExceeded,
+    terminalFailure,
+  } = segment.execution ?? {};
+  const submissionError = segment.event.submission.error;
+  return {
+    exitCode: error !== undefined && error.length > 0 && exitCode === 0 ? 1 : exitCode,
+    interrupted,
+    timedOut,
+    resourceLimitExceeded,
+    terminalFailure:
+      (submissionError !== undefined && submissionError.length > 0) || terminalFailure,
+  };
+}
+
+export class RunnerAttempt {
+  nativeExecution: ReadonlyDeep<ChildAttemptResult> | undefined;
+  nativeSegments: readonly ReadonlyDeep<NativeAttemptSegment>[] = [];
+  toolCount = 0;
+  readonly toolCalls: ToolCallSummary[] = [];
+  private readonly eventsPath: string;
+  private readonly step: SubagentStep;
+  private readonly ctx: ReadonlyDeep<SingleStepContext>;
+  private readonly environment: ReadonlyDeep<AttemptEnvironment>;
+
+  constructor(
+    step: SubagentStep,
+    ctx: ReadonlyDeep<SingleStepContext>,
+    environment: ReadonlyDeep<AttemptEnvironment>,
+  ) {
+    this.step = step;
+    this.ctx = ctx;
+    this.environment = environment;
+    this.eventsPath = path.join(path.dirname(ctx.outputFile), "events.jsonl");
+  }
+
+  nativeAttempt(segment: ReadonlyDeep<NativeAttemptSegment>): StepAttempt {
+    const nativeExecution = this.nativeExecution;
+    if (nativeExecution === undefined) {
+      throw new Error("Native segment requires a finalized execution.");
+    }
+    const error = nativeSegmentError(segment, this.step.agent);
+    return {
+      ...nativeExecution,
+      ...nativeSegmentState(segment, error),
+      error,
+      messages: segment.messages,
+      usage: segment.usage,
+      durationMs: segment.durationMs,
+      finalOutput: segment.event.submission.output,
+      reportSubmission: segment.event.turn > 0 ? segment.event.submission : undefined,
+      resolvedOutput: segment.event.resolvedOutput,
+      finalization: undefined,
+    };
+  }
+
+  async run(
+    prompt: string,
+    model: string | undefined,
+    review?: ReadonlyDeep<AttemptReview>,
+  ): Promise<StepAttempt> {
+    const { step, ctx } = this;
+    const { verificationSignal, effectiveStructuredOutput } = this.environment;
+    if (verificationSignal.aborted) {
+      return this.abortedAttempt(model);
+    }
+    ctx.onAttemptStart?.({ model, thinking: resolveEffectiveThinking(model, step.thinking) });
+    const structuredRuntime = review ? review.reportRuntime : effectiveStructuredOutput;
+    const outputSnapshot = review
+      ? review.outputSnapshot
+      : captureSingleOutputSnapshot(step.outputPath);
+    if (structuredRuntime) {
+      try {
+        fs.rmSync(structuredRuntime.outputPath, { force: true });
+      } catch {
+        // readStructuredOutput reports unreadable or stale output after the attempt.
+      }
+    }
+    const nativeFinalization = this.nativeFinalization(model, review, structuredRuntime);
+    let built: ReturnType<typeof buildChildInvocation>;
+    try {
+      built = this.buildInvocation(prompt, model, {
+        review,
+        structuredRuntime,
+        nativeFinalization,
+      });
+    } catch (error) {
+      if (nativeFinalization) {
+        cleanupTempDir(path.dirname(nativeFinalization.reportRuntime.schemaPath));
+      }
+      const message =
+        error instanceof Error ? error.message : "Failed to prepare child invocation.";
+      return this.failedPreparation(model, message);
+    }
+    const runResult = await this.executeInvocation(built, {
+      model,
+      review,
+      structuredRuntime,
+      nativeFinalization,
+    });
+    const adopted = this.adoptNativeRun(runResult, nativeFinalization !== undefined);
+    return interpretAttemptOutput(step, adopted.run, {
+      model,
+      review,
+      structuredRuntime,
+      outputSnapshot,
+      initialSegment: adopted.initialSegment,
+      structuredResult: built.claudeCodeInvocation !== undefined,
+    });
+  }
+
+  private abortedAttempt(model: string | undefined): StepAttempt {
+    const outcome = resolveExecutionOutcome({
+      result: { exitCode: 1 },
+      signal: this.ctx.signal,
+      interruptSignal: this.environment.interruptSignal,
+    });
+    return {
+      stderr: "",
+      messages: [],
+      usage: emptyUsage(),
+      durationMs: 0,
+      observedCompletedMutation: false,
+      finalOutput: outcome.error ?? "Interrupted. Waiting for explicit next action.",
+      ...outcome,
+      exitCode: outcome.exitCode ?? 1,
+      model,
+      terminalFailure: true,
+      resolvedOutput: { fullOutput: "" },
+    };
+  }
+
+  private nativeFinalization(
+    model: string | undefined,
+    review: ReadonlyDeep<AttemptReview> | undefined,
+    runtime: ReadonlyDeep<AttemptEnvironment["effectiveStructuredOutput"]>,
+  ): ReturnType<typeof createNativeFinalization> | undefined {
+    const acceptance = this.step.effectiveAcceptance;
+    if (
+      this.ctx.nativeFinalization !== true ||
+      review !== undefined ||
+      isClaudeCodeModel(model) ||
+      acceptance?.explicit !== true
+    ) {
+      return;
+    }
+    return createNativeFinalization(acceptance, runtime, this.step.outputPath);
+  }
+
+  private adoptNativeRun(
+    run: ReadonlyDeep<ChildAttemptResult>,
+    enabled: boolean,
+  ): Readonly<{
+    run: ReadonlyDeep<ChildAttemptResult>;
+    initialSegment?: ReadonlyDeep<NativeAttemptSegment>;
+  }> {
+    const initialSegment = enabled ? run.finalization?.at(0) : undefined;
+    if (initialSegment === undefined) {
+      return { run };
+    }
+    this.nativeExecution = run;
+    this.nativeSegments = run.finalization?.slice(1) ?? [];
+    return { run: this.nativeAttempt(initialSegment), initialSegment };
+  }
+
+  private failedPreparation(model: string | undefined, message: string): StepAttempt {
+    return {
+      stderr: message,
+      exitCode: 1,
+      messages: [],
+      usage: emptyUsage(),
+      durationMs: 0,
+      observedCompletedMutation: false,
+      model,
+      error: message,
+      finalOutput: message,
+      terminalFailure: true,
+      resolvedOutput: { fullOutput: message },
+    };
+  }
+
+  private buildInvocation(
+    prompt: string,
+    model: string | undefined,
+    input: ReadonlyDeep<{
+      review?: AttemptReview;
+      structuredRuntime?: ReturnType<typeof createStructuredOutputRuntime>;
+      nativeFinalization?: ReturnType<typeof createNativeFinalization>;
+    }>,
+  ): ReturnType<typeof buildChildInvocation> {
+    const { step, ctx } = this;
+    const { review, structuredRuntime, nativeFinalization } = input;
+    const { sessionEnabled, sessionDir } = this.environment;
+    const sessionFile = review?.sessionFile ?? step.sessionFile;
+    return buildChildInvocation({
+      task: prompt,
+      model,
+      thinking: step.thinking,
+      sessionEnabled: review ? true : sessionEnabled,
+      sessionDir: review ? undefined : sessionDir,
+      sessionFile,
+      inheritProjectContext: step.inheritProjectContext,
+      inheritSkills: step.inheritSkills,
+      tools: step.tools,
+      allowSubagents: step.allowSubagents,
+      extensions: step.extensions,
+      systemPrompt: step.systemPrompt,
+      systemPromptMode: step.systemPromptMode,
+      mcpDirectTools: step.mcpDirectTools,
+      cwd: step.cwd ?? ctx.cwd,
+      intercomSessionName: ctx.childIntercomTarget,
+      orchestratorIntercomTarget: ctx.orchestratorIntercomTarget,
+      runId: ctx.id,
+      childAgentName: step.agent,
+      childIndex: ctx.flatIndex,
+      rootSessionId: ctx.rootSessionId,
+      parentEventSink: ctx.nestedRoute?.eventSink,
+      parentControlInbox: ctx.nestedRoute?.controlInbox,
+      parentRootRunId: ctx.nestedRoute?.rootRunId,
+      parentCapabilityToken: ctx.nestedRoute?.capabilityToken,
+      structuredOutput: structuredRuntime,
+      projectTrust: ctx.projectTrust,
+      nativeFinalization,
+    });
+  }
+
+  private async executeInvocation(
+    built: ReadonlyDeep<ReturnType<typeof buildChildInvocation>>,
+    input: ReadonlyDeep<{
+      model?: string;
+      review?: AttemptReview;
+      structuredRuntime?: ReturnType<typeof createStructuredOutputRuntime>;
+      nativeFinalization?: ReturnType<typeof createNativeFinalization>;
+    }>,
+  ): Promise<ChildAttemptResult> {
+    const { step, ctx, eventsPath } = this;
+    const { interruptSignal } = this.environment;
+    const { args, env, tempDir, claudeCodeInvocation } = built;
+    const { model, review, structuredRuntime, nativeFinalization } = input;
+    const sessionFile = review?.sessionFile ?? step.sessionFile;
+    try {
+      return await runPiStreaming(
+        {
+          args,
+          cwd: step.cwd ?? ctx.cwd,
+          env,
+          agent: step.agent,
+          model,
+          maxSubagentDepth: step.maxSubagentDepth,
+          maxExecutionTimeMs: step.maxExecutionTimeMs,
+          maxTokens: step.maxTokens,
+          interruptSignal,
+          signal: ctx.signal,
+          claudeCodeInvocation,
+          sessionFile,
+          structuredOutput: structuredRuntime,
+          reportRuntime: review?.reportRuntime,
+          nativeFinalization,
+          onEvent: (event, result, mutation) => {
+            if (event.type === "tool_execution_start") {
+              this.toolCount++;
+            }
+            if (event.type === "message_end" && event.message?.role === "assistant") {
+              this.toolCalls.push(
+                ...(compactForegroundResult({
+                  agent: step.agent,
+                  task: step.task,
+                  exitCode: 0,
+                  usage: result.usage,
+                  messages: [event.message],
+                }).toolCalls ?? []),
+              );
+            }
+            ctx.onChildEvent?.(event, mutation);
+          },
+        },
+        review ? `${ctx.outputFile}.finalization-${review.turn}.log` : ctx.outputFile,
+        { eventsPath, runId: ctx.id, stepIndex: ctx.flatIndex, agent: step.agent },
+      );
+    } finally {
+      cleanupTempDir(tempDir);
+      if (nativeFinalization) {
+        cleanupTempDir(path.dirname(nativeFinalization.reportRuntime.schemaPath));
+      }
+    }
+  }
+}