@fitchmultz/pi-subagents 0.49.1 → 0.50.0

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

@@ -1,311 +0,0 @@
-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;
-        }
-        // Step completion, interruption and expansion can change activity without a tool-end event.
-        this.childObserver.syncTopLevelCurrentTool();
-        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

@@ -1,203 +0,0 @@
-import * as path from "node:path";
-import { inspect } from "node:util";
-import { appendJsonl } from "../../shared/artifacts.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`);
-        this.monitor.writeStatusPayload();
-        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`);
-        this.monitor.writeStatusPayload();
-        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

@@ -1,86 +0,0 @@
-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,
-    };
-}