@fitchmultz/pi-subagents 0.49.0 → 0.50.0

package/dist/runs/background/async-control.js

@@ -1,171 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { randomUUID } from "node:crypto";
-import { writeAtomicJson } from "../../shared/atomic-json.js";
-import { readStatus } from "../../shared/utils.js";
-import { readQuestionContract, readRunJson } from "../shared/supervisor-questions.js";
-import { checkPidLiveness } from "./stale-run-reconciler.js";
-import { isDurableRun } from "./async-result-file.js";
-import { readChildProcessIdentity, trySignalChildTree, } from "../../shared/post-exit-stdio-guard.js";
-import { errorCode, isRecord } from "./async-value.js";
-function validExtension(options) {
-    return (typeof options.extendMs === "number" &&
-        Number.isSafeInteger(options.extendMs) &&
-        options.extendMs > 0 &&
-        options.index === undefined);
-}
-export function writeAsyncControlRequest(asyncDir, runId, action, options = {}) {
-    if (action === "extend" && !validExtension(options)) {
-        throw new Error("extendMs must be a positive integer.");
-    }
-    const requestId = randomUUID();
-    const separateFiles = readStatus(asyncDir)?.controlRequestFiles === true ||
-        isDurableRun(readRunJson(path.join(asyncDir, "launch.json")));
-    const file = separateFiles
-        ? path.join(asyncDir, "control-requests", `${requestId}.json`)
-        : path.join(asyncDir, "control-request.json");
-    writeAtomicJson(file, { requestId, runId, action, ...options, createdAt: Date.now() });
-}
-function orphanedChild(runId, index) {
-    const contract = readQuestionContract(runId, index, undefined, { readConfiguration: false });
-    const pid = contract?.pid;
-    if (pid === undefined || !Number.isSafeInteger(pid) || pid <= 0) {
-        throw new Error(`Cannot verify process ownership for child ${index}.`);
-    }
-    if (checkPidLiveness(pid) === "dead") {
-        return undefined;
-    }
-    const identity = contract?.processIdentity;
-    if (identity === undefined ||
-        identity.length === 0 ||
-        readChildProcessIdentity(pid) !== identity) {
-        throw new Error(`Cannot verify process ownership for child ${index}. No stop was sent.`);
-    }
-    return { pid, identity };
-}
-function stopOrphan(childIdentity) {
-    const { pid, identity } = childIdentity;
-    const child = { pid, kill: (signal) => process.kill(pid, signal) };
-    if (!trySignalChildTree(child, "SIGTERM")) {
-        throw new Error(`Could not signal orphaned child process ${pid}. Exit is unconfirmed.`);
-    }
-    // Match normal Stop escalation, including descendants surviving their group leader.
-    setTimeout(() => {
-        if (checkPidLiveness(pid) === "dead") {
-            try {
-                process.kill(-pid, "SIGKILL");
-            }
-            catch {
-                // The process group may already have exited after SIGTERM.
-            }
-        }
-        else if (readChildProcessIdentity(pid) === identity) {
-            trySignalChildTree(child, "SIGKILL");
-        }
-    }, 3000).unref();
-}
-function deadRunner(status, runId) {
-    return (status?.runId === runId &&
-        status.state === "running" &&
-        status.pid !== undefined &&
-        status.pid !== 0 &&
-        checkPidLiveness(status.pid) === "dead");
-}
-function validInterruptIndex(status, index) {
-    return (index === undefined ||
-        (Number.isSafeInteger(index) && index >= 0 && status?.steps?.at(index)?.status === "running"));
-}
-export function writeAsyncInterruptRequest(asyncDir, runId, index) {
-    const status = readStatus(asyncDir);
-    if (!deadRunner(status, runId)) {
-        writeAsyncControlRequest(asyncDir, runId, "interrupt", { index });
-        return;
-    }
-    if (!validInterruptIndex(status, index)) {
-        throw new Error(`No running child at index ${index ?? "unknown"}. No siblings were stopped.`);
-    }
-    // Validate every target before signaling any: stale PIDs must never stop unrelated work.
-    const children = (status?.steps ?? []).flatMap((step, childIndex) => {
-        if (step.status !== "running" || (index !== undefined && index !== childIndex)) {
-            return [];
-        }
-        const child = orphanedChild(runId, childIndex);
-        return child === undefined ? [] : [child];
-    });
-    children.forEach(stopOrphan);
-}
-function isControlIndex(value) {
-    return (value === undefined || (typeof value === "number" && Number.isSafeInteger(value) && value >= 0));
-}
-function isControlAction(value) {
-    return value === "interrupt" || value === "cancel" || value === "extend";
-}
-function parseControlRequest(value, runId) {
-    if (!isRecord(value) ||
-        value.runId !== runId ||
-        typeof value.requestId !== "string" ||
-        value.requestId.length === 0) {
-        return undefined;
-    }
-    const action = value.action;
-    if (!isControlAction(action)) {
-        return undefined;
-    }
-    const index = value.index;
-    if (!isControlIndex(index)) {
-        return undefined;
-    }
-    const extendMs = typeof value.extendMs === "number" ? value.extendMs : undefined;
-    if (action === "extend" && !validExtension({ index, extendMs })) {
-        return undefined;
-    }
-    return { requestId: value.requestId, runId, action, index, extendMs };
-}
-function claimRequest(file) {
-    const claimed = `${file}.${randomUUID()}.reading`;
-    try {
-        // Claim before reading, so a legacy writer's replacement remains for the next poll.
-        fs.renameSync(file, claimed);
-        return claimed;
-    }
-    catch (error) {
-        if (errorCode(error) !== "ENOENT") {
-            console.error(`Failed to claim async control request '${file}':`, error);
-        }
-        return undefined;
-    }
-}
-export function readAsyncControlRequests(asyncDir, runId) {
-    const directory = path.join(asyncDir, "control-requests");
-    const files = fs.existsSync(directory)
-        ? fs
-            .readdirSync(directory)
-            .filter((file) => file.endsWith(".json"))
-            .map((file) => path.join(directory, file))
-        : [];
-    files.push(path.join(asyncDir, "control-request.json"));
-    const requests = [];
-    for (const file of files) {
-        const claimed = claimRequest(file);
-        if (claimed === undefined) {
-            continue;
-        }
-        try {
-            if (fs.statSync(claimed).size > 64 * 1024) {
-                throw new Error("control request exceeds 64 KiB");
-            }
-            const value = JSON.parse(fs.readFileSync(claimed, "utf-8"));
-            const request = parseControlRequest(value, runId);
-            if (request) {
-                requests.push(request);
-            }
-        }
-        catch (error) {
-            console.error(`Failed to read async control request '${file}':`, error);
-        }
-        finally {
-            fs.rmSync(claimed, { force: true });
-        }
-    }
-    return requests;
-}

package/dist/runs/background/async-execution.js

@@ -1,179 +0,0 @@
-import { createChainDir, isParallelStep, isDynamicParallelStep, resolveChainTemplates, } from "../../shared/settings.js";
-import { resolveChildCwd } from "../../shared/utils.js";
-import { buildWorkflowGraphSnapshot } from "../shared/workflow-graph.js";
-import { ChainOutputValidationError, validateChainOutputBindings, } from "../shared/chain-outputs.js";
-import { AsyncChainPlanner } from "./async-chain-plan.js";
-import { planAsyncSingle } from "./async-single-plan.js";
-import { AsyncStartValidationError, UnavailableSubagentSkillError, } from "./async-plan.js";
-import { prepareAsyncOwner, createRunnerLaunch, launchAsyncRun, launchErrorMessage, formatAsyncStartError, } from "./async-launch.js";
-export { formatAsyncStartedMessage } from "./async-launch.js";
-function firstTask(step) {
-    if (isParallelStep(step)) {
-        return step.parallel.at(0)?.task;
-    }
-    if (isDynamicParallelStep(step)) {
-        return step.parallel.task;
-    }
-    return step.task;
-}
-function stepAgents(step) {
-    if (isParallelStep(step)) {
-        return step.parallel.map((task) => task.agent);
-    }
-    if (isDynamicParallelStep(step)) {
-        return [step.parallel.agent];
-    }
-    return [step.agent];
-}
-function chainDescription(step) {
-    if (isParallelStep(step)) {
-        return `[${step.parallel.map((task) => task.agent).join("+")}]`;
-    }
-    if (isDynamicParallelStep(step)) {
-        return `expand:${step.parallel.agent}`;
-    }
-    return step.agent;
-}
-function validateChain(params) {
-    if (params.chain.length === 0) {
-        throw new AsyncStartValidationError("An async chain requires at least one step.");
-    }
-    validateChainOutputBindings(params.chain, { maxItems: params.dynamicFanoutMaxItems });
-    for (const step of params.chain) {
-        for (const name of stepAgents(step)) {
-            if (!params.agents.some((agent) => agent.name === name)) {
-                throw new AsyncStartValidationError(`Unknown agent: ${name}`);
-            }
-        }
-    }
-}
-function childTargets(steps, resolver) {
-    if (resolver === undefined) {
-        return;
-    }
-    let index = 0;
-    return steps.flatMap((step) => {
-        if (!("parallel" in step)) {
-            return [resolver(step.agent, index++)];
-        }
-        if ("expand" in step) {
-            return [resolver(step.parallel.agent, index++)];
-        }
-        return step.parallel.map((task) => resolver(task.agent, index++));
-    });
-}
-function chainOverview(id, mode, chain) {
-    const first = chain.at(0);
-    const groups = [];
-    const agents = [];
-    for (const [stepIndex, step] of chain.entries()) {
-        const names = stepAgents(step);
-        if (isParallelStep(step) || isDynamicParallelStep(step)) {
-            groups.push({ start: agents.length, count: names.length, stepIndex });
-        }
-        agents.push(...names);
-    }
-    const description = chain.map(chainDescription);
-    return {
-        headline: `Async ${mode}: ${description.join(" -> ")} [${id}]`,
-        agent: first ? stepAgents(first).at(0) : undefined,
-        agents,
-        task: first ? firstTask(first)?.slice(0, 50) : undefined,
-        chain: description,
-        chainStepCount: chain.length,
-        parallelGroups: groups,
-    };
-}
-function isAsyncStartFailure(error) {
-    return (error instanceof ChainOutputValidationError ||
-        error instanceof AsyncStartValidationError ||
-        error instanceof UnavailableSubagentSkillError);
-}
-/** Validates and plans the workflow before transferring ownership to a detached runner. */
-export function executeAsyncChain(id, params) {
-    const mode = params.resultMode ?? "chain";
-    try {
-        validateChain(params);
-    }
-    catch (error) {
-        if (isAsyncStartFailure(error)) {
-            return formatAsyncStartError(mode, error.message);
-        }
-        throw error;
-    }
-    const cwd = resolveChildCwd(params.ctx.cwd, params.cwd);
-    const chainDir = mode === "chain" ? createChainDir(id, params.chainDir, cwd) : cwd;
-    const originalTask = params.task ?? firstTask(params.chain[0]);
-    let owner;
-    try {
-        owner = prepareAsyncOwner(id);
-    }
-    catch (error) {
-        return formatAsyncStartError(mode, `Failed to create async run directory: ${launchErrorMessage(error)}`);
-    }
-    const graph = buildWorkflowGraphSnapshot({ runId: id, mode, steps: params.chain });
-    let steps;
-    try {
-        steps = new AsyncChainPlanner(id, params, {
-            runnerCwd: cwd,
-            chainDir,
-            asyncDir: owner.asyncDir,
-            originalTask,
-            resultMode: mode,
-            templates: resolveChainTemplates(params.chain),
-        }).build();
-    }
-    catch (error) {
-        if (isAsyncStartFailure(error)) {
-            return formatAsyncStartError(mode, error.message);
-        }
-        throw error;
-    }
-    const config = createRunnerLaunch(params, owner, {
-        steps,
-        cwd,
-        resultMode: mode,
-        chainDir,
-        originalTask,
-        childIntercomTargets: childTargets(steps, params.childIntercomTarget),
-        dynamicFanoutMaxItems: params.dynamicFanoutMaxItems,
-        workflowGraph: graph,
-    });
-    return launchAsyncRun(params.ctx.pi, owner, config, {
-        ...chainOverview(id, mode, params.chain),
-        nestedRoute: params.nestedRoute,
-    });
-}
-/** Plans one child's output/skill contract and preserves the handed-off pid on notification failure. */
-export function executeAsyncSingle(id, params) {
-    const cwd = resolveChildCwd(params.ctx.cwd, params.cwd);
-    let owner;
-    try {
-        owner = prepareAsyncOwner(id);
-    }
-    catch (error) {
-        return formatAsyncStartError("single", `Failed to create async run directory: ${launchErrorMessage(error)}`);
-    }
-    let step;
-    try {
-        step = planAsyncSingle(id, params, { cwd, asyncDir: owner.asyncDir });
-    }
-    catch (error) {
-        if (isAsyncStartFailure(error)) {
-            return formatAsyncStartError("single", error.message);
-        }
-        throw error;
-    }
-    const config = createRunnerLaunch(params, owner, {
-        steps: [step],
-        cwd,
-        resultMode: "single",
-        childIntercomTargets: childTargets([step], params.childIntercomTarget),
-    });
-    return launchAsyncRun(params.ctx.pi, owner, config, {
-        headline: `Async: ${params.agent} [${id}]`,
-        agent: params.agent,
-        task: (params.task ?? "").slice(0, 50),
-        nestedRoute: params.nestedRoute,
-    });
-}

package/dist/runs/background/async-job-admission.js

@@ -1,40 +0,0 @@
-import { normalizeParallelGroups } from "./parallel-groups.js";
-import { hasText } from "./async-value.js";
-function startedAgents(info) {
-    if ((info.agents?.length ?? 0) > 0) {
-        return info.agents;
-    }
-    if ((info.chain?.length ?? 0) > 0) {
-        return info.chain;
-    }
-    return hasText(info.agent) ? [info.agent] : undefined;
-}
-function parallelProjection(info) {
-    const groups = normalizeParallelGroups(info.parallelGroups, Number.MAX_SAFE_INTEGER, info.chainStepCount ?? Number.MAX_SAFE_INTEGER);
-    const count = groups.find((group) => group.start === 0)?.count;
-    const raw = startedAgents(info);
-    const active = count !== undefined && count > 0;
-    const agents = active ? raw?.slice(0, count) : raw;
-    return {
-        agents,
-        parallelGroups: groups,
-        stepsTotal: count ?? agents?.length,
-        activeParallelGroup: active,
-    };
-}
-/** Admission records own no resources until the tracker inserts them and starts polling. */
-export function startedJob(id, info, asyncDir, now) {
-    return {
-        asyncId: id,
-        asyncDir,
-        status: "queued",
-        pid: info.pid,
-        sessionId: info.sessionId,
-        mode: info.mode ?? (info.chain ? "chain" : "single"),
-        chainStepCount: info.chainStepCount,
-        nestedRoute: info.nestedRoute,
-        startedAt: now,
-        updatedAt: now,
-        ...parallelProjection(info),
-    };
-}

package/dist/runs/background/async-job-projection.js

@@ -1,169 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { scanJournal } from "../../shared/journal-reader.js";
-import { formatControlNoticeMessage, isObsoleteIdleNotice } from "../shared/subagent-control.js";
-import { RESULTS_DIR, SUBAGENT_CONTROL_EVENT, SUBAGENT_CONTROL_INTERCOM_EVENT, } from "../../shared/types.js";
-import { attachRootChildrenToSteps } from "../shared/nested-events.js";
-import { reconcileNestedAsyncDescendants } from "./stale-run-reconciler.js";
-import { errorCode, isRecord } from "./async-value.js";
-import { parseControlEvent } from "./run-schemas.js";
-function controlRecord(value) {
-    if (!isRecord(value) ||
-        value.type !== "subagent.control" ||
-        !isRecord(value.event) ||
-        value.event.type !== "needs_attention" ||
-        !Array.isArray(value.channels)) {
-        return undefined;
-    }
-    const event = parseControlEvent(value.event);
-    return {
-        event,
-        channels: value.channels,
-        childIntercomTarget: typeof value.childIntercomTarget === "string" ? value.childIntercomTarget : undefined,
-        noticeText: typeof value.noticeText === "string" ? value.noticeText : undefined,
-        intercom: isRecord(value.intercom) ? value.intercom : undefined,
-    };
-}
-/** Owns the mutable widget projection and journal cursor of one async job. */
-export class AsyncJobProjection {
-    job;
-    events;
-    constructor(job, events) {
-        this.job = job;
-        this.events = events;
-    }
-    emitControl(value) {
-        const record = controlRecord(value);
-        if (!record ||
-            (this.job.controlEventSince !== undefined && record.event.ts < this.job.controlEventSince)) {
-            return;
-        }
-        const payload = {
-            event: record.event,
-            source: "async",
-            asyncDir: this.job.asyncDir,
-            childIntercomTarget: record.childIntercomTarget,
-            noticeText: record.noticeText ?? formatControlNoticeMessage(record.event, record.childIntercomTarget),
-        };
-        if (isObsoleteIdleNotice(payload)) {
-            return;
-        }
-        if (record.channels.includes("event")) {
-            this.events.emit(SUBAGENT_CONTROL_EVENT, payload);
-        }
-        this.emitIntercom(record, payload);
-    }
-    emitIntercom(record, payload) {
-        const intercom = record.intercom;
-        if (record.channels.includes("intercom") &&
-            typeof intercom?.to === "string" &&
-            intercom.to.length > 0 &&
-            typeof intercom.message === "string" &&
-            intercom.message.length > 0) {
-            this.events.emit(SUBAGENT_CONTROL_INTERCOM_EVENT, {
-                ...payload,
-                to: intercom.to,
-                message: intercom.message,
-            });
-        }
-    }
-    emitNewControlEvents() {
-        const eventsPath = path.join(this.job.asyncDir, "events.jsonl");
-        try {
-            const stat = fs.statSync(eventsPath);
-            const identity = `${stat.dev}:${stat.ino}`;
-            if (this.job.controlEventIdentity !== identity ||
-                stat.size < (this.job.controlEventCursor ?? 0)) {
-                this.job.controlEventCursor = 0;
-            }
-            this.job.controlEventIdentity = identity;
-            if (stat.size === (this.job.controlEventCursor ?? 0)) {
-                return;
-            }
-            this.job.controlEventCursor = scanJournal(eventsPath, (parts) => parts.length === 0 ||
-                ["type", "event", "channels", "childIntercomTarget", "noticeText", "intercom"].includes(typeof parts[0] === "string" ? parts[0] : ""), ({ value, end }) => {
-                this.emitControl(value);
-                this.job.controlEventCursor = end;
-            }, { policy: "live", start: this.job.controlEventCursor ?? 0 });
-        }
-        catch (error) {
-            if (errorCode(error) !== "ENOENT") {
-                console.error(`Failed to read async control events for '${this.job.asyncDir}':`, error);
-            }
-        }
-    }
-    refreshNested() {
-        if (!this.job.nestedRoute) {
-            return;
-        }
-        this.job.nestedChildren = reconcileNestedAsyncDescendants(this.job.nestedRoute, {
-            resultsDir: RESULTS_DIR,
-        });
-        attachRootChildrenToSteps(this.job.asyncId, this.job.steps, this.job.nestedChildren);
-    }
-    activity(summary) {
-        this.job.sessionId = summary.sessionId ?? this.job.sessionId;
-        this.job.activityState = summary.activityState;
-        this.job.lastActivityAt = summary.lastActivityAt ?? this.job.lastActivityAt;
-        this.job.currentTool = summary.currentTool;
-        this.job.currentToolStartedAt = summary.currentToolStartedAt;
-        this.job.currentPath = summary.currentPath;
-        this.job.turnCount = summary.turnCount ?? this.job.turnCount;
-        this.job.toolCount = summary.toolCount ?? this.job.toolCount;
-        this.job.totalTokens = summary.totalTokens ?? this.job.totalTokens;
-        this.job.sessionFile = summary.sessionFile ?? this.job.sessionFile;
-    }
-    progress(summary) {
-        if (summary.steps.length === 0) {
-            return;
-        }
-        const groups = summary.parallelGroups ?? [];
-        this.job.parallelGroups = groups.length > 0 ? groups : this.job.parallelGroups;
-        const current = summary.currentStep;
-        const active = current === undefined
-            ? undefined
-            : groups.find((group) => current >= group.start && current < group.start + group.count);
-        const steps = active
-            ? summary.steps.slice(active.start, active.start + active.count)
-            : summary.steps;
-        this.job.activeParallelGroup = active !== undefined;
-        this.job.agents = steps.map((step) => step.agent);
-        this.job.steps = steps.map((step) => ({ ...step }));
-        attachRootChildrenToSteps(this.job.asyncId, this.job.steps, this.job.nestedChildren);
-        this.job.stepsTotal = steps.length;
-        this.job.runningSteps = steps.filter((step) => step.status === "running").length;
-        this.job.completedSteps =
-            summary.state === "complete"
-                ? steps.length
-                : steps.filter((step) => step.status === "complete" || step.status === "completed").length;
-    }
-    markRunning() {
-        if (this.job.status === "queued") {
-            this.job.status = "running";
-            this.job.updatedAt = Date.now();
-        }
-    }
-    markFailed() {
-        this.job.status = "failed";
-        this.job.updatedAt = Date.now();
-    }
-    complete(status, asyncDir) {
-        this.job.status = status;
-        this.job.updatedAt = Date.now();
-        if (asyncDir !== undefined && asyncDir.length > 0) {
-            this.job.asyncDir = asyncDir;
-        }
-    }
-    applySummary(summary) {
-        this.job.status = summary.state;
-        this.activity(summary);
-        this.job.mode = summary.mode;
-        this.job.currentStep = summary.currentStep ?? this.job.currentStep;
-        this.job.chainStepCount = summary.chainStepCount ?? this.job.chainStepCount;
-        this.job.startedAt = summary.startedAt;
-        if (summary.lastUpdate !== undefined) {
-            this.job.updatedAt = summary.lastUpdate;
-        }
-        this.progress(summary);
-    }
-}