harness-engineering-agent 0.1.0

package/dist/controller/run-controller.js

@@ -0,0 +1,291 @@
+import { RequirementSchema, RunSchema, 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 { 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 { createTaskExecutor } from "./task-executor.js";
+export const createRunController = (options) => {
+    const workspacePolicy = options.workspacePolicy ?? { allowDirty: false };
+    const workspaceAdapter = options.workspaceAdapter ?? createGitWorkspaceAdapter(options.workingDirectory);
+    const writer = createRunPersistence(options);
+    const runtime = createAgentSessionRuntime({
+        sessionAdapter: options.sessionAdapter,
+        ids: options.ids,
+        store: options.store,
+        workingDirectory: options.workingDirectory,
+    });
+    const { runTasks } = createTaskExecutor({
+        options,
+        runtime,
+        writer,
+    });
+    const requestPlan = async (run, requirement) => {
+        const maxPlannerAttempts = run.budgets.planner.limit;
+        let planningRun = run;
+        let lastError;
+        for (let attempt = 1; attempt <= maxPlannerAttempts; attempt += 1) {
+            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"],
+                    },
+                    messageLabel: `planner-${planningRun.runId}-${attempt}`,
+                });
+                return parsePlannerGraph(output);
+            }
+            catch (error) {
+                if (error instanceof RunBudgetExceededError) {
+                    throw error;
+                }
+                if (!(error instanceof AgentRunFailedError || error instanceof AgentOutputParseError)) {
+                    throw error;
+                }
+                lastError = error;
+                if (attempt < maxPlannerAttempts) {
+                    const planning = withStatus(planningRun, "planning");
+                    await writer.persist(planning, writer.createEvent(planningRun.runId, "run.planning.retrying", { attempt }));
+                }
+            }
+        }
+        if (lastError === undefined) {
+            throw new AgentRunFailedError("planner", "retry loop completed without a result");
+        }
+        throw lastError;
+    };
+    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}`);
+    };
+    return {
+        async start(input) {
+            const requirement = RequirementSchema.parse({ schemaVersion: "1.0.0", ...input });
+            const created = RunSchema.parse({
+                schemaVersion: "1.0.0",
+                runId: options.ids.createRunId(),
+                status: "created",
+                requirement,
+                evidence: [],
+                failures: [],
+                agentResults: [],
+                budgets: createInitialRunBudgets(options.maxRunAttempts),
+                governance: createInitialRunGovernance(),
+                workspace: { git: await workspaceAdapter.captureBaseline(workspacePolicy) },
+            });
+            await writer.persist(created, writer.createEvent(created.runId, "run.created", { status: "created" }));
+            if (created.workspace.git.mode === "non-git") {
+                const blocked = withStatus(withGovernance(created, {
+                    ...created.governance,
+                    blockingQuestionId: createBlockedQuestionId(created),
+                }), "clarification_required");
+                await writer.persist(blocked, writer.createEvent(created.runId, "run.blocked.non_git", {
+                    reason: "implementation requires a git workspace baseline",
+                    blockingQuestionId: blocked.governance.blockingQuestionId,
+                }));
+                return blocked;
+            }
+            if (!workspacePolicy.allowDirty && created.workspace.git.initialDirtyPaths.length > 0) {
+                const blocked = withStatus(withGovernance(created, {
+                    ...created.governance,
+                    blockingQuestionId: createBlockedQuestionId(created),
+                }), "clarification_required");
+                await writer.persist(blocked, writer.createEvent(created.runId, "run.blocked.dirty_workspace", {
+                    dirtyPaths: created.workspace.git.initialDirtyPaths,
+                    blockingQuestionId: blocked.governance.blockingQuestionId,
+                }));
+                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;
+            }
+        },
+        async status(runId) {
+            return loadRunWithRetry(runId);
+        },
+        async pause(input) {
+            const current = await loadRunWithRetry(input.runId);
+            if (current.status === "paused") {
+                return current;
+            }
+            if (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,
+            }), "paused");
+            await writer.persist(paused, writer.createEvent(input.runId, "run.paused", {
+                pauseId: paused.governance.paused?.pauseId ?? null,
+                actor: input.actor,
+                reason: input.reason,
+            }));
+            return paused;
+        },
+        async answer(input) {
+            const current = await loadRunWithRetry(input.runId);
+            if (hasAnswer(current, input.questionId)) {
+                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,
+            }), "planning");
+            await writer.persist(updated, writer.createEvent(input.runId, "run.answered", {
+                answerId: updated.governance.answers.at(-1)?.answerId ?? null,
+                questionId: input.questionId,
+                actor: input.actor,
+            }));
+            return updated;
+        },
+        async resume(runId) {
+            const run = await loadRunWithRetry(runId);
+            switch (run.status) {
+                case "completed":
+                case "cancelled":
+                case "failed":
+                    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;
+                default:
+                    return run;
+            }
+        },
+        async cancel(runId) {
+            const current = await loadRunWithRetry(runId);
+            if (current.status === "completed" ||
+                current.status === "cancelled" ||
+                current.status === "failed") {
+                return current;
+            }
+            requireTransition(current, "cancel", canCancel);
+            await runtime.abortActiveSession(runId);
+            const latest = await loadRunWithRetry(runId);
+            if (latest.status === "completed" ||
+                latest.status === "cancelled" ||
+                latest.status === "failed") {
+                return latest;
+            }
+            const cancelled = withStatus(latest, "cancelled");
+            await writer.persist(cancelled, writer.createEvent(runId, "run.cancelled", { status: "cancelled" }));
+            return cancelled;
+        },
+        async waive(input) {
+            const current = await loadRunWithRetry(input.runId);
+            if (hasWaiver(current, input.requirementId)) {
+                return current;
+            }
+            requireTransition(current, "waive", canWaive);
+            requireWaivableRequirement(input.requirementId);
+            const waiver = {
+                waiverId: options.ids.createEventId(`waive-${input.requirementId}`),
+                requirementId: input.requirementId,
+                actor: input.actor,
+                reason: input.reason,
+                residualRisk: input.residualRisk,
+                waivedAt: options.clock.now().toISOString(),
+            };
+            const waivedRun = appendWaiver(current, waiver);
+            await writer.persist(waivedRun, writer.createEvent(input.runId, "run.waived", waiver));
+            return waivedRun;
+        },
+        async report(runId) {
+            const run = await loadRunWithRetry(runId);
+            return createReport(run, options.clock);
+        },
+    };
+};
+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}`;
+//# sourceMappingURL=run-controller.js.map

package/dist/controller/run-controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-controller.js","sourceRoot":"","sources":["../../src/controller/run-controller.ts"],"names":[],"mappings":"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"}

package/dist/controller/run-persistence.d.ts

@@ -0,0 +1,15 @@
+import type { Run, RunId } from "../domain/index.js";
+import type { RunEvent, RunStore } from "../store/index.js";
+import type { ControllerClock, ControllerIdSource } from "./contracts.js";
+type RunPersistenceOptions = {
+    readonly store: RunStore;
+    readonly clock: ControllerClock;
+    readonly ids: Pick<ControllerIdSource, "createEventId">;
+};
+export type RunPersistence = {
+    readonly createEvent: (runId: RunId, type: string, payload: RunEvent["payload"]) => RunEvent;
+    readonly persist: (run: Run, event: RunEvent) => Promise<void>;
+};
+export declare const createRunPersistence: (options: RunPersistenceOptions) => RunPersistence;
+export {};
+//# sourceMappingURL=run-persistence.d.ts.map

package/dist/controller/run-persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-persistence.d.ts","sourceRoot":"","sources":["../../src/controller/run-persistence.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAEzE,KAAK,qBAAqB,GAAG;IAC3B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAA;IAC/B,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,kBAAkB,EAAE,eAAe,CAAC,CAAA;CACxD,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,SAAS,CAAC,KAAK,QAAQ,CAAA;IAC5F,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC/D,CAAA;AAED,eAAO,MAAM,oBAAoB,GAAI,SAAS,qBAAqB,KAAG,cAiDrE,CAAA"}

package/dist/controller/run-persistence.js

@@ -0,0 +1,83 @@
+import { createHash } from "node:crypto";
+export const createRunPersistence = (options) => {
+    const bootstrapSnapshotRunIds = new Set();
+    let writeChain;
+    const persistedIdempotencyKeys = new Map();
+    const createEvent = (runId, type, payload) => {
+        const semanticKey = createSemanticEventKey(runId, type, payload);
+        return {
+            schemaVersion: "1.0.0",
+            eventId: options.ids.createEventId(`event-${semanticKey}`),
+            idempotencyKey: `idempotency-${semanticKey}`,
+            runId,
+            type,
+            timestamp: options.clock.now().toISOString(),
+            payload,
+        };
+    };
+    return {
+        createEvent,
+        persist(run, event) {
+            const committedEvent = {
+                ...event,
+                idempotencyKey: event.idempotencyKey ?? event.eventId,
+                state: run,
+            };
+            const previousOperation = writeChain;
+            const operation = (async () => {
+                if (previousOperation !== undefined) {
+                    await previousOperation;
+                }
+                const knownKeys = persistedIdempotencyKeys.get(run.runId) ?? new Set();
+                if (knownKeys.has(committedEvent.idempotencyKey ?? committedEvent.eventId)) {
+                    await options.store.saveState(run, committedEvent.eventId);
+                    return;
+                }
+                if (!bootstrapSnapshotRunIds.has(run.runId)) {
+                    await options.store.saveState(run);
+                    bootstrapSnapshotRunIds.add(run.runId);
+                }
+                await options.store.appendEvents(run.runId, [committedEvent]);
+                await options.store.saveState(run, committedEvent.eventId);
+                knownKeys.add(committedEvent.idempotencyKey ?? committedEvent.eventId);
+                persistedIdempotencyKeys.set(run.runId, knownKeys);
+            })();
+            writeChain = operation.catch(() => undefined);
+            return operation;
+        },
+    };
+};
+const createSemanticEventKey = (runId, type, payload) => {
+    const hash = createHash("sha256")
+        .update(type)
+        .update("\n")
+        .update(runId)
+        .update("\n")
+        .update(stableStringify(payload))
+        .digest("hex")
+        .slice(0, 16);
+    return `${runId}-${type.replaceAll(".", "-")}-${hash}`;
+};
+const stableStringify = (value) => JSON.stringify(sortJsonValue(value));
+const sortJsonValue = (value) => {
+    if (Array.isArray(value)) {
+        return value.map(sortJsonValue);
+    }
+    if (typeof value !== "object" || value === null) {
+        return value;
+    }
+    if (!isJsonObject(value)) {
+        return value;
+    }
+    return Object.keys(value)
+        .sort((left, right) => left.localeCompare(right))
+        .reduce((result, key) => {
+        const propertyValue = value[key];
+        if (propertyValue !== undefined) {
+            result[key] = sortJsonValue(propertyValue);
+        }
+        return result;
+    }, {});
+};
+const isJsonObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+//# sourceMappingURL=run-persistence.js.map

package/dist/controller/run-persistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-persistence.js","sourceRoot":"","sources":["../../src/controller/run-persistence.ts"],"names":[],"mappings":"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"}

package/dist/controller/run-state.d.ts

@@ -0,0 +1,61 @@
+import { type AgentResult, type Evidence, type Failure, type Run, type RunAnswerRecord, type RunBudgetState, type RunGovernance, type RunPauseRecord, type RunWaiverRecord, type Task, type TaskGraph } from "../domain/index.js";
+import type { RunWorkspace } from "../workspace/index.js";
+import type { RunBudgetKind } from "./contracts.js";
+type MutableRunParts = {
+    readonly evidence: readonly Evidence[];
+    readonly failures: readonly Failure[];
+    readonly agentResults: readonly AgentResult[];
+    readonly workspace: RunWorkspace;
+};
+type MutableGovernance = {
+    readonly blockingQuestionId: string | null;
+    readonly answers: readonly RunAnswerRecord[];
+    readonly waivers: readonly RunWaiverRecord[];
+    readonly paused: RunPauseRecord | null;
+};
+export type PlannedRun = Run & {
+    readonly taskGraph: TaskGraph;
+};
+export declare class RunStateTransitionError extends Error {
+    readonly runId: Run["runId"];
+    readonly operation: string;
+    readonly status: Run["status"];
+    readonly name = "RunStateTransitionError";
+    constructor(runId: Run["runId"], operation: string, status: Run["status"]);
+}
+export declare class RunGovernanceError extends Error {
+    readonly name = "RunGovernanceError";
+}
+export declare class RunBudgetExceededError extends Error {
+    readonly runId: Run["runId"];
+    readonly budget: RunBudgetKind;
+    readonly limit: number;
+    readonly name = "RunBudgetExceededError";
+    constructor(runId: Run["runId"], budget: RunBudgetKind, limit: number);
+}
+export declare const withStatus: (run: Run, status: Run["status"]) => Run;
+export declare const withPlannedStatus: (run: PlannedRun, status: Run["status"]) => PlannedRun;
+export declare const withTask: (run: PlannedRun, task: Task) => PlannedRun;
+export declare const withParts: (run: PlannedRun, parts: MutableRunParts) => PlannedRun;
+export declare const createInitialRunBudgets: (limit: number) => RunBudgetState;
+export declare const createInitialRunGovernance: () => RunGovernance;
+export declare const withGovernance: (run: Run, governance: MutableGovernance) => Run;
+export declare const consumeBudget: (run: Run, budget: RunBudgetKind) => Run;
+export declare const canResume: (run: Run) => boolean;
+export declare const canPause: (run: Run) => boolean;
+export declare const canAnswer: (run: Run) => boolean;
+export declare const canCancel: (run: Run) => boolean;
+export declare const canWaive: (run: Run) => boolean;
+export declare const isTerminalRunStatus: (run: Run) => boolean;
+export declare const isActiveRunStatus: (run: Run) => boolean;
+export declare const requireTransition: (run: Run, operation: string, predicate: (candidate: Run) => boolean) => void;
+export declare const hasAnswer: (run: Run, questionId: string) => boolean;
+export declare const hasWaiver: (run: Run, requirementId: string) => boolean;
+export declare const appendAnswer: (run: Run, answer: RunAnswerRecord) => Run;
+export declare const appendWaiver: (run: Run, waiver: RunWaiverRecord) => Run;
+export declare const setPaused: (run: Run, paused: RunPauseRecord | null) => Run;
+export declare const createBlockedQuestionId: (run: Run) => string;
+export declare const requireWaivableRequirement: (requirementId: string) => void;
+export declare const parsePlannedRun: (value: unknown) => PlannedRun;
+export {};
+//# sourceMappingURL=run-state.d.ts.map

package/dist/controller/run-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-state.d.ts","sourceRoot":"","sources":["../../src/controller/run-state.ts"],"names":[],"mappings":"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"}

package/dist/controller/run-state.js

@@ -0,0 +1,151 @@
+import { RunSchema, } from "../domain/index.js";
+const ACTIVE_RUN_STATUSES = [
+    "planning",
+    "plan_ready",
+    "executing",
+    "verifying",
+];
+const PAUSEABLE_RUN_STATUSES = [
+    "planning",
+    "plan_ready",
+    "executing",
+    "verifying",
+];
+const RESUMEABLE_RUN_STATUSES = [
+    "plan_ready",
+    "executing",
+    "verifying",
+    "paused",
+];
+const ANSWERABLE_RUN_STATUSES = ["clarification_required"];
+const CANCELLABLE_RUN_STATUSES = [
+    "created",
+    "analyzing",
+    "planning",
+    "plan_ready",
+    "executing",
+    "verifying",
+    "evidence_gap",
+    "clarification_required",
+    "paused",
+];
+const WAIVABLE_RUN_STATUSES = [
+    "clarification_required",
+    "paused",
+    "failed",
+];
+const AUTO_WAIVE_BLOCKED_REQUIREMENT_IDS = [
+    "security",
+    "permission",
+    "destructive",
+    "verification",
+];
+const hasAllowedStatus = (allowed, status) => allowed.includes(status);
+export class RunStateTransitionError extends Error {
+    runId;
+    operation;
+    status;
+    name = "RunStateTransitionError";
+    constructor(runId, operation, status) {
+        super(`Cannot ${operation} run ${runId} from status ${status}`);
+        this.runId = runId;
+        this.operation = operation;
+        this.status = status;
+    }
+}
+export class RunGovernanceError extends Error {
+    name = "RunGovernanceError";
+}
+export class RunBudgetExceededError extends Error {
+    runId;
+    budget;
+    limit;
+    name = "RunBudgetExceededError";
+    constructor(runId, budget, limit) {
+        super(`Run ${runId} exhausted the ${budget} budget at limit ${limit}`);
+        this.runId = runId;
+        this.budget = budget;
+        this.limit = limit;
+    }
+}
+export const withStatus = (run, status) => RunSchema.parse({ ...run, status });
+export const withPlannedStatus = (run, status) => parsePlannedRun({ ...run, status });
+export const withTask = (run, task) => parsePlannedRun({
+    ...run,
+    taskGraph: {
+        ...run.taskGraph,
+        tasks: run.taskGraph.tasks.map((candidate) => candidate.taskId === task.taskId ? task : candidate),
+    },
+});
+export const withParts = (run, parts) => parsePlannedRun({ ...run, ...parts });
+export const createInitialRunBudgets = (limit) => {
+    const parsedLimit = Math.max(1, limit);
+    const initialBudget = { limit: parsedLimit, used: 0 };
+    return {
+        intake: initialBudget,
+        planner: initialBudget,
+        task: initialBudget,
+        repair: initialBudget,
+        overall: initialBudget,
+    };
+};
+export const createInitialRunGovernance = () => ({
+    blockingQuestionId: null,
+    answers: [],
+    waivers: [],
+    paused: null,
+});
+export const withGovernance = (run, governance) => RunSchema.parse({ ...run, governance });
+export const consumeBudget = (run, budget) => {
+    const counter = run.budgets[budget];
+    if (counter.used >= counter.limit) {
+        throw new RunBudgetExceededError(run.runId, budget, counter.limit);
+    }
+    return RunSchema.parse({
+        ...run,
+        budgets: {
+            ...run.budgets,
+            [budget]: { ...counter, used: counter.used + 1 },
+        },
+    });
+};
+export const canResume = (run) => hasAllowedStatus(RESUMEABLE_RUN_STATUSES, run.status);
+export const canPause = (run) => hasAllowedStatus(PAUSEABLE_RUN_STATUSES, run.status);
+export const canAnswer = (run) => hasAllowedStatus(ANSWERABLE_RUN_STATUSES, run.status);
+export const canCancel = (run) => hasAllowedStatus(CANCELLABLE_RUN_STATUSES, run.status);
+export const canWaive = (run) => hasAllowedStatus(WAIVABLE_RUN_STATUSES, run.status);
+export const isTerminalRunStatus = (run) => run.status === "completed" || run.status === "cancelled" || run.status === "failed";
+export const isActiveRunStatus = (run) => hasAllowedStatus(ACTIVE_RUN_STATUSES, run.status);
+export const requireTransition = (run, operation, predicate) => {
+    if (!predicate(run)) {
+        throw new RunStateTransitionError(run.runId, operation, run.status);
+    }
+};
+export const hasAnswer = (run, questionId) => run.governance.answers.some((answer) => answer.questionId === questionId);
+export const hasWaiver = (run, requirementId) => run.governance.waivers.some((waiver) => waiver.requirementId === requirementId);
+export const appendAnswer = (run, answer) => withGovernance(run, {
+    ...run.governance,
+    blockingQuestionId: null,
+    answers: [...run.governance.answers, answer],
+    paused: null,
+});
+export const appendWaiver = (run, waiver) => withGovernance(run, {
+    ...run.governance,
+    waivers: [...run.governance.waivers, waiver],
+});
+export const setPaused = (run, paused) => withGovernance(run, { ...run.governance, paused });
+export const createBlockedQuestionId = (run) => `question-${run.runId}`;
+export const requireWaivableRequirement = (requirementId) => {
+    const normalizedRequirement = requirementId.toLowerCase();
+    if (AUTO_WAIVE_BLOCKED_REQUIREMENT_IDS.some((blockedWord) => normalizedRequirement.includes(blockedWord))) {
+        throw new RunGovernanceError(`Requirement ${requirementId} cannot be waived automatically because it is safety- or verification-critical.`);
+    }
+};
+export const parsePlannedRun = (value) => {
+    const run = RunSchema.parse(value);
+    if ("taskGraph" in run) {
+        return run;
+    }
+    throw new TypeError("planned run must include a taskGraph");
+};
+//# sourceMappingURL=run-state.js.map