@fitchmultz/pi-subagents 0.44.7 → 0.45.0

package/dist/runs/background/runner-monitor.js

@@ -0,0 +1,309 @@
+import * as fs from "node:fs";
+import { RunnerChildObserver } from "./runner-child-observer.js";
+import { refreshRunnerGraph } from "./runner-graph.js";
+import { expandDynamicStatus, expandDynamicGraph, reindexChildTargets, } from "./runner-dynamic.js";
+import * as path from "node:path";
+import { writeAtomicJson } from "../../shared/atomic-json.js";
+import { appendJsonl } from "../../shared/artifacts.js";
+import { SUBAGENT_CHILD_ENV, SUBAGENT_FANOUT_CHILD_ENV } from "../shared/pi-args.js";
+import { DEFAULT_CONTROL_CONFIG, buildControlEvent, deriveActivityState, claimControlNotification, formatControlIntercomMessage, formatControlNoticeMessage, } from "../shared/subagent-control.js";
+import { nestedSummaryFromAsyncStatus, writeNestedEvent } from "../shared/nested-events.js";
+import { saveRunStatus, pendingSupervisorQuestion } from "../shared/supervisor-questions.js";
+/** Owns live status publication and attention notifications; execution owns cancellation. */
+export class RunnerMonitor {
+    statusWriteTimer;
+    currentActivityState;
+    emittedControlEventKeys = new Set();
+    childObserver;
+    controlConfig;
+    childSafeControls;
+    statusPath;
+    eventsPath;
+    asyncDir;
+    id;
+    childIntercomTargets;
+    config;
+    statusPayload;
+    overallStartTime;
+    constructor(config, statusPayload, overallStartTime) {
+        this.config = config;
+        this.statusPayload = statusPayload;
+        this.overallStartTime = overallStartTime;
+        this.id = this.config.id;
+        this.asyncDir = this.config.asyncDir;
+        this.statusPath = path.join(this.config.asyncDir, "status.json");
+        this.eventsPath = path.join(this.config.asyncDir, "events.jsonl");
+        this.controlConfig = this.config.controlConfig ?? DEFAULT_CONTROL_CONFIG;
+        this.childSafeControls =
+            this.config.nestedSelf !== undefined ||
+                (process.env[SUBAGENT_CHILD_ENV] === "1" && process.env[SUBAGENT_FANOUT_CHILD_ENV] === "1");
+        this.childObserver = new RunnerChildObserver(statusPayload, { id: this.id, controlConfig: this.controlConfig }, {
+            clearAttention: (index) => {
+                this.clearControlNotificationKeys(index);
+            },
+            notify: (event) => {
+                this.appendControlEvent(event);
+            },
+            scheduleWrite: () => {
+                this.scheduleStatusWrite();
+            },
+        });
+        this.childIntercomTargets = config.childIntercomTargets?.map((target) => typeof target === "string" ? target : undefined);
+    }
+    childTarget(index) {
+        return this.childIntercomTargets?.[index];
+    }
+    failDynamicStep(stepIndex, flatIndex, error) {
+        const now = Date.now();
+        this.statusPayload.state = "failed";
+        this.statusPayload.error = error;
+        this.statusPayload.currentStep = flatIndex;
+        const placeholder = this.statusPayload.steps.at(flatIndex);
+        if (placeholder) {
+            Object.assign(placeholder, {
+                status: "failed",
+                error,
+                startedAt: now,
+                endedAt: now,
+                durationMs: 0,
+                exitCode: 1,
+            });
+        }
+        this.statusPayload.lastUpdate = now;
+        this.markDynamicGraphGroup(stepIndex, "failed", error);
+        this.writeStatusPayload();
+    }
+    expandChildren(plan, step, position) {
+        const address = { ...position, runId: this.id };
+        const count = expandDynamicStatus(this.statusPayload, plan, step, address);
+        this.childIntercomTargets = reindexChildTargets(this.childIntercomTargets, this.statusPayload.steps, { ...address, count });
+        this.childObserver.expandChildren(position.flatIndex, count);
+        const graph = this.statusPayload.workflowGraph;
+        if (graph) {
+            this.statusPayload.workflowGraph = expandDynamicGraph(graph, plan, step, address);
+        }
+        this.writeStatusPayload();
+    }
+    emitNestedSelfEvent(type) {
+        if (!this.config.nestedRoute || !this.config.nestedSelf) {
+            return;
+        }
+        try {
+            writeNestedEvent(this.config.nestedRoute, {
+                type,
+                ts: Date.now(),
+                parentRunId: this.config.nestedSelf.parentRunId,
+                parentStepIndex: this.config.nestedSelf.parentStepIndex,
+                child: nestedSummaryFromAsyncStatus(this.statusPayload, this.asyncDir, {
+                    id: this.id,
+                    parentRunId: this.config.nestedSelf.parentRunId,
+                    parentStepIndex: this.config.nestedSelf.parentStepIndex,
+                    depth: this.config.nestedSelf.depth,
+                    path: this.config.nestedSelf.path?.map((entry) => Object.assign({}, entry)),
+                    mode: this.statusPayload.mode,
+                    ts: Date.now(),
+                }),
+            });
+        }
+        catch (error) {
+            console.error("Failed to emit nested async status event:", error);
+        }
+    }
+    refreshWorkflowGraph() {
+        const graph = this.statusPayload.workflowGraph ?? this.config.workflowGraph;
+        if (graph !== undefined) {
+            this.statusPayload.workflowGraph = refreshRunnerGraph(graph, this.statusPayload.steps, this.statusPayload.currentStep);
+        }
+    }
+    writeStatusPayload = () => {
+        if (this.statusWriteTimer) {
+            clearTimeout(this.statusWriteTimer);
+            this.statusWriteTimer = undefined;
+        }
+        this.refreshWorkflowGraph();
+        writeAtomicJson(this.statusPath, this.statusPayload);
+        if (this.config.runtimeVersion !== 2) {
+            saveRunStatus(this.id, this.statusPayload);
+        }
+        this.emitNestedSelfEvent(this.statusPayload.state === "running" || this.statusPayload.state === "queued"
+            ? "subagent.nested.updated"
+            : "subagent.nested.completed");
+    };
+    scheduleStatusWrite() {
+        if (this.statusWriteTimer) {
+            return;
+        }
+        this.statusWriteTimer = setTimeout(this.writeStatusPayload, 200);
+        this.statusWriteTimer.unref();
+    }
+    markDynamicGraphGroup(stepIndex, status, error, acceptance) {
+        const graph = this.statusPayload.workflowGraph;
+        if (graph === undefined) {
+            return;
+        }
+        this.statusPayload.workflowGraph = {
+            ...graph,
+            nodes: graph.nodes.map((node) => node.id === `step-${stepIndex}`
+                ? Object.assign({}, node, {
+                    status,
+                    error,
+                    acceptanceStatus: acceptance?.status ?? node.acceptanceStatus,
+                })
+                : node),
+        };
+    }
+    refreshUsageTotals() {
+        this.statusPayload.totalTokens = this.statusPayload.steps.reduce((total, step) => ({
+            input: total.input + (step.tokens?.input ?? 0),
+            output: total.output + (step.tokens?.output ?? 0),
+            total: total.total + (step.tokens?.total ?? 0),
+        }), { input: 0, output: 0, total: 0 });
+    }
+    stepOutputActivityAt(index) {
+        const step = this.statusPayload.steps.at(index);
+        let lastActivityAt = step?.lastActivityAt ?? step?.startedAt ?? this.overallStartTime;
+        const outputPath = path.join(this.asyncDir, `output-${index}.log`);
+        try {
+            lastActivityAt = Math.max(lastActivityAt, fs.statSync(outputPath).mtimeMs);
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) {
+                console.error(`Failed to inspect async output file '${outputPath}':`, error);
+            }
+        }
+        return lastActivityAt;
+    }
+    appendControlEvent(event) {
+        if (!this.controlConfig.enabled) {
+            return;
+        }
+        const childIntercomTarget = this.childIntercomTargets?.[event.index ?? this.statusPayload.currentStep];
+        const channels = this.controlConfig.notifyChannels;
+        if (channels.length === 0 ||
+            !claimControlNotification(this.controlConfig, event, this.emittedControlEventKeys, childIntercomTarget)) {
+            return;
+        }
+        appendJsonl(this.eventsPath, JSON.stringify({
+            type: "subagent.control",
+            event,
+            channels,
+            childIntercomTarget,
+            noticeText: formatControlNoticeMessage(event, childIntercomTarget, this.childSafeControls),
+            ...(this.config.controlIntercomTarget !== undefined &&
+                this.config.controlIntercomTarget.length > 0 &&
+                channels.includes("intercom")
+                ? {
+                    intercom: {
+                        to: this.config.controlIntercomTarget,
+                        message: formatControlIntercomMessage(event, childIntercomTarget, this.childSafeControls),
+                    },
+                }
+                : {}),
+        }));
+    }
+    updateStepModel(flatIndex, model, thinking, now = Date.now()) {
+        const step = this.statusPayload.steps.at(flatIndex);
+        if (!step) {
+            return;
+        }
+        step.model = model;
+        step.thinking = thinking;
+        step.modelStartedAt = now;
+        this.statusPayload.lastUpdate = now;
+        this.writeStatusPayload();
+    }
+    clearControlNotificationKeys(flatIndex) {
+        const childKey = this.childIntercomTargets?.[flatIndex] ?? `${this.config.id}:${flatIndex}`;
+        for (const key of this.emittedControlEventKeys) {
+            if (key.startsWith(`${childKey}:`)) {
+                this.emittedControlEventKeys.delete(key);
+            }
+        }
+    }
+    updateStepFromChildEvent(flatIndex, event, toolSnapshot) {
+        this.childObserver.updateStepFromChildEvent(flatIndex, event, toolSnapshot);
+    }
+    updateIdleAttention(index, lastActivityAt, now) {
+        const step = this.statusPayload.steps[index];
+        const idleState = deriveActivityState({
+            config: this.controlConfig,
+            startedAt: step.startedAt ?? this.overallStartTime,
+            lastActivityAt,
+            now,
+        });
+        const previous = step.activityState;
+        if (idleState !== "needs_attention") {
+            if (previous !== "needs_attention") {
+                return false;
+            }
+            step.activityState = undefined;
+            this.clearControlNotificationKeys(index);
+            return true;
+        }
+        step.activityState = "needs_attention";
+        if (previous === "needs_attention") {
+            return false;
+        }
+        this.appendControlEvent(buildControlEvent({
+            from: previous,
+            to: "needs_attention",
+            runId: this.id,
+            agent: step.agent,
+            index,
+            ts: now,
+            lastActivityAt,
+            currentTool: step.currentTool,
+            currentToolDurationMs: step.currentToolStartedAt === undefined
+                ? undefined
+                : Math.max(0, now - step.currentToolStartedAt),
+            supervisorQuestion: pendingSupervisorQuestion({
+                runId: this.id,
+                agent: step.agent,
+                index,
+                sessionFile: step.sessionFile,
+            }),
+        }));
+        return true;
+    }
+    syncRunAttention() {
+        const nextRunState = this.statusPayload.steps.some((step) => step.activityState === "needs_attention")
+            ? "needs_attention"
+            : undefined;
+        if (nextRunState === this.currentActivityState) {
+            return false;
+        }
+        this.currentActivityState = nextRunState;
+        this.statusPayload.activityState = nextRunState;
+        return true;
+    }
+    updateRunnerActivityState(now) {
+        if (!this.controlConfig.enabled) {
+            return false;
+        }
+        let changed = false;
+        let runLastActivityAt = this.statusPayload.lastActivityAt ?? this.overallStartTime;
+        for (let index = 0; index < this.statusPayload.steps.length; index++) {
+            const step = this.statusPayload.steps[index];
+            if (step.status !== "running") {
+                continue;
+            }
+            const lastActivityAt = this.stepOutputActivityAt(index);
+            runLastActivityAt = Math.max(runLastActivityAt, lastActivityAt);
+            if (step.lastActivityAt !== lastActivityAt) {
+                step.lastActivityAt = lastActivityAt;
+                changed = true;
+            }
+            changed = this.updateIdleAttention(index, lastActivityAt, now) || changed;
+        }
+        if (this.statusPayload.lastActivityAt !== runLastActivityAt) {
+            this.statusPayload.lastActivityAt = runLastActivityAt;
+            changed = true;
+        }
+        changed = this.syncRunAttention() || changed;
+        this.statusPayload.lastUpdate = now;
+        if (changed) {
+            this.writeStatusPayload();
+        }
+        return changed;
+    }
+}

package/dist/runs/background/runner-parallel.js

@@ -0,0 +1,204 @@
+import * as path from "node:path";
+import { inspect } from "node:util";
+import { appendJsonl } from "../../shared/artifacts.js";
+import { writeAtomicJson } from "../../shared/atomic-json.js";
+import { writeInitialProgressFile } from "../../shared/settings.js";
+import { completeWorkflowStep, runParallelTasks } from "../shared/workflow-policy.js";
+import { createWorktrees, cleanupWorktrees, findWorktreeTaskCwdConflict, formatWorktreeTaskCwdConflict, formatParallelWorktreeSummary, WorktreeCleanupError, } from "../shared/worktree.js";
+import { MAX_PARALLEL_CONCURRENCY } from "../shared/parallel-utils.js";
+/** Owns worktree setup/preservation/cleanup for a static parallel group. */
+export class RunnerParallelGroup {
+    config;
+    monitor;
+    lifecycle;
+    executor;
+    constructor(config, monitor, lifecycle, executor) {
+        this.config = config;
+        this.monitor = monitor;
+        this.lifecycle = lifecycle;
+        this.executor = executor;
+    }
+    async run(group, position, hooks) {
+        const setup = await this.setup(group, position);
+        if (!setup.ready) {
+            hooks.failed(setup.results, setup.warning);
+            return false;
+        }
+        const worktrees = setup.worktrees;
+        const cwd = group.cwd ?? this.config.cwd;
+        try {
+            if (group.worktree === true) {
+                this.ensureProgress(cwd, group);
+            }
+            this.startGroup(group, position);
+            const results = await this.executeTasks(group, position, worktrees);
+            this.monitor.refreshUsageTotals();
+            this.monitor.statusPayload.lastUpdate = Date.now();
+            this.monitor.writeStatusPayload();
+            const completion = completeWorkflowStep({
+                stepIndex: position.stepIndex,
+                stepCount: this.config.steps.length,
+                results,
+                previousOutput: position.previousOutput,
+                parallel: true,
+                outputNames: group.parallel.map((task) => task.outputName),
+            });
+            const summary = formatParallelWorktreeSummary(worktrees, path.join(this.config.asyncDir, "worktree-diffs", `step-${position.stepIndex}`), group.parallel.map((task) => task.agent));
+            // Workflow outputs and terminal group event are published before ordered worktree cleanup.
+            hooks.completed({ results, completion, summary });
+            return completion.advance;
+        }
+        catch (error) {
+            if (worktrees) {
+                worktrees.preserveOnCleanup = true;
+            }
+            throw error;
+        }
+        finally {
+            if (worktrees) {
+                cleanupWorktrees(worktrees);
+            }
+        }
+    }
+    async setup(group, position) {
+        if (group.worktree !== true) {
+            return { ready: true };
+        }
+        const cwd = group.cwd ?? this.config.cwd;
+        const conflict = findWorktreeTaskCwdConflict(group.parallel, cwd);
+        if (conflict) {
+            return {
+                ready: false,
+                results: this.failSetup(group, position, formatWorktreeTaskCwdConflict(conflict, cwd)),
+            };
+        }
+        try {
+            const hook = this.config.worktreeSetupHook;
+            const worktrees = await createWorktrees(cwd, `${this.config.id}-s${position.stepIndex}`, group.parallel.length, {
+                agents: group.parallel.map((task) => task.agent),
+                signal: AbortSignal.any([
+                    this.lifecycle.cancellation.signal,
+                    this.lifecycle.interruption.signal,
+                ]),
+                setupHook: hook === undefined || hook.length === 0
+                    ? undefined
+                    : { hookPath: hook, timeoutMs: this.config.worktreeSetupHookTimeoutMs },
+            });
+            return { ready: true, worktrees };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : inspect(error);
+            if (this.lifecycle.interrupted && !this.lifecycle.cancellation.signal.aborted) {
+                return this.interruptedSetup(group, position, error, message);
+            }
+            return { ready: false, results: this.failSetup(group, position, message) };
+        }
+    }
+    interruptedSetup(group, position, error, message) {
+        const warning = error instanceof WorktreeCleanupError ? message : undefined;
+        const results = group.parallel.map((task, index) => {
+            const stopped = this.executor.stop(task, position.flatIndex + index, "interrupted");
+            return {
+                ...stopped,
+                output: warning === undefined ? stopped.output : `${stopped.output}\n\n${warning}`,
+                success: false,
+            };
+        });
+        return { ready: false, results, warning };
+    }
+    failSetup(group, position, error) {
+        const failedAt = Date.now();
+        const status = this.monitor.statusPayload;
+        const results = group.parallel.map((task, taskIndex) => {
+            const step = status.steps[position.flatIndex + taskIndex];
+            Object.assign(step, {
+                status: "failed",
+                startedAt: failedAt,
+                endedAt: failedAt,
+                durationMs: 0,
+                exitCode: 1,
+            });
+            return {
+                agent: task.agent,
+                output: error,
+                success: false,
+                exitCode: 1,
+                sessionFile: task.sessionFile,
+            };
+        });
+        status.currentStep = position.flatIndex;
+        status.lastUpdate = failedAt;
+        status.outputFile = path.join(this.config.asyncDir, `output-${position.flatIndex}.log`);
+        writeAtomicJson(path.join(this.config.asyncDir, "status.json"), status);
+        this.append({
+            type: "subagent.parallel.completed",
+            ts: failedAt,
+            runId: this.config.id,
+            stepIndex: position.stepIndex,
+            success: false,
+        });
+        return results;
+    }
+    startGroup(group, position) {
+        const startedAt = Date.now();
+        const status = this.monitor.statusPayload;
+        for (const [index] of group.parallel.entries()) {
+            Object.assign(status.steps[position.flatIndex + index], {
+                status: "pending",
+                startedAt: undefined,
+                endedAt: undefined,
+                durationMs: undefined,
+                lastActivityAt: undefined,
+                activityState: undefined,
+                error: undefined,
+            });
+        }
+        status.currentStep = position.flatIndex;
+        status.activityState = undefined;
+        status.lastActivityAt = startedAt;
+        status.lastUpdate = startedAt;
+        status.outputFile = path.join(this.config.asyncDir, `output-${position.flatIndex}.log`);
+        writeAtomicJson(path.join(this.config.asyncDir, "status.json"), status);
+        this.append({
+            type: "subagent.parallel.started",
+            ts: startedAt,
+            runId: this.config.id,
+            stepIndex: position.stepIndex,
+            agents: group.parallel.map((task) => task.agent),
+            count: group.parallel.length,
+        });
+    }
+    executeTasks(group, position, worktrees) {
+        return runParallelTasks({
+            tasks: group.parallel,
+            concurrency: group.concurrency ?? MAX_PARALLEL_CONCURRENCY,
+            failFast: group.failFast,
+            signal: this.lifecycle.cancellation.signal,
+            interruptSignal: this.lifecycle.interruption.signal,
+            stoppedTask: (task, index, reason) => this.executor.stop(task, position.flatIndex + index, reason),
+            runTask: (task, index, interruptSignal) => this.executor.run({
+                task: worktrees ? { ...task, cwd: undefined } : task,
+                taskCwd: worktrees ? worktrees.worktrees[index].agentCwd : (group.cwd ?? this.config.cwd),
+                worktreePath: worktrees?.worktrees[index]?.path,
+                flatIndex: position.flatIndex + index,
+                interruptSignal,
+                sessionDir: this.config.sessionDir === undefined || this.config.sessionDir.length === 0
+                    ? undefined
+                    : path.join(this.config.sessionDir, `parallel-${index}`),
+                flatStepCount: position.flatStepCount,
+                resetTiming: true,
+                trackSession: true,
+                notifyCompletionGuard: true,
+            }),
+        });
+    }
+    ensureProgress(cwd, group) {
+        const progressPath = path.join(cwd, "progress.md");
+        if (group.parallel.some((task) => task.task.includes(`Update progress at: ${progressPath}`))) {
+            writeInitialProgressFile(cwd);
+        }
+    }
+    append(event) {
+        appendJsonl(path.join(this.config.asyncDir, "events.jsonl"), JSON.stringify(event));
+    }
+}

package/dist/runs/background/runner-prepare-step.js

@@ -0,0 +1,86 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getArtifactPaths } from "../../shared/artifacts.js";
+import { createStructuredOutputRuntime, } from "../shared/structured-output.js";
+import { formatAcceptancePrompt } from "../shared/acceptance.js";
+import { saveQuestionContract } from "../shared/supervisor-questions.js";
+function saveStepContract(step, ctx) {
+    saveQuestionContract(ctx.id, ctx.flatIndex, {
+        task: step.task,
+        label: step.label,
+        effectiveAcceptance: step.effectiveAcceptance,
+        output: step.outputPath ?? false,
+        outputMode: step.outputMode,
+        outputSchema: step.structuredOutputSchema ?? step.structuredOutput?.schema,
+        launch: step.launch
+            ? {
+                ...step.launch,
+                cwd: step.cwd ?? ctx.cwd,
+                output: step.outputPath ?? false,
+                outputMode: step.outputMode ?? "inline",
+                outputSchema: step.structuredOutputSchema ?? step.structuredOutput?.schema,
+                model: step.model,
+                thinking: step.thinking,
+            }
+            : undefined,
+        sessionFile: step.sessionFile,
+    });
+}
+function prepareArtifacts(step, task, ctx) {
+    const directory = ctx.artifactsDir;
+    if (directory === undefined || directory.length === 0) {
+        return;
+    }
+    const index = ctx.flatStepCount > 1 ? ctx.flatIndex : undefined;
+    const paths = getArtifactPaths(directory, ctx.id, step.agent, index);
+    fs.mkdirSync(directory, { recursive: true });
+    fs.writeFileSync(paths.inputPath, `# Task for ${step.agent}\n\n${task}`, "utf-8");
+    return paths;
+}
+function continuationStep(input, ctx) {
+    if (ctx.nativeFinalization !== true || input.effectiveAcceptance?.explicit !== true) {
+        return input;
+    }
+    if (input.sessionFile !== undefined && input.sessionFile.length > 0) {
+        return input;
+    }
+    return {
+        ...input,
+        sessionFile: path.join(path.dirname(ctx.outputFile), `session-${ctx.flatIndex}.jsonl`),
+    };
+}
+function structuredRuntime(step, outputFile) {
+    if (step.structuredOutput) {
+        return step.structuredOutput;
+    }
+    if (step.structuredOutputSchema === undefined) {
+        return;
+    }
+    return createStructuredOutputRuntime(step.structuredOutputSchema, path.join(path.dirname(outputFile), "structured-output"));
+}
+/** Establishes continuation persistence, acceptance prompt and owned interrupt signal before execution. */
+export function prepareRunnerStep(input, ctx) {
+    const step = continuationStep(input, ctx);
+    saveStepContract(step, ctx);
+    const interrupt = new AbortController();
+    ctx.registerInterrupt?.(() => {
+        interrupt.abort();
+    });
+    const interruptSignal = AbortSignal.any([ctx.interruptSignal, interrupt.signal].filter((signal) => signal !== undefined));
+    const verificationSignal = AbortSignal.any([ctx.signal, interruptSignal].filter((signal) => signal !== undefined));
+    const runtime = structuredRuntime(step, ctx.outputFile);
+    const prompt = step.effectiveAcceptance ? formatAcceptancePrompt(step.effectiveAcceptance) : "";
+    const task = prompt.length > 0 ? `${step.task}\n${prompt}` : step.task;
+    const artifactPaths = prepareArtifacts(step, task, ctx);
+    const hasSession = step.sessionFile !== undefined && step.sessionFile.length > 0;
+    return {
+        step,
+        task,
+        artifactPaths,
+        interruptSignal,
+        verificationSignal,
+        structuredRuntime: runtime,
+        sessionEnabled: hasSession || ctx.sessionEnabled,
+        sessionDir: hasSession ? undefined : ctx.sessionDir,
+    };
+}