harness-engineering-agent 0.1.7 → 0.1.9

package/dist/controller/run-controller.js

@@ -1,15 +1,36 @@
-import { RequirementSchema, RunSchema, TaskGraphSchema, } from "../domain/index.js";
+import { z } from "zod";
+import { PlanReviewSchema, RequirementSchema, RunSchema, SchemaVersionSchema, TaskGraphSchema, } from "../domain/index.js";
 import { HARNESS_SESSION_ROLE } from "../session/index.js";
 import { createGitWorkspaceAdapter } from "../workspace/index.js";
 import { parseAgentJson } from "./agent-output.js";
 import { createAgentSessionRuntime } from "./agent-session.js";
-import { AgentOutputParseError, AgentRunFailedError, GraphValidationError, RunCancellationError, } from "./errors.js";
+import { AgentOutputParseError, AgentRunFailedError, GraphValidationError, RunCancellationError, RunPausedError, } from "./errors.js";
 import { validateTaskGraph } from "./graph-validator.js";
 import { createReport } from "./report-factory.js";
 import { plannerTaskPrompt } from "./role-prompts.js";
 import { createRunPersistence } from "./run-persistence.js";
-import { appendAnswer, appendWaiver, canAnswer, canCancel, canPause, canWaive, consumeBudget, createBlockedQuestionId, createInitialRunBudgets, createInitialRunGovernance, hasAnswer, hasWaiver, isTerminalRunStatus, parsePlannedRun, RunBudgetExceededError, requireTransition, requireWaivableRequirement, setPaused, withGovernance, withStatus, } from "./run-state.js";
+import { appendAnswer, appendWaiver, canAdvanceRun, canAnswer, canCancel, canPause, canWaive, consumeBudget, createBlockedQuestionId, createInitialRunBudgets, createInitialRunGovernance, hasAnswer, hasWaiver, isTerminalRunStatus, parsePlannedRun, RunBudgetExceededError, requireTransition, requireWaivableRequirement, setPaused, withGovernance, withStatus, } from "./run-state.js";
+import { PlannerContextOutputSchema } from "./task-agent-schemas.js";
 import { createTaskExecutor } from "./task-executor.js";
+const PlanReviewVerifierOutputSchema = z
+    .object({
+    schemaVersion: SchemaVersionSchema,
+    role: z.literal("verifier"),
+    status: z.enum(["approved", "rejected"]),
+    summary: z.string().trim().min(1),
+    evidenceIds: z.array(z.string().trim().min(1)).readonly(),
+    planReview: PlanReviewSchema,
+})
+    .strict()
+    .readonly();
+class PlanningBlockedError extends Error {
+    run;
+    name = "PlanningBlockedError";
+    constructor(run) {
+        super(`planning blocked: ${run.status}`);
+        this.run = run;
+    }
+}
 export const createRunController = (options) => {
     const workspacePolicy = options.workspacePolicy ?? { allowDirty: false };
     const workspaceAdapter = options.workspaceAdapter ?? createGitWorkspaceAdapter(options.workingDirectory);
@@ -20,11 +41,188 @@ export const createRunController = (options) => {
         store: options.store,
         workingDirectory: options.workingDirectory,
     });
+    const loadRunWithRetry = async (runId) => {
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            try {
+                return await options.store.loadState(runId);
+            }
+            catch (error) {
+                if (!isMissingRunError(error, runId) || attempt === 2) {
+                    throw error;
+                }
+                await waitForNextTurn();
+            }
+        }
+        throw new TypeError(`missing run ${runId}`);
+    };
     const { runTasks } = createTaskExecutor({
         options,
         runtime,
         writer,
+        loadRun: loadRunWithRetry,
     });
+    const advancingRuns = new Map();
+    const persistPlanBlockedState = async (input) => {
+        const nextRun = withStatus(withGovernance(input.run, {
+            ...input.run.governance,
+            blockingQuestionId: input.status === "clarification_required" ? createBlockedQuestionId(input.run) : null,
+        }), input.status);
+        await writer.persist(nextRun, writer.createEvent(input.run.runId, input.eventType, {
+            reason: input.reason,
+            ...(input.status === "clarification_required"
+                ? { blockingQuestionId: nextRun.governance.blockingQuestionId }
+                : {}),
+            ...input.payload,
+        }));
+        return nextRun;
+    };
+    const requestContextPackage = async (run, requirement) => {
+        const outputText = await runtime.sendAgent({
+            runId: run.runId,
+            role: HARNESS_SESSION_ROLE.planner,
+            title: `${requirement.title} context`,
+            brief: JSON.stringify({ requirement, runId: run.runId }),
+            constraints: [
+                "先输出可审计 ContextPackage。",
+                "上下文不足时只能返回 evidence_gap 或 clarification_required。",
+                "不要生成 TaskGraph，不要推进状态。",
+            ],
+            evidence: [],
+            outputContract: {
+                schemaVersion: "1.0.0",
+                type: "PlannerContextOutput",
+                requiredFields: ["schemaVersion", "role", "status"],
+            },
+            systemPrompt: "你是 Fuxi。先输出 PlannerContextOutput JSON。",
+            messageLabel: `planner-context-${run.runId}`,
+        });
+        const output = parseAgentJson(outputText, PlannerContextOutputSchema, "planner");
+        switch (output.status) {
+            case "completed":
+                return { kind: "completed", contextPackage: output.contextPackage };
+            case "clarification_required":
+                return {
+                    kind: "blocked",
+                    run: await persistPlanBlockedState({
+                        run,
+                        status: "clarification_required",
+                        reason: output.summary,
+                        eventType: "run.planning.context_gap",
+                        payload: { missingContext: output.missingContext },
+                    }),
+                };
+            case "evidence_gap":
+                return {
+                    kind: "blocked",
+                    run: await persistPlanBlockedState({
+                        run,
+                        status: "evidence_gap",
+                        reason: output.summary,
+                        eventType: "run.planning.context_gap",
+                        payload: { missingContext: output.missingContext },
+                    }),
+                };
+            default:
+                return assertNever(output);
+        }
+    };
+    const requestTaskGraph = async (input) => {
+        const output = await runtime.sendAgent({
+            runId: input.run.runId,
+            role: HARNESS_SESSION_ROLE.planner,
+            title: input.requirement.title,
+            brief: plannerTaskPrompt({
+                requirement: input.requirement,
+                runId: input.run.runId,
+                contextPackage: input.contextPackage,
+            }),
+            constraints: [
+                "只允许根据 requirement 和 contextPackage 生成任务图。",
+                "不得执行任务或请求父会话完整历史。",
+                "只输出符合 TaskGraph 契约的 JSON。",
+            ],
+            evidence: [
+                {
+                    refId: input.contextPackage.contextPackageId,
+                    kind: "artifact",
+                    summary: input.contextPackage.summary,
+                },
+            ],
+            outputContract: {
+                schemaVersion: "1.0.0",
+                type: "TaskGraph",
+                requiredFields: ["schemaVersion", "graphId", "runId", "version", "tasks", "edges"],
+            },
+            systemPrompt: "你是 Fuxi。使用已持久化的 ContextPackage 生成 TaskGraph JSON。",
+            messageLabel: `planner-graph-${input.run.runId}`,
+        });
+        return parsePlannerGraph(output);
+    };
+    const persistPlanningArtifacts = async (input) => {
+        const nextRun = RunSchema.parse({
+            ...input.run,
+            ...(input.contextPackage === undefined ? {} : { contextPackage: input.contextPackage }),
+            ...(input.planReview === undefined ? {} : { planReview: input.planReview }),
+            ...(input.taskGraph === undefined
+                ? {}
+                : { taskGraph: input.taskGraph, status: "plan_ready" }),
+        });
+        await writer.persist(nextRun, writer.createEvent(input.run.runId, input.eventType, input.payload));
+        return nextRun;
+    };
+    const requestPlanReview = async (input) => {
+        const outputText = await runtime.sendAgent({
+            runId: input.run.runId,
+            role: HARNESS_SESSION_ROLE.verifier,
+            title: `Review ${input.requirement.title}`,
+            brief: JSON.stringify({
+                requirement: input.requirement,
+                contextPackage: input.contextPackage,
+                taskGraph: input.taskGraph,
+            }),
+            constraints: [
+                "独立审查每个 criterion/path/dependency/verification/category。",
+                "只输出包含完整 PlanReview 的 VerifierOutput JSON。",
+                "计划未覆盖 criterionId、未知类别、非法路径或不可执行验证时必须 rejected。",
+            ],
+            evidence: [
+                {
+                    refId: input.contextPackage.contextPackageId,
+                    kind: "artifact",
+                    summary: input.contextPackage.summary,
+                },
+                {
+                    refId: input.taskGraph.graphId,
+                    kind: "artifact",
+                    summary: `Task graph ${input.taskGraph.graphId}`,
+                },
+            ],
+            outputContract: {
+                schemaVersion: "1.0.0",
+                type: "VerifierOutput",
+                requiredFields: ["schemaVersion", "role", "status", "summary", "evidenceIds", "planReview"],
+            },
+            systemPrompt: "你是 Zhulong。只输出 PlanReview 版 VerifierOutput JSON。",
+            messageLabel: `plan-review-${input.run.runId}`,
+        });
+        const output = PlanReviewVerifierOutputSchema.parse(JSON.parse(outputText));
+        if (output.status !== "approved") {
+            throw new GraphValidationError(output.planReview.findings.map((finding) => finding.message).length === 0
+                ? [output.summary]
+                : output.planReview.findings.map((finding) => finding.message));
+        }
+        return output.planReview;
+    };
+    const ensureExecutionCategoriesConfigured = (graph) => {
+        const missingCategories = graph.tasks
+            .map((task) => task.executionCategory)
+            .filter((category) => options.executionCategories?.[category] === undefined);
+        if (missingCategories.length > 0) {
+            throw new GraphValidationError([
+                `Unsupported executionCategory mappings: ${[...new Set(missingCategories)].join(", ")}`,
+            ]);
+        }
+    };
     const requestPlan = async (run, requirement) => {
         const maxPlannerAttempts = run.budgets.planner.limit;
         let planningRun = run;
@@ -33,28 +231,54 @@ export const createRunController = (options) => {
             try {
                 planningRun = consumeBudget(planningRun, "planner");
                 planningRun = consumeBudget(planningRun, "overall");
-                const output = await runtime.sendAgent({
-                    runId: planningRun.runId,
-                    role: HARNESS_SESSION_ROLE.planner,
-                    title: requirement.title,
-                    brief: plannerTaskPrompt({ requirement, runId: planningRun.runId }),
-                    constraints: [
-                        "只允许根据 requirement 生成任务图。",
-                        "不得执行任务或请求父会话完整历史。",
-                        "只输出符合 TaskGraph 契约的 JSON。",
-                    ],
-                    evidence: [],
-                    outputContract: {
-                        schemaVersion: "1.0.0",
-                        type: "TaskGraph",
-                        requiredFields: ["schemaVersion", "graphId", "runId", "version", "tasks", "edges"],
+                const contextResult = await requestContextPackage(planningRun, requirement);
+                if (contextResult.kind === "blocked") {
+                    throw new PlanningBlockedError(contextResult.run);
+                }
+                planningRun = await persistPlanningArtifacts({
+                    run: planningRun,
+                    contextPackage: contextResult.contextPackage,
+                    eventType: "run.planning.context_captured",
+                    payload: {
+                        contextPackageId: contextResult.contextPackage.contextPackageId,
+                        requirementId: contextResult.contextPackage.requirementId,
                     },
-                    messageLabel: `planner-${planningRun.runId}-${attempt}`,
                 });
-                return parsePlannerGraph(output);
+                const taskGraph = await requestTaskGraph({
+                    run: planningRun,
+                    requirement,
+                    contextPackage: contextResult.contextPackage,
+                });
+                validateTaskGraph(taskGraph, requirement, run.runId);
+                ensureExecutionCategoriesConfigured(taskGraph);
+                const planReview = await requestPlanReview({
+                    run: planningRun,
+                    requirement,
+                    contextPackage: contextResult.contextPackage,
+                    taskGraph,
+                });
+                planningRun = await persistPlanningArtifacts({
+                    run: planningRun,
+                    contextPackage: contextResult.contextPackage,
+                    taskGraph,
+                    planReview,
+                    eventType: "run.planning.plan_review_approved",
+                    payload: {
+                        graphId: taskGraph.graphId,
+                        reviewId: planReview.reviewId,
+                    },
+                });
+                return {
+                    contextPackage: contextResult.contextPackage,
+                    taskGraph,
+                    planReview,
+                };
             }
             catch (error) {
-                if (error instanceof RunBudgetExceededError) {
+                if (error instanceof RunBudgetExceededError || error instanceof RunCancellationError) {
+                    throw error;
+                }
+                if (error instanceof PlanningBlockedError) {
                     throw error;
                 }
                 if (!(error instanceof AgentRunFailedError || error instanceof AgentOutputParseError)) {
@@ -72,21 +296,124 @@ export const createRunController = (options) => {
         }
         throw lastError;
     };
-    const loadRunWithRetry = async (runId) => {
-        for (let attempt = 0; attempt < 3; attempt += 1) {
-            try {
-                return await options.store.loadState(runId);
+    const persistPlanningState = async (run) => {
+        if (run.status === "planning") {
+            return run;
+        }
+        const planning = withStatus(run, "planning");
+        await writer.persist(planning, writer.createEvent(run.runId, "run.planning", { status: "planning" }));
+        return planning;
+    };
+    const persistExecutingState = async (run) => {
+        const executing = parsePlannedRun({ ...run, status: "executing" });
+        await writer.persist(executing, writer.createEvent(executing.runId, "run.executing", { status: "executing" }));
+        return executing;
+    };
+    const continueRun = async (runId) => {
+        const current = await loadRunWithRetry(runId);
+        if (!canAdvanceRun(current)) {
+            return current;
+        }
+        const reconciliation = await runtime.reconcileOrphanSessions({
+            runId,
+            actorId: "harness-recovery",
+        });
+        if (reconciliation.kind === "rebound") {
+            return current;
+        }
+        if (reconciliation.kind === "abandoned") {
+            const interrupted = "taskGraph" in current
+                ? withStatus(current, "paused")
+                : withStatus(withGovernance(current, {
+                    ...current.governance,
+                    blockingQuestionId: createBlockedQuestionId(current),
+                }), "clarification_required");
+            await writer.persist(interrupted, writer.createEvent(runId, "run.recovery.session_abandoned", {
+                sessionIds: reconciliation.sessionIds,
+                status: interrupted.status,
+            }));
+            return interrupted;
+        }
+        if (current.status === "created" ||
+            current.status === "analyzing" ||
+            current.status === "planning") {
+            const planning = await persistPlanningState(current);
+            const planningArtifacts = await requestPlan(planning, planning.requirement);
+            validateTaskGraph(planningArtifacts.taskGraph, planning.requirement, runId);
+            runtime.clearInterruption(runId);
+            return await runTasks(await persistExecutingState(parsePlannedRun({
+                ...planning,
+                status: "executing",
+                taskGraph: planningArtifacts.taskGraph,
+                contextPackage: planningArtifacts.contextPackage,
+                planReview: planningArtifacts.planReview,
+            })));
+        }
+        const planned = parsePlannedRun(setPaused(current, null));
+        runtime.clearInterruption(runId);
+        if (planned.status !== "executing" || current.governance.paused !== null) {
+            return await runTasks(await persistExecutingState(planned));
+        }
+        return await runTasks(planned);
+    };
+    const finalizeAdvanceError = async (runId, error) => {
+        if (error instanceof GraphValidationError ||
+            error instanceof PlanningBlockedError ||
+            error instanceof AgentRunFailedError ||
+            error instanceof AgentOutputParseError ||
+            error instanceof RunBudgetExceededError) {
+            const latest = await loadRunWithRetry(runId);
+            if (error instanceof PlanningBlockedError) {
+                return error.run;
             }
-            catch (error) {
-                if (!isMissingRunError(error, runId) || attempt === 2) {
-                    throw error;
-                }
-                await waitForNextTurn();
+            const planning = withStatus(latest, "planning");
+            const blocked = withStatus(withGovernance(planning, {
+                ...planning.governance,
+                blockingQuestionId: error instanceof RunBudgetExceededError ? createBlockedQuestionId(planning) : null,
+            }), error instanceof RunBudgetExceededError ? "paused" : "failed");
+            await writer.persist(blocked, writer.createEvent(runId, error instanceof RunBudgetExceededError ? "run.paused" : "run.failed", {
+                reason: error.message,
+                ...(error instanceof RunBudgetExceededError
+                    ? {
+                        budget: error.budget,
+                        blockingQuestionId: blocked.governance.blockingQuestionId,
+                    }
+                    : {}),
+            }));
+            return blocked;
+        }
+        if (error instanceof RunPausedError) {
+            const latest = await loadRunWithRetry(runId);
+            if (latest.status === "paused") {
+                return latest;
             }
+            return withStatus(setPaused(latest, latest.governance.paused), "paused");
         }
-        throw new TypeError(`missing run ${runId}`);
+        if (error instanceof RunCancellationError) {
+            const latest = await loadRunWithRetry(runId);
+            if (latest.status === "cancelled") {
+                return latest;
+            }
+            const cancelled = withStatus(latest, "cancelled");
+            await writer.persist(cancelled, writer.createEvent(runId, "run.cancelled", { status: "cancelled" }));
+            return cancelled;
+        }
+        throw error;
     };
-    return {
+    const advanceRun = async (runId) => {
+        const active = advancingRuns.get(runId);
+        if (active !== undefined) {
+            return active;
+        }
+        const pending = continueRun(runId)
+            .catch(async (error) => finalizeAdvanceError(runId, error))
+            .finally(() => {
+            advancingRuns.delete(runId);
+        });
+        advancingRuns.set(runId, pending);
+        return pending;
+    };
+    const controller = {
         async start(input) {
             const requirement = RequirementSchema.parse({ schemaVersion: "1.0.0", ...input });
             const created = RunSchema.parse({
@@ -124,75 +451,35 @@ export const createRunController = (options) => {
                 }));
                 return blocked;
             }
-            const planning = withStatus(created, "planning");
-            await writer.persist(planning, writer.createEvent(created.runId, "run.planning", { status: "planning" }));
-            try {
-                const graph = await requestPlan(created, requirement);
-                validateTaskGraph(graph, requirement, created.runId);
-                const executing = parsePlannedRun({ ...planning, status: "executing", taskGraph: graph });
-                await writer.persist(executing, writer.createEvent(created.runId, "run.executing", { status: "executing" }));
-                return await runTasks(executing);
-            }
-            catch (error) {
-                if (error instanceof GraphValidationError ||
-                    error instanceof AgentRunFailedError ||
-                    error instanceof AgentOutputParseError ||
-                    error instanceof RunBudgetExceededError) {
-                    const failed = withStatus(withGovernance(planning, {
-                        ...planning.governance,
-                        blockingQuestionId: error instanceof RunBudgetExceededError ? createBlockedQuestionId(planning) : null,
-                    }), error instanceof RunBudgetExceededError ? "paused" : "failed");
-                    await writer.persist(failed, writer.createEvent(created.runId, error instanceof RunBudgetExceededError ? "run.paused" : "run.failed", {
-                        reason: error.message,
-                        ...(error instanceof RunBudgetExceededError
-                            ? {
-                                budget: error.budget,
-                                blockingQuestionId: failed.governance.blockingQuestionId,
-                            }
-                            : {}),
-                    }));
-                    if (error instanceof RunBudgetExceededError) {
-                        return failed;
-                    }
-                }
-                if (error instanceof RunCancellationError) {
-                    const latest = await options.store.loadState(created.runId);
-                    if (latest.status === "cancelled") {
-                        return latest;
-                    }
-                    const cancelled = withStatus(latest, "cancelled");
-                    await writer.persist(cancelled, writer.createEvent(created.runId, "run.cancelled", { status: "cancelled" }));
-                    return cancelled;
-                }
-                throw error;
-            }
+            return created;
+        },
+        async advanceRun(runId) {
+            return advanceRun(runId);
         },
         async status(runId) {
             return loadRunWithRetry(runId);
         },
         async pause(input) {
             const current = await loadRunWithRetry(input.runId);
-            if (current.status === "paused") {
-                return current;
-            }
-            if (isTerminalRunStatus(current)) {
+            if (current.status === "paused" || isTerminalRunStatus(current)) {
                 return current;
             }
             requireTransition(current, "pause", canPause);
-            await runtime.abortActiveSession(input.runId);
-            const pausedAt = options.clock.now().toISOString();
             const paused = withStatus(setPaused(current, {
                 pauseId: options.ids.createEventId(`pause-${input.runId}`),
                 actor: input.actor,
                 reason: input.reason,
-                pausedAt,
+                pausedAt: options.clock.now().toISOString(),
             }), "paused");
+            runtime.markPaused(input.runId);
             await writer.persist(paused, writer.createEvent(input.runId, "run.paused", {
                 pauseId: paused.governance.paused?.pauseId ?? null,
                 actor: input.actor,
                 reason: input.reason,
             }));
-            return paused;
+            await runtime.abortActiveSession(input.runId);
+            const latest = await loadRunWithRetry(input.runId);
+            return latest.status === "paused" ? latest : paused;
         },
         async answer(input) {
             const current = await loadRunWithRetry(input.runId);
@@ -200,13 +487,12 @@ export const createRunController = (options) => {
                 return current;
             }
             requireTransition(current, "answer", canAnswer);
-            const answeredAt = options.clock.now().toISOString();
             const updated = withStatus(appendAnswer(current, {
                 answerId: options.ids.createEventId(`answer-${input.questionId}`),
                 questionId: input.questionId,
                 answer: input.answer,
                 actor: input.actor,
-                answeredAt,
+                answeredAt: options.clock.now().toISOString(),
             }), "planning");
             await writer.persist(updated, writer.createEvent(input.runId, "run.answered", {
                 answerId: updated.governance.answers.at(-1)?.answerId ?? null,
@@ -221,37 +507,30 @@ export const createRunController = (options) => {
                 case "completed":
                 case "cancelled":
                 case "failed":
+                case "clarification_required":
                     return run;
                 case "created":
                 case "analyzing":
                 case "planning":
-                case "clarification_required":
-                    return run;
                 case "plan_ready":
                 case "executing":
                 case "verifying":
                 case "paused":
-                    if (runtime.hasActiveSession(runId)) {
-                        return run;
-                    }
-                    return "taskGraph" in run ? await runTasks(parsePlannedRun(setPaused(run, null))) : run;
+                    return advanceRun(runId);
                 default:
                     return run;
             }
         },
         async cancel(runId) {
             const current = await loadRunWithRetry(runId);
-            if (current.status === "completed" ||
-                current.status === "cancelled" ||
-                current.status === "failed") {
+            if (isTerminalRunStatus(current)) {
                 return current;
             }
             requireTransition(current, "cancel", canCancel);
+            runtime.markCancelled(runId);
             await runtime.abortActiveSession(runId);
             const latest = await loadRunWithRetry(runId);
-            if (latest.status === "completed" ||
-                latest.status === "cancelled" ||
-                latest.status === "failed") {
+            if (isTerminalRunStatus(latest)) {
                 return latest;
             }
             const cancelled = withStatus(latest, "cancelled");
@@ -282,10 +561,14 @@ export const createRunController = (options) => {
             return createReport(run, options.clock);
         },
     };
+    return controller;
 };
 const parsePlannerGraph = (text) => parseAgentJson(text, TaskGraphSchema, "planner");
 const waitForNextTurn = async () => await new Promise((resolve) => {
     setTimeout(resolve, 0);
 });
 const isMissingRunError = (error, runId) => error instanceof TypeError && error.message === `missing run ${runId}`;
+const assertNever = (value) => {
+    throw new TypeError(`Unexpected planner output: ${JSON.stringify(value)}`);
+};
 //# sourceMappingURL=run-controller.js.map