parallel-codex-tui 0.3.1 → 0.4.0

package/dist/orchestrator/orchestrator.js

@@ -75,10 +75,17 @@ export class Orchestrator {
     }
     async handleRequest(input) {
         throwIfCancelled(input.signal);
-        const routed = await this.routeRequest(input.request, input.cwd, input.signal, "initial", input.onRouteStart, input.onRouteFallback, input.onRouteProgress);
-        const roleSelection = input.roleSelection ?? await this.roleConfiguration.selectionForRequest();
-        const route = routeWithRoleSelection(routed, roleSelection);
-        input.onRoute?.(route);
+        let roleSelection;
+        let route;
+        if (input.route) {
+            roleSelection = input.roleSelection ?? await this.roleConfiguration.selectionForRequest();
+            route = routeWithRoleSelection(input.route, roleSelection);
+        }
+        else {
+            const routed = await this.routeInitialRequest(input);
+            roleSelection = routed.roleSelection;
+            route = routed.route;
+        }
         throwIfCancelled(input.signal);
         const workers = [];
         const executionInput = { ...input, roleSelection };
@@ -115,6 +122,21 @@ export class Orchestrator {
         await this.roleConfiguration.writeTurnSelection(turn.dir, roleSelectionWithEngines(route, roleSelection));
         return this.withTaskRunLease(task, () => this.runInitialTask(executionInput, task, route, turn, workers));
     }
+    async routeInitialRequest(input) {
+        throwIfCancelled(input.signal);
+        const routed = await this.routeRequest(input.request, input.cwd, input.signal, "initial", input.onRouteStart, input.onRouteFallback, input.onRouteProgress);
+        const roleSelection = input.roleSelection ?? await this.roleConfiguration.selectionForRequest();
+        const route = routeWithRoleSelection(routed, roleSelection);
+        input.onRoute?.(route);
+        throwIfCancelled(input.signal);
+        return {
+            mode: route.mode,
+            taskId: null,
+            reason: route.reason,
+            route,
+            roleSelection
+        };
+    }
     async handleTaskTurn(input) {
         throwIfCancelled(input.signal);
         const task = this.sessions.taskFromId(input.taskId);

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/protocol.js

@@ -0,0 +1,177 @@
+import { z } from "zod";
+import { EngineNameSchema, RouteDecisionSchema, TaskIdSchema, WorkerModelNameSchema, WorkerRoleSchema, WorkerStatusSchema } from "../domain/schemas.js";
+const RoleExecutionTargetSchema = z.object({
+    engine: EngineNameSchema,
+    model: WorkerModelNameSchema
+}).strict();
+const RoleExecutionSelectionSchema = z.object({
+    main: RoleExecutionTargetSchema,
+    judge: RoleExecutionTargetSchema,
+    actor: RoleExecutionTargetSchema,
+    critic: RoleExecutionTargetSchema
+}).strict();
+const SupervisorRequestBaseSchema = z.object({
+    version: z.literal(1),
+    run_id: z.string().min(1),
+    app_root: z.string().min(1),
+    workspace_root: z.string().min(1),
+    data_dir: z.string().min(1),
+    created_at: z.string().datetime()
+});
+export const SupervisorRunRequestSchema = z.discriminatedUnion("kind", [
+    SupervisorRequestBaseSchema.extend({
+        kind: z.literal("handle-request"),
+        request: z.string().min(1),
+        cwd: z.string().min(1),
+        route: RouteDecisionSchema.optional(),
+        role_selection: RoleExecutionSelectionSchema.optional()
+    }).strict(),
+    SupervisorRequestBaseSchema.extend({
+        kind: z.literal("handle-task-turn"),
+        request: z.string().min(1),
+        cwd: z.string().min(1),
+        task_id: TaskIdSchema,
+        route: RouteDecisionSchema.optional(),
+        role_selection: RoleExecutionSelectionSchema.optional()
+    }).strict(),
+    SupervisorRequestBaseSchema.extend({
+        kind: z.literal("answer-task-question"),
+        request: z.string().min(1),
+        cwd: z.string().min(1),
+        task_id: TaskIdSchema,
+        route: RouteDecisionSchema.optional(),
+        role_selection: RoleExecutionSelectionSchema.optional()
+    }).strict(),
+    SupervisorRequestBaseSchema.extend({
+        kind: z.literal("retry-task"),
+        cwd: z.string().min(1),
+        task_id: TaskIdSchema
+    }).strict(),
+    SupervisorRequestBaseSchema.extend({
+        kind: z.literal("resume-feature"),
+        cwd: z.string().min(1),
+        task_id: TaskIdSchema,
+        feature_id: z.string().min(1)
+    }).strict()
+]);
+export const SupervisorRunStatusSchema = z.enum([
+    "queued",
+    "running",
+    "cancelling",
+    "completed",
+    "failed",
+    "cancelled"
+]);
+const WorkerLogRefSchema = z.object({
+    id: z.string().min(1),
+    featureId: z.string().min(1).optional(),
+    role: WorkerRoleSchema,
+    engine: EngineNameSchema,
+    label: z.string(),
+    logPath: z.string().min(1),
+    statusPath: z.string().min(1),
+    runtimeStatus: WorkerStatusSchema.optional()
+}).strict();
+export const SupervisorRunResultSchema = z.object({
+    mode: z.enum(["simple", "complex"]),
+    taskId: TaskIdSchema.nullable(),
+    summary: z.string(),
+    workers: z.array(WorkerLogRefSchema)
+}).strict();
+export const SupervisorRunStateSchema = z.object({
+    version: z.literal(1),
+    run_id: z.string().min(1),
+    kind: z.enum([
+        "handle-request",
+        "handle-task-turn",
+        "answer-task-question",
+        "retry-task",
+        "resume-feature"
+    ]),
+    status: SupervisorRunStatusSchema,
+    app_root: z.string().min(1),
+    workspace_root: z.string().min(1),
+    created_at: z.string().datetime(),
+    updated_at: z.string().datetime(),
+    started_at: z.string().datetime().optional(),
+    finished_at: z.string().datetime().optional(),
+    task_id: TaskIdSchema.nullable().optional(),
+    pid: z.number().int().positive().optional(),
+    process_start_token: z.string().min(1).optional(),
+    result: SupervisorRunResultSchema.optional(),
+    error: z.string().optional()
+}).strict();
+export const SupervisorEventTypeSchema = z.enum([
+    "route-start",
+    "route-progress",
+    "route",
+    "status",
+    "worker"
+]);
+export const SupervisorRunEventSchema = z.object({
+    version: z.literal(1),
+    sequence: z.number().int().nonnegative(),
+    at: z.string().datetime(),
+    type: SupervisorEventTypeSchema,
+    payload: z.unknown()
+}).strict();
+export const SupervisorCommandSchema = z.discriminatedUnion("type", [
+    z.object({
+        version: z.literal(1),
+        id: z.string().min(1),
+        at: z.string().datetime(),
+        type: z.literal("cancel-run")
+    }).strict(),
+    z.object({
+        version: z.literal(1),
+        id: z.string().min(1),
+        at: z.string().datetime(),
+        type: z.literal("cancel-feature"),
+        task_id: TaskIdSchema,
+        feature_id: z.string().min(1)
+    }).strict(),
+    z.object({
+        version: z.literal(1),
+        id: z.string().min(1),
+        at: z.string().datetime(),
+        type: z.literal("pause-feature"),
+        task_id: TaskIdSchema,
+        feature_id: z.string().min(1)
+    }).strict()
+]);
+export const SupervisorControllerSchema = z.object({
+    version: z.literal(1),
+    controller_id: z.string().min(1),
+    pid: z.number().int().positive(),
+    acquired_at: z.string().datetime(),
+    process_start_token: z.string().min(1).optional()
+}).strict();
+export function supervisorEventPayload(event) {
+    switch (event.type) {
+        case "route":
+            return RouteDecisionSchema.parse(event.payload);
+        case "worker":
+            return WorkerLogRefSchema.parse(event.payload);
+        case "route-progress":
+            return z.object({ phase: z.enum([
+                    "dispatching",
+                    "starting",
+                    "retrying",
+                    "waiting-output",
+                    "receiving-stderr",
+                    "receiving-response",
+                    "parsing",
+                    "stopping"
+                ]) }).parse(event.payload);
+        case "route-start":
+            return event.payload;
+        case "status":
+            return event.payload;
+    }
+}
+export function asSupervisorRunResult(value) {
+    return SupervisorRunResultSchema.parse(value);
+}
+export function roleSelectionFromRequest(request) {
+    return "role_selection" in request ? request.role_selection : undefined;
+}