@fitchmultz/pi-subagents 0.44.7 → 0.46.0

package/dist/pi-intercom/ui/topic-view.js

@@ -0,0 +1,88 @@
+import { Container, ScrollView, Text, matchesKey, } from "@earendil-works/pi-tui";
+import { actionHints } from "../../tui/action-hints.js";
+function scrollDelta(data, viewport) {
+    if (matchesKey(data, "pageUp")) {
+        return -viewport;
+    }
+    if (matchesKey(data, "pageDown")) {
+        return viewport;
+    }
+    if (matchesKey(data, "up")) {
+        return -1;
+    }
+    if (matchesKey(data, "down")) {
+        return 1;
+    }
+    return 0;
+}
+export function createTopicView(options) {
+    const { tui, done, inspect, attach } = options;
+    const text = new Text("", 0, 0);
+    const scroll = new ScrollView(text, { follow: "none", scrollbar: "hidden" });
+    const render = () => {
+        tui.requestRender();
+    };
+    attach(render);
+    let closed = false;
+    const act = (delta) => {
+        if (closed) {
+            return;
+        }
+        if (delta === undefined) {
+            done();
+        }
+        else {
+            scroll.scrollBy(delta);
+        }
+        tui.requestRender();
+    };
+    const view = new Container();
+    view.addChild({
+        invalidate() {
+            scroll.invalidate();
+        },
+        render: (width) => {
+            text.setText(inspect());
+            const lines = scroll.render(width);
+            const height = Math.max(1, tui.terminal.rows - 2);
+            scroll.updateLayout(lines.length, height, render);
+            return lines.slice(scroll.scrollTop, scroll.scrollTop + height);
+        },
+    });
+    view.addChild(actionHints([
+        { text: "↑", run: () => act(-1) },
+        "/",
+        { text: "↓", run: () => act(1) },
+        " ",
+        { text: "PgUp", run: () => act(-scroll.viewportHeight) },
+        "/",
+        { text: "PgDn Read", run: () => act(scroll.viewportHeight) },
+        " · ",
+        { text: "Esc Back", run: () => act() },
+    ], (hint) => hint, "..."));
+    return {
+        invalidate() {
+            view.invalidate();
+        },
+        dispose: () => {
+            closed = true;
+            attach(null);
+        },
+        render: (width) => view.render(width),
+        handleInput(data) {
+            if (matchesKey(data, "escape")) {
+                act();
+            }
+            else {
+                act(scrollDelta(data, scroll.viewportHeight));
+            }
+        },
+        handleMouse(event) {
+            if (event.type === "wheel") {
+                act(event.wheelDelta ?? 0);
+                return { handled: true };
+            }
+            return view.handleMouse(event);
+        },
+    };
+}

package/dist/pi-intercom/validation.js

@@ -0,0 +1,59 @@
+/** JSON objects are untrusted at the broker and journal boundaries. */
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function isUnknownArray(value) {
+    return Array.isArray(value);
+}
+export function errorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (error === null) {
+        return "null";
+    }
+    switch (typeof error) {
+        case "string":
+            return error;
+        case "undefined":
+            return "undefined";
+        case "boolean":
+        case "number":
+        case "bigint":
+        case "symbol":
+            return String(error);
+        case "object":
+        case "function":
+            // Do not inspect arbitrary thrown objects: they can contain private state.
+            return Object.prototype.toString.call(error);
+        default:
+            return "Unknown error";
+    }
+}
+export function asError(error) {
+    return error instanceof Error ? error : new Error(errorMessage(error));
+}
+// Protocol text permits line feeds and tabs, but rejects other C0/C1 controls.
+// oxlint-disable-next-line no-control-regex
+const UNSAFE_TEXT_CONTROLS = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/;
+// Protocol labels are single-line fields and reject every C0/C1 control.
+// oxlint-disable-next-line no-control-regex
+const UNSAFE_LABEL_CONTROLS = /[\u0000-\u001f\u007f-\u009f]/;
+export function safeText(value) {
+    return typeof value === "string" && !UNSAFE_TEXT_CONTROLS.test(value);
+}
+export function safeLabel(value) {
+    return typeof value === "string" && value.length > 0 && !UNSAFE_LABEL_CONTROLS.test(value);
+}
+export function optionalLabel(value) {
+    return value === undefined || safeLabel(value);
+}
+export function optionalBoolean(value) {
+    return value === undefined || typeof value === "boolean";
+}
+export function finiteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+export function optionalFiniteNumber(value) {
+    return value === undefined || finiteNumber(value);
+}

package/dist/runs/background/async-chain-plan.js

@@ -0,0 +1,265 @@
+import * as path from "node:path";
+import { resolveChildMaxSubagentDepth, } from "../../shared/types.js";
+import { buildChainInstructions, isParallelStep, isDynamicParallelStep, resolveParallelBehaviors, resolveStepBehavior, suppressProgressForReadOnlyTask, writeInitialProgressFile, } from "../../shared/settings.js";
+import { buildSkillInjection, normalizeSkillInput, resolveSkillsWithFallback, } from "../../agents/skills.js";
+import { resolveChildCwd } from "../../shared/utils.js";
+import { findDuplicateOutputPath, injectSingleOutputInstruction, resolveSingleOutputPath, validateFileOnlyOutputMode, } from "../shared/single-output.js";
+import { resolveExpectedWorktreeAgentCwd } from "../shared/worktree.js";
+import { resolveEffectiveAcceptance } from "../shared/acceptance.js";
+import { createStructuredOutputRuntime } from "../shared/structured-output.js";
+import { agentRuntimeFields, usesAgentDefaultOutput, materializeAsyncDefaultOutput, withSavedLaunch, resolveLaunchModel, UnavailableSubagentSkillError, UNAVAILABLE_SUBAGENT_SKILL_ERROR, AsyncStartValidationError, } from "./async-plan.js";
+import { launchErrorMessage } from "./async-launch.js";
+function stepOverrides(step) {
+    const skills = normalizeSkillInput(step.skill);
+    return {
+        ...(step.output !== undefined ? { output: step.output } : {}),
+        ...(step.outputMode !== undefined ? { outputMode: step.outputMode } : {}),
+        ...(step.reads !== undefined ? { reads: step.reads } : {}),
+        ...(step.progress !== undefined ? { progress: step.progress } : {}),
+        ...(skills !== undefined ? { skills } : {}),
+    };
+}
+/** Owns output numbering, progress admission and continuation-session reservation during chain planning. */
+export class AsyncChainPlanner {
+    id;
+    params;
+    workspace;
+    progressInstructionCreated = false;
+    outputIndex = 0;
+    sessionIndex = 0;
+    constructor(id, params, workspace) {
+        this.id = id;
+        this.params = params;
+        this.workspace = workspace;
+    }
+    build() {
+        return this.params.chain.map((step, index) => {
+            if (isParallelStep(step)) {
+                return this.parallelGroup(step, index);
+            }
+            if (isDynamicParallelStep(step)) {
+                return this.dynamicGroup(step, index);
+            }
+            return this.sequential({ ...step, task: this.sequentialTemplate(index) }, { sessionFile: this.nextSessionFile() });
+        });
+    }
+    agent(name) {
+        const agent = this.params.agents.find((candidate) => candidate.name === name);
+        if (!agent) {
+            throw new AsyncStartValidationError(`Unknown agent: ${name}`);
+        }
+        return agent;
+    }
+    sequentialTemplate(index) {
+        const template = this.workspace.templates.at(index);
+        if (typeof template !== "string") {
+            throw new AsyncStartValidationError(`Missing task template for step ${index + 1}.`);
+        }
+        return template;
+    }
+    systemPrompt(agent, behavior, cwd) {
+        const names = behavior.skills === false ? [] : behavior.skills;
+        const { resolved, missing } = resolveSkillsWithFallback(names, cwd, this.params.ctx.cwd, {
+            projectTrusted: this.params.ctx.projectTrusted ?? true,
+        });
+        if (missing.includes("pi-subagents")) {
+            throw new UnavailableSubagentSkillError(UNAVAILABLE_SUBAGENT_SKILL_ERROR);
+        }
+        let prompt = agent.systemPrompt.trim();
+        if (resolved.length > 0) {
+            const injection = buildSkillInjection(resolved);
+            prompt = prompt.length > 0 ? `${prompt}\n\n${injection}` : injection;
+        }
+        return { prompt, skills: resolved.map((skill) => skill.name) };
+    }
+    taskInstructions(step, behavior, input) {
+        const read = buildChainInstructions({ ...behavior, output: false, progress: false }, input.cwd, false);
+        const firstProgress = behavior.progress &&
+            !input.progressPrecreated &&
+            (this.workspace.resultMode !== "chain" || !this.progressInstructionCreated);
+        if (behavior.progress && this.workspace.resultMode === "chain") {
+            this.progressInstructionCreated = true;
+        }
+        const progress = buildChainInstructions({ ...behavior, output: false, reads: false }, input.cwd, firstProgress);
+        const outputPath = resolveSingleOutputPath(input.output, this.params.ctx.cwd, input.cwd);
+        const error = validateFileOnlyOutputMode(behavior.outputMode, outputPath, `Async step (${step.agent})`);
+        if (error !== undefined && error.length > 0) {
+            throw new AsyncStartValidationError(error);
+        }
+        return {
+            task: injectSingleOutputInstruction(`${read.prefix}${step.task ?? "{previous}"}${progress.suffix}`, outputPath),
+            outputPath,
+        };
+    }
+    sequential(step, options) {
+        const agent = this.agent(step.agent);
+        const outputIndex = this.outputIndex++;
+        const cwd = resolveChildCwd(this.workspace.runnerCwd, step.cwd);
+        const instructionCwd = options.behaviorCwd ??
+            (this.workspace.resultMode === "chain" ? this.workspace.chainDir : cwd);
+        const behavior = this.behaviorForStep(agent, step, options.behavior);
+        const launchAgent = behavior.skills === false ? { ...agent, inheritSkills: false } : agent;
+        const usesDefault = usesAgentDefaultOutput(step.output) || step.outputFromAgentDefault === true;
+        const output = usesDefault && this.workspace.resultMode !== "chain"
+            ? materializeAsyncDefaultOutput({
+                output: behavior.output,
+                artifactsDir: this.params.artifactsDir,
+                asyncDir: this.workspace.asyncDir,
+                runId: this.id,
+                agent: step.agent,
+                index: outputIndex,
+            })
+            : behavior.output;
+        const skills = this.systemPrompt(agent, behavior, cwd);
+        const instructions = this.taskInstructions(step, behavior, {
+            cwd: instructionCwd,
+            output,
+            progressPrecreated: options.progressPrecreated === true,
+        });
+        return withSavedLaunch({
+            ...agentRuntimeFields(agent),
+            agent: step.agent,
+            task: instructions.task,
+            phase: step.phase,
+            label: step.label,
+            outputName: step.as,
+            structured: step.outputSchema !== undefined,
+            cwd,
+            ...resolveLaunchModel(agent, step.model, {
+                availableModels: this.params.availableModels,
+                preferredProvider: this.params.ctx.currentModelProvider,
+            }),
+            systemPrompt: skills.prompt,
+            inheritSkills: launchAgent.inheritSkills,
+            skills: [...skills.skills],
+            outputPath: instructions.outputPath,
+            output: behavior.output,
+            outputMode: behavior.outputMode,
+            ...(this.defaultOutputMarker(agent, instructions.outputPath, usesDefault)
+                ? { outputPathFromAgentDefault: true }
+                : {}),
+            sessionFile: options.sessionFile,
+            maxSubagentDepth: resolveChildMaxSubagentDepth(this.params.maxSubagentDepth, agent.maxSubagentDepth),
+            effectiveAcceptance: resolveEffectiveAcceptance({ explicit: step.acceptance }),
+            ...(step.outputSchema
+                ? {
+                    structuredOutputSchema: step.outputSchema,
+                    structuredOutput: createStructuredOutputRuntime(step.outputSchema, path.join(this.workspace.asyncDir, "structured-output")),
+                }
+                : {}),
+        }, launchAgent, this.params);
+    }
+    defaultOutputMarker(agent, outputPath, usesDefault) {
+        return (usesDefault &&
+            outputPath !== undefined &&
+            outputPath.length > 0 &&
+            typeof agent.output === "string" &&
+            !path.isAbsolute(agent.output));
+    }
+    behaviorForStep(agent, step, override) {
+        return suppressProgressForReadOnlyTask(override ?? resolveStepBehavior(agent, stepOverrides(step), this.params.chainSkills ?? []), step.task, this.workspace.originalTask);
+    }
+    parallelGroup(group, stepIndex) {
+        const templates = this.workspace.templates.at(stepIndex);
+        if (templates === undefined || typeof templates === "string") {
+            throw new AsyncStartValidationError(`Missing parallel task templates for step ${stepIndex + 1}.`);
+        }
+        const behaviors = this.workspace.resultMode === "chain"
+            ? resolveParallelBehaviors(group.parallel, this.params.agents, stepIndex, this.params.chainSkills ?? [])
+            : group.parallel.map((task) => resolveStepBehavior(this.agent(task.agent), stepOverrides(task), this.params.chainSkills ?? []));
+        const resolved = behaviors.map((behavior, index) => suppressProgressForReadOnlyTask(behavior, group.parallel[index]?.task, this.workspace.originalTask));
+        const progressPrecreated = this.workspace.resultMode === "chain" && resolved.some((behavior) => behavior.progress);
+        if (progressPrecreated) {
+            if (group.worktree !== true) {
+                writeInitialProgressFile(this.workspace.chainDir);
+            }
+            this.progressInstructionCreated = true;
+        }
+        const parallel = group.parallel.map((task, taskIndex) => this.parallelTask(group, task, {
+            stepIndex,
+            taskIndex,
+            template: templates.at(taskIndex),
+            behavior: resolved.at(taskIndex),
+            progressPrecreated,
+        }));
+        const error = findDuplicateOutputPath(parallel);
+        if (error !== undefined && error.length > 0) {
+            throw new AsyncStartValidationError(error);
+        }
+        return {
+            parallel,
+            cwd: resolveChildCwd(this.workspace.runnerCwd, group.cwd),
+            concurrency: group.concurrency,
+            failFast: group.failFast,
+            worktree: group.worktree,
+        };
+    }
+    parallelTask(group, task, input) {
+        const cwd = resolveChildCwd(this.workspace.runnerCwd, group.cwd);
+        let behaviorCwd;
+        if (group.worktree === true && this.workspace.resultMode !== "chain") {
+            try {
+                behaviorCwd = resolveExpectedWorktreeAgentCwd(cwd, `${this.id}-s${input.stepIndex}`, input.taskIndex);
+            }
+            catch {
+                /* Setup will report unusable worktrees; instructions fall back to the launch cwd. */
+            }
+        }
+        const precreated = this.initializeTaskProgress(group, task, input);
+        return this.sequential({ ...task, task: input.template, cwd: resolveChildCwd(cwd, task.cwd) }, {
+            sessionFile: this.nextSessionFile(),
+            behaviorCwd,
+            progressPrecreated: precreated,
+            behavior: input.behavior,
+        });
+    }
+    initializeTaskProgress(group, task, input) {
+        const precreated = input.progressPrecreated ||
+            (this.workspace.resultMode !== "chain" &&
+                input.behavior?.progress === true &&
+                group.worktree !== true);
+        if (precreated && !input.progressPrecreated) {
+            const progressCwd = resolveChildCwd(resolveChildCwd(this.workspace.runnerCwd, group.cwd), task.cwd);
+            try {
+                writeInitialProgressFile(progressCwd);
+            }
+            catch (error) {
+                throw new AsyncStartValidationError(`Failed to initialize progress in '${progressCwd}': ${launchErrorMessage(error)}`, { cause: error });
+            }
+        }
+        return precreated;
+    }
+    dynamicGroup(group, stepIndex) {
+        const agent = this.agent(group.parallel.agent);
+        const behavior = suppressProgressForReadOnlyTask(resolveStepBehavior(agent, stepOverrides(group.parallel), this.params.chainSkills ?? []), group.parallel.task, this.workspace.originalTask);
+        if (behavior.progress) {
+            writeInitialProgressFile(this.workspace.chainDir);
+            this.progressInstructionCreated = true;
+        }
+        const count = group.expand.maxItems ?? this.params.dynamicFanoutMaxItems ?? 0;
+        return {
+            expand: group.expand,
+            parallel: this.sequential({ ...group.parallel, task: this.sequentialTemplate(stepIndex) }, { progressPrecreated: behavior.progress, behavior }),
+            collect: group.collect,
+            concurrency: group.concurrency,
+            failFast: group.failFast,
+            phase: group.phase,
+            label: group.label,
+            sessionFiles: this.takeDynamicSessions(count),
+        };
+    }
+    nextSessionFile() {
+        const file = this.params.sessionFilesByFlatIndex?.[this.sessionIndex];
+        this.sessionIndex++;
+        return file;
+    }
+    takeDynamicSessions(count) {
+        const files = this.params.sessionFilesByFlatIndex;
+        if (files === undefined || count <= 0) {
+            return;
+        }
+        const selected = files.slice(this.sessionIndex, this.sessionIndex + count);
+        this.sessionIndex += count;
+        return selected;
+    }
+}

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

@@ -5,84 +5,160 @@ 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 { readChildProcessIdentity, trySignalChildTree } from "../../shared/post-exit-stdio-guard.js";
-export function writeAsyncControlRequest(asyncDir, runId, action, index, extendMs) {
-    if (action === "extend" && (typeof extendMs !== "number" || !Number.isSafeInteger(extendMs) || extendMs <= 0 || index !== undefined))
+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 file = readStatus(asyncDir)?.controlRequestFiles === true || readRunJson(path.join(asyncDir, "launch.json"))?.runtimeVersion === 2
+    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, ...(index !== undefined ? { index } : {}), ...(extendMs !== undefined ? { extendMs } : {}), createdAt: Date.now() });
+    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 (status?.runId === runId && status.state === "running" && status.pid && checkPidLiveness(status.pid) === "dead") {
-        if (index !== undefined && (!Number.isSafeInteger(index) || index < 0 || status.steps?.[index]?.status !== "running")) {
-            throw new Error(`No running child at index ${index}. No siblings were stopped.`);
+    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 [];
         }
-        // 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 contract = readQuestionContract(runId, childIndex, undefined, { readConfiguration: false });
-            if (!contract?.pid || !Number.isSafeInteger(contract.pid) || contract.pid <= 0)
-                throw new Error(`Cannot verify process ownership for child ${childIndex}.`);
-            if (checkPidLiveness(contract.pid) === "dead")
-                return [];
-            if (!contract.processIdentity || readChildProcessIdentity(contract.pid) !== contract.processIdentity) {
-                throw new Error(`Cannot verify process ownership for child ${childIndex}. No stop was sent.`);
-            }
-            return [{ pid: contract.pid, identity: contract.processIdentity }];
-        });
-        for (const { pid, identity } of children) {
-            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 { }
-                }
-                else if (readChildProcessIdentity(pid) === identity) {
-                    trySignalChildTree(child, "SIGKILL");
-                }
-            }, 3000).unref();
+        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;
+        return undefined;
     }
-    writeAsyncControlRequest(asyncDir, runId, "interrupt", index);
 }
 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)) : [];
+    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 = `${file}.${randomUUID()}.reading`;
-        try {
-            // Claim before reading, so a legacy writer's replacement remains for the next poll.
-            fs.renameSync(file, claimed);
-        }
-        catch (error) {
-            if (error.code !== "ENOENT")
-                console.error(`Failed to claim async control request '${file}':`, error);
+        const claimed = claimRequest(file);
+        if (claimed === undefined) {
             continue;
         }
         try {
-            if (fs.statSync(claimed).size > 64 * 1024)
+            if (fs.statSync(claimed).size > 64 * 1024) {
                 throw new Error("control request exceeds 64 KiB");
-            const request = JSON.parse(fs.readFileSync(claimed, "utf-8"));
-            if (!request || (request.action !== "interrupt" && request.action !== "cancel" && request.action !== "extend") || request.runId !== runId || typeof request.requestId !== "string" || !request.requestId)
-                continue;
-            if (request.index !== undefined && (!Number.isSafeInteger(request.index) || request.index < 0))
-                continue;
-            if (request.action === "extend" && (typeof request.extendMs !== "number" || !Number.isSafeInteger(request.extendMs) || request.extendMs <= 0 || request.index !== undefined))
-                continue;
-            requests.push(request);
+            }
+            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);