@fitchmultz/pi-subagents 0.44.7 → 0.46.0

package/dist/runs/background/runner-attempt-output.js

@@ -0,0 +1,155 @@
+import { detectSubagentError } from "../../shared/utils.js";
+import { hasCompletedMutationToolCall, resolveCompletionPolicy, } from "../shared/completion-guard.js";
+import { readStructuredOutput } from "../shared/structured-output.js";
+import { resolveSingleOutput } from "../shared/single-output.js";
+import { readFinalizationReport, resolveFinalizationOutput, stripAcceptanceReport, } from "../shared/acceptance.js";
+export function formatProcessExitFailure(input) {
+    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, run) {
+    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) {
+    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, run, review) {
+    return (review === undefined &&
+        resolveCompletionPolicy({
+            completionGuardEnabled: step.completionGuard === true,
+            usesAcceptanceContract: step.effectiveAcceptance?.explicit === true,
+        }) === "mutation-guard" &&
+        !run.observedCompletedMutation &&
+        !hasCompletedMutationToolCall(run.messages));
+}
+function resolveAttemptOutput(step, fullOutput, input) {
+    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, run, context) {
+    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, run, input) {
+    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, report, review) {
+    const finalOutput = report?.output ?? run.finalOutput;
+    const fullOutput = review === undefined
+        ? stripAcceptanceReport(finalOutput)
+        : resolveFinalizationOutput(finalOutput, review.previousOutput);
+    return { finalOutput, fullOutput };
+}
+function hiddenAttemptFailure(run, report) {
+    return successfulProcess(run) && (report === undefined || report.output.length === 0)
+        ? detectSubagentError(run.messages)
+        : undefined;
+}
+function analyzeAttempt(run, context) {
+    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) {
+    return run.exitCode === 0 && (run.error === undefined || run.error.length === 0);
+}
+function terminalFailure(guard, structuredError, hiddenError, saveError) {
+    return (guard ||
+        (structuredError !== undefined && structuredError.length > 0) ||
+        hiddenError?.hasError === true ||
+        (saveError !== undefined && saveError.length > 0));
+}
+function outputState(step, resolvedOutput, error, exitCode) {
+    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, input) {
+    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/dist/runs/background/runner-attempt.js

@@ -0,0 +1,263 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { interpretAttemptOutput, formatProcessExitFailure, } from "./runner-attempt-output.js";
+import { runPiStreaming } from "./runner-streaming.js";
+import { captureSingleOutputSnapshot } from "../shared/single-output.js";
+import { cleanupTempDir } from "../shared/pi-args.js";
+import { isClaudeCodeModel } from "../shared/claude-code.js";
+import { buildChildInvocation, } from "../shared/child-attempt.js";
+import { createNativeFinalization } from "../shared/native-finalization.js";
+import { compactForegroundResult } from "../../shared/utils.js";
+import { resolveEffectiveThinking } from "../../shared/model-info.js";
+import { resolveExecutionOutcome } from "../shared/acceptance.js";
+function emptyUsage() {
+    return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
+}
+function nativeSegmentError(segment, agent) {
+    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, error) {
+    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;
+    nativeSegments = [];
+    toolCount = 0;
+    toolCalls = [];
+    eventsPath;
+    step;
+    ctx;
+    environment;
+    constructor(step, ctx, environment) {
+        this.step = step;
+        this.ctx = ctx;
+        this.environment = environment;
+        this.eventsPath = path.join(path.dirname(ctx.outputFile), "events.jsonl");
+    }
+    nativeAttempt(segment) {
+        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, model, review) {
+        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;
+        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,
+        });
+    }
+    abortedAttempt(model) {
+        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: "" },
+        };
+    }
+    nativeFinalization(model, review, runtime) {
+        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);
+    }
+    adoptNativeRun(run, enabled) {
+        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 };
+    }
+    failedPreparation(model, message) {
+        return {
+            stderr: message,
+            exitCode: 1,
+            messages: [],
+            usage: emptyUsage(),
+            durationMs: 0,
+            observedCompletedMutation: false,
+            model,
+            error: message,
+            finalOutput: message,
+            terminalFailure: true,
+            resolvedOutput: { fullOutput: message },
+        };
+    }
+    buildInvocation(prompt, model, input) {
+        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,
+        });
+    }
+    async executeInvocation(built, input) {
+        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));
+            }
+        }
+    }
+}

package/dist/runs/background/runner-child-executor.js

@@ -0,0 +1,166 @@
+import * as path from "node:path";
+import { appendJsonl } from "../../shared/artifacts.js";
+import { buildControlEvent } from "../shared/subagent-control.js";
+import { flattenSteps } from "../shared/parallel-utils.js";
+import { markStepPaused, startRunnerStep, finishRunnerStep, runnerResultEvent, tokenUsageFromAttempts, } from "./runner-status.js";
+import { runSingleStep } from "./runner-step.js";
+/** Executes one scheduled child; shared workflow policy still owns scheduling and admission. */
+export class RunnerChildExecutor {
+    latestSessionFile;
+    config;
+    monitor;
+    lifecycle;
+    renderTask;
+    sessionEnabled;
+    constructor(config, monitor, lifecycle, renderTask) {
+        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) {
+        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 };
+    }
+    stepContext(input) {
+        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);
+            },
+        };
+    }
+    finish(input, result, startedAt) {
+        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, index, reason) {
+        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,
+        };
+    }
+    append(event) {
+        appendJsonl(path.join(this.config.asyncDir, "events.jsonl"), JSON.stringify(event));
+    }
+}