parallel-codex-tui 0.3.2 → 0.4.1

package/dist/supervisor/client.js

@@ -0,0 +1,442 @@
+import { randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { closeSync, openSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { asSupervisorRunResult, supervisorEventPayload } from "./protocol.js";
+import { acknowledgeSupervisorRun, appendSupervisorCommand, claimSupervisorController, createSupervisorRun, createSupervisorRunId, listSupervisorRuns, readSupervisorEvents, readSupervisorRunState, supervisorRunIsAcknowledged, supervisorRunIsTerminal, supervisorRunProcessIsActive, writeSupervisorRunState } from "./store.js";
+const RUN_POLL_MS = 100;
+const QUEUED_START_GRACE_MS = 3000;
+export class SupervisorDetachedError extends Error {
+    constructor(message = "Background run detached") {
+        super(message);
+        this.name = "SupervisorDetachedError";
+    }
+}
+export function isSupervisorDetachedError(error) {
+    return error instanceof Error && error.name === "SupervisorDetachedError";
+}
+export class SupervisorOrchestrator {
+    options;
+    persistsRunResults = true;
+    launch;
+    now;
+    recoverableRun = null;
+    currentRun = null;
+    settledRun = null;
+    detaching = false;
+    backgroundRunListeners = new Set();
+    constructor(options) {
+        this.options = options;
+        this.launch = options.launch ?? launchSupervisorProcess;
+        this.now = options.now ?? (() => new Date());
+    }
+    static async open(options) {
+        const client = new SupervisorOrchestrator(options);
+        client.recoverableRun = await client.findRecoverableRun();
+        return client;
+    }
+    async handleRequest(input) {
+        const routed = await this.options.delegate.routeInitialRequest(input);
+        return this.startRun({
+            kind: "handle-request",
+            request: input.request,
+            cwd: input.cwd,
+            route: routed.route,
+            role_selection: routed.roleSelection
+        }, input);
+    }
+    async handleTaskTurn(input) {
+        return this.startRun({
+            kind: "handle-task-turn",
+            request: input.request,
+            cwd: input.cwd,
+            task_id: input.taskId,
+            ...(input.route ? { route: input.route } : {}),
+            ...(input.roleSelection ? { role_selection: input.roleSelection } : {})
+        }, input);
+    }
+    async answerTaskQuestion(input) {
+        return this.startRun({
+            kind: "answer-task-question",
+            request: input.request,
+            cwd: input.cwd,
+            task_id: input.taskId,
+            ...(input.route ? { route: input.route } : {}),
+            ...(input.roleSelection ? { role_selection: input.roleSelection } : {})
+        }, input);
+    }
+    async retryTask(input) {
+        return this.startRun({
+            kind: "retry-task",
+            cwd: input.cwd,
+            task_id: input.taskId
+        }, input);
+    }
+    async resumeFeature(input) {
+        return this.startRun({
+            kind: "resume-feature",
+            cwd: input.cwd,
+            task_id: input.taskId,
+            feature_id: input.featureId
+        }, input);
+    }
+    async restorePendingRun(input) {
+        this.detaching = input.signal?.aborted ? this.detaching : false;
+        const pending = this.recoverableRun ?? await this.findRecoverableRun();
+        this.recoverableRun = null;
+        if (!pending) {
+            return null;
+        }
+        const controller = await claimSupervisorController(pending.files);
+        return this.watchRun({
+            files: pending.files,
+            controller,
+            detached: this.detaching,
+            cancelSent: false
+        }, input);
+    }
+    detachBackgroundRuns() {
+        this.detaching = true;
+        const current = this.currentRun;
+        if (!current) {
+            return;
+        }
+        current.detached = true;
+        void current.controller?.release();
+        current.controller = null;
+        this.notifyBackgroundRunState();
+    }
+    backgroundRunAttached() {
+        return this.currentRun !== null;
+    }
+    backgroundRunControllable() {
+        return this.currentRun?.controller !== null && this.currentRun?.controller !== undefined;
+    }
+    subscribeBackgroundRunState(listener) {
+        this.backgroundRunListeners.add(listener);
+        return () => this.backgroundRunListeners.delete(listener);
+    }
+    async acknowledgeBackgroundRun() {
+        if (!this.settledRun) {
+            return;
+        }
+        const files = this.settledRun;
+        this.settledRun = null;
+        await acknowledgeSupervisorRun(files);
+    }
+    async cancelFeature(taskId, featureId) {
+        if (!this.currentRun) {
+            return this.options.delegate.cancelFeature(taskId, featureId);
+        }
+        if (!this.currentRun.controller) {
+            return { requested: false, featureId };
+        }
+        await appendSupervisorCommand(this.currentRun.files, {
+            version: 1,
+            id: randomUUID(),
+            at: this.now().toISOString(),
+            type: "cancel-feature",
+            task_id: taskId,
+            feature_id: featureId
+        });
+        return { requested: true, featureId };
+    }
+    async pauseFeature(taskId, featureId) {
+        if (!this.currentRun) {
+            return this.options.delegate.pauseFeature(taskId, featureId);
+        }
+        if (!this.currentRun.controller) {
+            return { requested: false, featureId };
+        }
+        await appendSupervisorCommand(this.currentRun.files, {
+            version: 1,
+            id: randomUUID(),
+            at: this.now().toISOString(),
+            type: "pause-feature",
+            task_id: taskId,
+            feature_id: featureId
+        });
+        return { requested: true, featureId };
+    }
+    routeTaskFollowUp(input) {
+        return this.options.delegate.routeTaskFollowUp(input);
+    }
+    canRetryTask(taskId) {
+        return this.options.delegate.canRetryTask(taskId);
+    }
+    listTaskWorkers(taskId) {
+        return this.options.delegate.listTaskWorkers(taskId);
+    }
+    reassignFeature(input) {
+        return this.options.delegate.reassignFeature(input);
+    }
+    roleConfigurationSnapshot(taskId) {
+        return this.options.delegate.roleConfigurationSnapshot(taskId);
+    }
+    updateRoleConfiguration(input) {
+        return this.options.delegate.updateRoleConfiguration(input);
+    }
+    clearRoleConfiguration(scope, taskId) {
+        return this.options.delegate.clearRoleConfiguration(scope, taskId);
+    }
+    validateRoleConfiguration(roles) {
+        return this.options.delegate.validateRoleConfiguration(roles);
+    }
+    async startRun(input, callbacks) {
+        this.detaching = callbacks.signal?.aborted ? this.detaching : false;
+        if (this.currentRun) {
+            throw new Error("A Supervisor run is already attached in this TUI.");
+        }
+        const active = (await this.reconcileRuns()).filter(({ state }) => !supervisorRunIsTerminal(state));
+        if (active.length > 0) {
+            throw new Error("A background run is already active in this workspace. Reopen the TUI to attach to it.");
+        }
+        const createdAt = this.now().toISOString();
+        const request = {
+            ...input,
+            version: 1,
+            run_id: createSupervisorRunId(this.now()),
+            app_root: this.options.appRoot,
+            workspace_root: this.options.workspaceRoot,
+            data_dir: this.options.dataDir,
+            created_at: createdAt
+        };
+        const files = await createSupervisorRun(this.options.workspaceRoot, this.options.dataDir, request);
+        const controller = await claimSupervisorController(files);
+        if (!controller) {
+            throw new Error("The new Supervisor run was claimed by another TUI before it could start.");
+        }
+        const watched = {
+            files,
+            controller,
+            detached: this.detaching,
+            cancelSent: false
+        };
+        this.currentRun = watched;
+        this.notifyBackgroundRunState();
+        try {
+            await this.launch(files, request);
+        }
+        catch (error) {
+            if (this.currentRun === watched) {
+                this.currentRun = null;
+                this.notifyBackgroundRunState();
+            }
+            await controller.release();
+            const message = error instanceof Error ? error.message : String(error);
+            const failedAt = this.now().toISOString();
+            const state = await readSupervisorRunState(files);
+            await writeSupervisorRunState(files, {
+                ...state,
+                status: "failed",
+                updated_at: failedAt,
+                finished_at: failedAt,
+                error: message
+            });
+            await this.options.sessions.appendChatMessage({ from: "system", text: message });
+            this.settledRun = files;
+            throw error;
+        }
+        return this.watchRun(watched, callbacks);
+    }
+    async watchRun(watched, callbacks) {
+        this.currentRun = watched;
+        this.notifyBackgroundRunState();
+        let nextEventSequence = 0;
+        try {
+            while (true) {
+                if (watched.detached) {
+                    throw new SupervisorDetachedError();
+                }
+                if (!watched.controller) {
+                    watched.controller = await claimSupervisorController(watched.files);
+                    if (watched.controller) {
+                        this.notifyBackgroundRunState();
+                    }
+                }
+                const events = await readSupervisorEvents(watched.files);
+                for (const event of events) {
+                    if (event.sequence < nextEventSequence) {
+                        continue;
+                    }
+                    nextEventSequence = event.sequence + 1;
+                    dispatchSupervisorEvent(event, callbacks);
+                }
+                const state = await readSupervisorRunState(watched.files);
+                if (supervisorRunIsTerminal(state)) {
+                    this.settledRun = watched.files;
+                    if (state.status === "completed" && state.result) {
+                        return asSupervisorRunResult(state.result);
+                    }
+                    const error = new Error(state.error || `Supervisor run ${state.status}`);
+                    if (state.status === "cancelled") {
+                        error.name = "AbortError";
+                    }
+                    throw error;
+                }
+                if (watched.controller && !(await supervisorRunProcessIsActive(state))) {
+                    const ageMs = this.now().getTime() - Date.parse(state.created_at);
+                    if (state.status !== "queued" || ageMs >= QUEUED_START_GRACE_MS) {
+                        const failedAt = this.now().toISOString();
+                        const summary = `Supervisor exited unexpectedly while ${state.kind} was running.`;
+                        await writeSupervisorRunState(watched.files, {
+                            ...state,
+                            status: "failed",
+                            updated_at: failedAt,
+                            finished_at: failedAt,
+                            error: summary
+                        });
+                        await this.options.sessions.appendChatMessage({
+                            from: "system",
+                            text: summary,
+                            taskId: state.task_id ?? undefined
+                        });
+                        continue;
+                    }
+                }
+                if (callbacks.signal?.aborted && !watched.cancelSent) {
+                    if (!watched.controller) {
+                        throw new SupervisorDetachedError("Observer detached; the background run is still active");
+                    }
+                    watched.cancelSent = true;
+                    await appendSupervisorCommand(watched.files, {
+                        version: 1,
+                        id: randomUUID(),
+                        at: this.now().toISOString(),
+                        type: "cancel-run"
+                    });
+                }
+                await delay(RUN_POLL_MS);
+            }
+        }
+        finally {
+            if (this.currentRun === watched) {
+                this.currentRun = null;
+            }
+            await watched.controller?.release();
+            watched.controller = null;
+            this.notifyBackgroundRunState();
+        }
+    }
+    notifyBackgroundRunState() {
+        for (const listener of this.backgroundRunListeners) {
+            listener();
+        }
+    }
+    async findRecoverableRun() {
+        const runs = await this.reconcileRuns();
+        const active = runs.filter(({ state }) => !supervisorRunIsTerminal(state));
+        if (active.length > 0) {
+            return active.at(-1) ?? null;
+        }
+        const unacknowledged = [];
+        for (const run of runs) {
+            if (supervisorRunIsTerminal(run.state) && !(await supervisorRunIsAcknowledged(run.files))) {
+                unacknowledged.push(run);
+            }
+        }
+        return unacknowledged.at(-1) ?? null;
+    }
+    async reconcileRuns() {
+        const runs = await listSupervisorRuns(this.options.workspaceRoot, this.options.dataDir);
+        for (const run of runs) {
+            if (supervisorRunIsTerminal(run.state) || await supervisorRunProcessIsActive(run.state)) {
+                continue;
+            }
+            const ageMs = this.now().getTime() - Date.parse(run.state.created_at);
+            if (run.state.status === "queued" && ageMs < QUEUED_START_GRACE_MS) {
+                continue;
+            }
+            const failedAt = this.now().toISOString();
+            const summary = `Supervisor exited unexpectedly while ${run.state.kind} was running.`;
+            run.state = {
+                ...run.state,
+                status: "failed",
+                updated_at: failedAt,
+                finished_at: failedAt,
+                error: summary
+            };
+            await writeSupervisorRunState(run.files, run.state);
+            await this.options.sessions.appendChatMessage({
+                from: "system",
+                text: summary,
+                taskId: run.state.task_id ?? undefined
+            });
+        }
+        return runs;
+    }
+}
+function dispatchSupervisorEvent(event, callbacks) {
+    const payload = supervisorEventPayload(event);
+    switch (event.type) {
+        case "route-start":
+            callbacks.onRouteStart?.(payload);
+            break;
+        case "route-progress":
+            callbacks.onRouteProgress?.(payload);
+            break;
+        case "route":
+            callbacks.onRoute?.(payload);
+            break;
+        case "status":
+            callbacks.onStatus?.(payload);
+            break;
+        case "worker":
+            callbacks.onWorker?.(payload);
+            break;
+    }
+}
+async function launchSupervisorProcess(files, request) {
+    const entrypoint = process.argv[1] ? resolve(process.argv[1]) : "";
+    if (!entrypoint) {
+        throw new Error("Cannot locate the parallel-codex-tui CLI entrypoint for Supervisor launch.");
+    }
+    const errorLog = openSync(join(files.dir, "supervisor.log"), "a");
+    const child = spawn(process.execPath, [...process.execArgv, entrypoint], {
+        cwd: process.cwd(),
+        detached: true,
+        env: {
+            ...process.env,
+            PCT_SUPERVISOR_RUN_DIR: files.dir
+        },
+        stdio: ["ignore", "ignore", errorLog]
+    });
+    try {
+        await new Promise((resolve, reject) => {
+            child.once("spawn", resolve);
+            child.once("error", reject);
+        });
+    }
+    finally {
+        closeSync(errorLog);
+    }
+    let exitCode;
+    const onExit = (code) => {
+        exitCode = code;
+    };
+    child.once("exit", onExit);
+    const deadline = Date.now() + 5000;
+    while (Date.now() < deadline) {
+        const state = await readSupervisorRunState(files);
+        if (state.status !== "queued") {
+            child.off("exit", onExit);
+            child.unref();
+            return;
+        }
+        if (exitCode !== undefined) {
+            throw new Error(`Supervisor process exited before startup (code ${exitCode ?? "signal"}).`);
+        }
+        await delay(25);
+    }
+    child.off("exit", onExit);
+    try {
+        child.kill("SIGTERM");
+    }
+    catch {
+        // The startup failure below remains the useful error when the child already exited.
+    }
+    throw new Error("Supervisor process did not publish startup state within 5s.");
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/supervisor/operations.js

@@ -0,0 +1,116 @@
+import { randomUUID } from "node:crypto";
+import { appendSupervisorCommand, listSupervisorRuns, readSupervisorController, supervisorControllerIsActive, supervisorRunIsAcknowledged, supervisorRunIsTerminal, supervisorRunProcessIsActive } from "./store.js";
+const QUEUED_START_GRACE_MS = 5000;
+export async function inspectSupervisorRuns(workspaceRoot, dataDir, now = new Date()) {
+    const records = await listSupervisorRuns(workspaceRoot, dataDir);
+    const runs = await Promise.all(records.map((record) => inspectSupervisorRun(record, now)));
+    return {
+        version: 1,
+        workspace_root: workspaceRoot,
+        generated_at: now.toISOString(),
+        runs: runs.reverse()
+    };
+}
+export async function requestSupervisorRunCancellation(workspaceRoot, dataDir, runId, now = new Date()) {
+    const records = await listSupervisorRuns(workspaceRoot, dataDir);
+    const inspected = await Promise.all(records.map(async (record) => ({
+        record,
+        view: await inspectSupervisorRun(record, now)
+    })));
+    const newestFirst = inspected.reverse();
+    const selected = runId
+        ? newestFirst.find(({ view }) => view.run_id === runId)
+        : newestFirst.find(({ view }) => !isTerminalStatus(view.status) && view.control !== "stale");
+    if (!selected) {
+        if (runId) {
+            throw new Error(`Supervisor run not found: ${runId}`);
+        }
+        const stale = newestFirst.find(({ view }) => !isTerminalStatus(view.status));
+        if (stale) {
+            throw new Error(`Supervisor run is not active: ${stale.view.run_id} (${stale.view.status})`);
+        }
+        throw new Error(`No active Supervisor run in workspace ${workspaceRoot}`);
+    }
+    if (isTerminalStatus(selected.view.status)) {
+        throw new Error(`Supervisor run is already ${selected.view.status}: ${selected.view.run_id}`);
+    }
+    if (selected.view.control === "stale") {
+        throw new Error(`Supervisor run is not active: ${selected.view.run_id} (${selected.view.status})`);
+    }
+    const requestedAt = now.toISOString();
+    const commandId = randomUUID();
+    await appendSupervisorCommand(selected.record.files, {
+        version: 1,
+        id: commandId,
+        at: requestedAt,
+        type: "cancel-run"
+    });
+    return {
+        version: 1,
+        command_id: commandId,
+        requested_at: requestedAt,
+        run: selected.view
+    };
+}
+export function formatSupervisorRuns(report) {
+    if (report.runs.length === 0) {
+        return `No Supervisor runs in ${report.workspace_root}.`;
+    }
+    const lines = [`Supervisor runs · ${report.workspace_root}`];
+    for (const run of report.runs) {
+        const acknowledgement = run.acknowledged ? "seen" : "unread";
+        lines.push(`${run.status} · ${run.control} · ${acknowledgement} · ${run.run_id}`);
+        lines.push([
+            run.task_id ? `task ${run.task_id}` : `kind ${run.kind}`,
+            `updated ${run.updated_at}`,
+            ...(run.pid ? [`pid ${run.pid}`] : [])
+        ].join(" · "));
+    }
+    return lines.join("\n");
+}
+export function formatSupervisorCancellation(result) {
+    const target = result.run.task_id ? `task ${result.run.task_id}` : result.run.kind;
+    return `Cancellation requested · ${result.run.run_id} · ${target}`;
+}
+async function inspectSupervisorRun(record, now) {
+    const controller = await readSupervisorController(record.files);
+    const [processActive, controllerActive, acknowledged] = await Promise.all([
+        supervisorRunProcessIsActive(record.state),
+        controller ? supervisorControllerIsActive(controller) : Promise.resolve(false),
+        supervisorRunIsAcknowledged(record.files)
+    ]);
+    return {
+        run_id: record.state.run_id,
+        kind: record.state.kind,
+        status: record.state.status,
+        control: controlState(record, processActive, controllerActive, now),
+        task_id: record.state.task_id ?? null,
+        created_at: record.state.created_at,
+        updated_at: record.state.updated_at,
+        finished_at: record.state.finished_at ?? null,
+        pid: record.state.pid ?? null,
+        process_active: processActive,
+        controller_pid: controller?.pid ?? null,
+        controller_active: controllerActive,
+        acknowledged
+    };
+}
+function controlState(record, processActive, controllerActive, now) {
+    if (supervisorRunIsTerminal(record.state)) {
+        return "settled";
+    }
+    if (controllerActive) {
+        return "controlled";
+    }
+    if (processActive) {
+        return "detached";
+    }
+    if (record.state.status === "queued"
+        && now.getTime() - Date.parse(record.state.updated_at) <= QUEUED_START_GRACE_MS) {
+        return "starting";
+    }
+    return "stale";
+}
+function isTerminalStatus(status) {
+    return status === "completed" || status === "failed" || status === "cancelled";
+}