@warlock.js/core 4.8.0 → 4.8.1

package/esm/ai/src/planner/planner-run.mjs

@@ -1,769 +0,0 @@
-import { AIError } from "../errors/ai-error.mjs";
-import { PlannerFailedError } from "../errors/planner-failed-error.mjs";
-import { PlannerCancelledError } from "../errors/planner-cancelled-error.mjs";
-import { PlannerPlanInvalidError } from "../errors/planner-plan-invalid-error.mjs";
-import { SchemaValidationError } from "../errors/schema-validation-error.mjs";
-import { accumulateCost } from "../utils/compute-cost.mjs";
-import { generateRunId } from "../utils/generate-run-id.mjs";
-import { captureChildReport, withoutRunFrame } from "../utils/run-context.mjs";
-import { stampReportLineage } from "../utils/stamp-report-lineage.mjs";
-import { notifyObservers } from "../observe/resolve-observers.mjs";
-import { buildDag, readyNodes, sinkNodes } from "./dag-scheduler.mjs";
-import { planSchema } from "./plan-schema.mjs";
-import { deletePlannerSnapshot, persistPlannerSnapshot } from "./snapshot.mjs";
-import { log } from "@warlock.js/logger";
-
-//#region ../@warlock.js/ai/src/planner/planner-run.ts
-/**
-* Per-call orchestration state for one `planner.execute()` invocation.
-*
-* **Role.** Owns the full bounded-v1 planning lifecycle across four
-* phases that share mutable accumulators: (1) ask the LLM to GENERATE a
-* plan, (2) execute each plan step through its capability's `execute()`,
-* (3) optionally validate the final output, (4) assemble the unified
-* {@link PlannerResult}. Instantiated fresh per call inside the factory
-* so the accumulators (`usage`, `children`, `executedSteps`) are never
-* shared across runs. Unexported — callers only ever see the plain
-* {@link PlannerResult}.
-*
-* **Composition, not a fork.** Plan generation runs through a normal
-* `agent.execute()`; each step runs through the capability's own
-* `executable.execute()`. The planner adds the plan-generation brain and
-* the ordered-dispatch loop on top of the existing executable machinery —
-* it does not reimplement agent or step internals.
-*/
-var PlannerRun = class {
-	constructor(args) {
-		this.args = args;
-		this.startedAt = (/* @__PURE__ */ new Date()).toISOString();
-		this.startPerf = performance.now();
-		this.usage = {
-			input: 0,
-			output: 0,
-			total: 0
-		};
-		this.children = [];
-		this.executedSteps = [];
-		this.awaitingApproval = false;
-		this.replanCount = 0;
-		this.dagResumeConsumed = false;
-		this.runId = args.resumeFrom?.runId ?? args.options?.runId ?? generateRunId("planner");
-		if (args.resumeFrom) {
-			this.plan = args.resumeFrom.plan;
-			this.executedSteps.push(...args.resumeFrom.executedSteps);
-			this.children.push(...args.resumeFrom.children);
-			this.mergeUsage(this.usage, args.resumeFrom.usage);
-			this.replanCount = args.resumeFrom.replanCount;
-			this.startedAt = args.resumeFrom.startedAt;
-		}
-	}
-	/**
-	* Run the planner end-to-end. Never throws on runtime failure —
-	* generation errors, plan-validity errors, step failures, and
-	* cancellation all surface on `result.error` with a narrowing
-	* `report.status`.
-	*/
-	async run() {
-		const result = await this.runPlan();
-		await notifyObservers(this.args.config.observe, result.report);
-		captureChildReport(result.report);
-		return result;
-	}
-	/**
-	* Drive the planner lifecycle and return the built result WITHOUT
-	* routing it — `run()` owns observer routing + auto-nesting so the
-	* unified tree is emitted exactly once.
-	*/
-	async runPlan() {
-		if (this.args.resumeFrom && this.args.resumeFrom.status === "completed") {
-			this.rebuildResumedTerminal("completed");
-			return this.buildResult();
-		}
-		try {
-			if (this.isAborted()) {
-				this.markCancelled();
-				await this.checkpoint(this.resolveSnapshotStatus());
-				return this.buildResult();
-			}
-			const plan = this.args.resumeFrom ? this.plan : this.args.options?.approvedPlan ?? await this.generatePlan();
-			if (this.error || !plan) {
-				await this.checkpoint(this.resolveSnapshotStatus());
-				return this.buildResult();
-			}
-			if (!this.args.resumeFrom) {
-				this.assertPlanValid(plan);
-				if (this.error) {
-					await this.checkpoint(this.resolveSnapshotStatus());
-					return this.buildResult();
-				}
-			}
-			this.plan = plan;
-			if (!this.args.resumeFrom && this.args.options?.mode === "plan-only" && !this.args.options?.approvedPlan) {
-				this.awaitingApproval = true;
-				return this.buildResult();
-			}
-			await this.executePlan(plan);
-			await this.finalizeOutput();
-		} catch (caught) {
-			this.error = this.toAIError(caught);
-		}
-		await this.checkpoint(this.resolveSnapshotStatus());
-		if (!this.error && this.args.config.durable?.deleteOnComplete) {
-			const outcome = await deletePlannerSnapshot({
-				durable: this.args.config.durable,
-				runId: this.runId
-			});
-			if (!outcome.ok) this.logDurableFailure("snapshot.delete.failed", outcome.error);
-		}
-		return this.buildResult();
-	}
-	/**
-	* Phase 1 — ask the planning agent for a structured plan. The plan
-	* schema (built from the live capability names) is supplied as the
-	* agent's per-call `output`, so the model is steered to reference only
-	* real capabilities. The planning trip's usage + report roll into the
-	* planner's totals regardless of outcome.
-	*
-	* `feedback` is set only on a RE-plan: the regenerated request is
-	* seeded with the executed-step digest plus the caller's feedback so
-	* the planner revises the remaining work rather than starting cold.
-	*/
-	async generatePlan(feedback) {
-		const schema = planSchema([...this.args.capabilities.keys()], this.args.maxSteps);
-		const result = await withoutRunFrame(() => this.args.planningAgent.execute(this.buildPlanPrompt(feedback), {
-			output: schema,
-			placeholders: this.args.options?.placeholders,
-			signal: this.args.options?.signal,
-			sessionId: this.args.options?.sessionId
-		}));
-		this.absorb(result.usage, result.report);
-		if (result.error) {
-			this.error = result.error instanceof SchemaValidationError ? new PlannerPlanInvalidError(`ai.planner("${this.args.config.name}"): the planner produced no usable plan`, {
-				cause: result.error,
-				context: { runId: this.runId }
-			}) : result.error;
-			return;
-		}
-		const plan = result.data;
-		if (!plan || !Array.isArray(plan.steps) || plan.steps.length === 0) {
-			this.error = new PlannerPlanInvalidError(`ai.planner("${this.args.config.name}"): the planner produced no usable plan`, { context: { runId: this.runId } });
-			return;
-		}
-		this.assertPlanValid(plan);
-		if (this.error) return;
-		return plan;
-	}
-	/**
-	* Shared plan-validity guard — used both for a freshly generated plan
-	* and for a caller-supplied `approvedPlan`. Sets `this.error` to a
-	* typed {@link PlannerPlanInvalidError} when the plan is empty or names
-	* an unknown capability; a stale `approvedPlan` thus fails the same way
-	* a hallucinated capability does, never silently mis-dispatching.
-	*/
-	assertPlanValid(plan) {
-		if (!Array.isArray(plan.steps) || plan.steps.length === 0) {
-			this.error = new PlannerPlanInvalidError(`ai.planner("${this.args.config.name}"): the planner produced no usable plan`, { context: { runId: this.runId } });
-			return;
-		}
-		const unknownStep = plan.steps.find((step) => !this.args.capabilities.has(step.capability));
-		if (unknownStep) this.error = new PlannerPlanInvalidError(`ai.planner("${this.args.config.name}"): plan references unknown capability "${unknownStep.capability}"`, { context: {
-			runId: this.runId,
-			capability: unknownStep.capability
-		} });
-	}
-	/**
-	* Phase 2 — execute the plan. Branches on `config.dag`: the default is
-	* the strict array-order sequential loop (byte-for-byte today's
-	* behavior when neither `onStep` nor `replan` is configured); `dag:
-	* true` schedules independent `dependsOn` branches in parallel.
-	*/
-	async executePlan(plan) {
-		if (this.args.config.dag) return this.executeDag(plan);
-		return this.executeSequential(plan);
-	}
-	/**
-	* Sequential executor — the original strict array-order loop, threading
-	* each completed step's output into the next step's input context.
-	* Stops at the first step failure or when the abort signal fires
-	* between steps; steps beyond `maxSteps` are recorded `skipped`.
-	*
-	* **Additive hooks (inert by default).** After each step settles it
-	* fires the `onStep` directive hook; an `abort` directive stops the run
-	* like a failure, and a `replan` directive (or, when `config.replan` is
-	* set, an unhandled failure) regenerates the REMAINING plan instead of
-	* aborting. With no `onStep` and no `replan`, the behavior is identical
-	* to before.
-	*/
-	async executeSequential(plan) {
-		const previousOutputs = [];
-		let steps = plan.steps;
-		let index = 0;
-		if (this.args.resumeFrom) index = this.rehydrateSequentialState(steps, previousOutputs);
-		while (index < steps.length) {
-			const step = steps[index];
-			if (index >= this.args.maxSteps) {
-				this.recordSkipped(index, step);
-				index++;
-				continue;
-			}
-			if (this.isAborted()) {
-				this.markCancelled();
-				this.recordSkipped(index, step);
-				index++;
-				continue;
-			}
-			const completed = await this.executeStep(index, step, previousOutputs);
-			const snapshot = this.snapshotFor(index);
-			const directive = snapshot ? await this.resolveDirective(snapshot, plan, completed) : void 0;
-			if (directive?.type === "replan") {
-				const remaining = await this.regeneratePlan(directive.feedback);
-				if (this.error || !remaining) {
-					this.skipRest(steps, index + 1);
-					return;
-				}
-				steps = remaining.steps;
-				index = 0;
-				previousOutputs.length = 0;
-				previousOutputs.push(...this.executedDigest());
-				continue;
-			}
-			if (directive?.type === "abort") {
-				this.skipRest(steps, index + 1);
-				return;
-			}
-			index++;
-		}
-	}
-	/**
-	* DAG executor — schedule independent `dependsOn` branches in parallel.
-	*
-	* Builds the DAG (cycle / unknown-id → `PlannerPlanInvalidError`),
-	* then repeatedly computes the ready set (steps whose deps all
-	* completed), dispatches up to `maxConcurrency` of them with
-	* `Promise.all`, and feeds each step ONLY its dependencies' outputs. A
-	* failed step blocks just its descendants (recorded `skipped`);
-	* independent branches still settle. With an `output` schema set, the
-	* final `data` is the topological SINK's output (multiple sinks → a
-	* convergence error).
-	*/
-	async executeDag(plan) {
-		const dag = buildDag(plan.steps, this.args.config.name);
-		const maxConcurrency = Math.max(1, this.args.config.maxConcurrency ?? 4);
-		const completed = /* @__PURE__ */ new Set();
-		const done = /* @__PURE__ */ new Set();
-		const outputs = /* @__PURE__ */ new Map();
-		const rawOutputs = /* @__PURE__ */ new Map();
-		let executedCount = 0;
-		if (this.args.resumeFrom && !this.dagResumeConsumed) {
-			this.dagResumeConsumed = true;
-			executedCount = this.rehydrateDagState(dag, completed, done, outputs, rawOutputs);
-		}
-		while (done.size < dag.nodes.length) {
-			if (this.isAborted()) {
-				this.markCancelled();
-				this.skipDagRest(dag, done);
-				return;
-			}
-			const ready = readyNodes(dag, completed, done);
-			if (ready.length === 0) {
-				this.skipDagRest(dag, done);
-				return;
-			}
-			const batch = ready.slice(0, maxConcurrency);
-			const settled = await Promise.all(batch.map(async (node) => {
-				if (executedCount >= this.args.maxSteps) {
-					this.recordSkipped(node.index, node.step);
-					return {
-						node,
-						ran: false,
-						completed: false
-					};
-				}
-				executedCount++;
-				const previousOutputs = node.dependencies.map((dependency) => outputs.get(dependency));
-				const stepCompleted = await this.executeStep(node.index, node.step, previousOutputs);
-				if (stepCompleted) {
-					const rawOutput = this.snapshotFor(node.index)?.output;
-					rawOutputs.set(node.id, rawOutput);
-					outputs.set(node.id, this.stringifyOutput(node.step.capability, rawOutput));
-				}
-				return {
-					node,
-					ran: true,
-					completed: stepCompleted
-				};
-			}));
-			for (const entry of settled) {
-				done.add(entry.node.id);
-				if (entry.completed) completed.add(entry.node.id);
-			}
-			let replanFeedback;
-			let shouldAbort = false;
-			for (const entry of settled) {
-				if (!entry.ran) continue;
-				const snapshot = this.snapshotFor(entry.node.index);
-				const directive = snapshot ? await this.resolveDirective(snapshot, plan, entry.completed) : void 0;
-				if (directive?.type === "replan") replanFeedback = directive.feedback;
-				else if (directive?.type === "abort") shouldAbort = true;
-			}
-			if (shouldAbort) {
-				this.skipDagRest(dag, done);
-				return;
-			}
-			if (replanFeedback !== void 0) {
-				const remaining = await this.regeneratePlan(replanFeedback);
-				if (this.error || !remaining) {
-					this.skipDagRest(dag, done);
-					return;
-				}
-				return this.executeDag(remaining);
-			}
-		}
-		this.finalizeDagOutput(dag, completed, rawOutputs);
-	}
-	/**
-	* Dispatch one plan step through its capability's `executable.execute()`
-	* and fold the outcome into the accumulators. Returns `true` when the
-	* step completed, `false` when it failed (setting the run error).
-	*/
-	async executeStep(index, step, previousOutputs) {
-		const capability = this.args.capabilities.get(step.capability);
-		const stepStart = performance.now();
-		const startedAt = (/* @__PURE__ */ new Date()).toISOString();
-		const input = this.composeStepInput(step, previousOutputs);
-		const result = await withoutRunFrame(() => capability.executable.execute(input, {
-			signal: this.args.options?.signal,
-			sessionId: this.args.options?.sessionId
-		}));
-		const childReport = "report" in result ? result.report : void 0;
-		this.absorb(result.usage, childReport);
-		const output = this.extractOutput(result);
-		const failed = result.error !== void 0;
-		this.executedSteps.push({
-			index,
-			step,
-			status: failed ? "failed" : "completed",
-			output: failed ? void 0 : output,
-			error: result.error,
-			startedAt,
-			endedAt: (/* @__PURE__ */ new Date()).toISOString(),
-			duration: performance.now() - stepStart,
-			usage: result.usage,
-			childReport
-		});
-		await this.checkpoint("running");
-		if (failed) {
-			this.error = result.error;
-			return false;
-		}
-		previousOutputs.push(this.stringifyOutput(step.capability, output));
-		this.data = output;
-		return true;
-	}
-	/**
-	* Resolve the steering directive for a just-settled step, shared by the
-	* sequential and DAG executors. Fires the user's `onStep` hook, then
-	* normalizes the result against the `replan` budget:
-	*
-	* - explicit `replan` directive — honored only when `config.replan` is
-	*   set and the budget remains; otherwise downgraded to `continue`.
-	* - explicit `abort` — honored.
-	* - failed step with no overriding directive — auto-`replan` when
-	*   `config.replan` is set and the budget remains (feedback = the step
-	*   error message), else `abort` (today's abort-on-first-failure).
-	*
-	* Returns `undefined` when the run should simply continue. A returned
-	* `replan` directive has ALREADY consumed one unit of the replan budget.
-	*/
-	async resolveDirective(snapshot, plan, completed) {
-		const hook = this.args.options?.onStep;
-		const userDirective = hook ? await hook(snapshot, plan) : void 0;
-		if (userDirective?.type === "replan") {
-			if (this.canReplan()) {
-				this.replanCount++;
-				return userDirective;
-			}
-		} else if (userDirective?.type === "abort") return { type: "abort" };
-		else if (userDirective?.type === "continue") return;
-		if (!completed) {
-			if (this.canReplan()) {
-				this.replanCount++;
-				return {
-					type: "replan",
-					feedback: snapshot.error?.message ?? "step failed"
-				};
-			}
-			return { type: "abort" };
-		}
-	}
-	/** Whether a re-plan is configured and the budget has room. */
-	canReplan() {
-		const replan = this.args.config.replan;
-		return replan !== void 0 && this.replanCount < replan.maxReplans;
-	}
-	/**
-	* Re-ask the planning agent for a plan over the REMAINING work — a
-	* second `generatePlan()` seeded with the executed-step digest plus the
-	* caller's feedback. Reuses the exact `generatePlan` plumbing (same
-	* schema, same `PlannerPlanInvalidError` handling), so a regenerated
-	* plan that is empty or names an unknown capability fails identically.
-	* The failed step's error is cleared so the regenerated plan runs
-	* cleanly; a fresh failure (or exhausted budget) re-sets it.
-	*/
-	async regeneratePlan(feedback) {
-		this.error = void 0;
-		return this.generatePlan(feedback);
-	}
-	/**
-	* The executed-so-far digest — one context line per completed step, in
-	* execution order. Seeds the regenerated plan's first step so it builds
-	* on what already ran.
-	*/
-	executedDigest() {
-		return this.executedSteps.filter((snapshot) => snapshot.status === "completed").map((snapshot) => this.stringifyOutput(snapshot.step.capability, snapshot.output));
-	}
-	/** The last-pushed snapshot for a given step index, if any. */
-	snapshotFor(index) {
-		for (let position = this.executedSteps.length - 1; position >= 0; position--) {
-			const snapshot = this.executedSteps[position];
-			if (snapshot.index === index) return snapshot;
-		}
-	}
-	/** Record every step from `from` onward (in a flat array plan) as skipped. */
-	skipRest(steps, from) {
-		for (let rest = from; rest < steps.length; rest++) this.recordSkipped(rest, steps[rest]);
-	}
-	/** Record every not-yet-`done` DAG node as skipped, in plan order. */
-	skipDagRest(dag, done) {
-		for (const node of dag.nodes) if (!done.has(node.id)) this.recordSkipped(node.index, node.step);
-	}
-	/**
-	* Set `this.data` from the DAG's topological sink for a configured
-	* `output` schema. "Last completed step" is meaningless under
-	* parallelism, so the sink (the step nothing depends on) is the
-	* unambiguous final output. Multiple sinks while an `output` schema is
-	* set is a convergence error — a typed `PlannerPlanInvalidError`.
-	*/
-	finalizeDagOutput(dag, completed, rawOutputs) {
-		if (!(this.args.options?.output ?? this.args.config.output) || this.error) return;
-		const sinks = sinkNodes(dag).filter((node) => completed.has(node.id));
-		if (sinks.length > 1) {
-			this.error = new PlannerPlanInvalidError(`ai.planner("${this.args.config.name}"): DAG has multiple sinks but an \`output\` schema is set — the plan must converge to a single final step`, { context: {
-				runId: this.runId,
-				sinks: sinks.map((node) => node.id)
-			} });
-			this.data = void 0;
-			return;
-		}
-		const sink = sinks[0];
-		this.data = sink ? rawOutputs.get(sink.id) : void 0;
-	}
-	/**
-	* Phase 3 — when an `output` schema is configured (factory or per-call
-	* override), validate the final completed step's output into typed
-	* `result.data`. A validation failure replaces the run error and flips
-	* the status to failed.
-	*/
-	async finalizeOutput() {
-		const schema = this.args.options?.output ?? this.args.config.output;
-		if (!schema || this.error) return;
-		if (this.data === void 0) {
-			this.error = new PlannerPlanInvalidError(`ai.planner("${this.args.config.name}"): plan completed without producing output for the configured \`output\` schema`, { context: { runId: this.runId } });
-			return;
-		}
-		const validation = await schema["~standard"].validate(this.data);
-		if (validation.issues) {
-			this.error = new PlannerPlanInvalidError(`ai.planner("${this.args.config.name}"): final output failed validation`, { context: {
-				runId: this.runId,
-				issues: validation.issues.map((issue) => issue.message)
-			} });
-			this.data = void 0;
-			return;
-		}
-		this.data = validation.value;
-	}
-	/**
-	* Phase 4 — fold the accumulators into the planner's own
-	* {@link PlannerReport} node and the final {@link PlannerResult}, then
-	* stamp lineage across the whole subtree so every child shares this
-	* run's root id.
-	*/
-	buildResult() {
-		const status = this.resolveStatus();
-		const report = {
-			runId: this.runId,
-			rootRunId: this.runId,
-			name: this.args.config.name,
-			version: this.args.config.version,
-			type: "planner",
-			status,
-			...this.error ? { error: this.error } : {},
-			startedAt: this.startedAt,
-			endedAt: (/* @__PURE__ */ new Date()).toISOString(),
-			duration: performance.now() - this.startPerf,
-			usage: this.usage,
-			children: this.children,
-			signature: this.args.signature,
-			plan: this.plan,
-			executedSteps: this.executedSteps,
-			cancelledAt: this.cancelledAt,
-			reportSchemaVersion: 1
-		};
-		stampReportLineage(report, {
-			rootRunId: this.runId,
-			sessionId: this.args.options?.sessionId
-		});
-		const result = {
-			type: "planner",
-			data: this.error ? void 0 : this.data,
-			error: this.error,
-			usage: this.usage,
-			report
-		};
-		if (this.awaitingApproval) result.plan = this.plan;
-		return result;
-	}
-	/**
-	* Resolve the terminal status from the accumulated outcome.
-	* `awaiting-approval` (plan-only short-circuit) wins over everything —
-	* nothing executed, so neither cancellation nor error applies.
-	* Otherwise cancelled wins over failed (an abort that also produced a
-	* step error still reads as cancelled); failed wins over completed.
-	*/
-	resolveStatus() {
-		if (this.awaitingApproval) return "awaiting-approval";
-		if (this.cancelledAt !== void 0) return "cancelled";
-		if (this.error) return "failed";
-		return "completed";
-	}
-	/**
-	* Build the prompt handed to the planning agent. On the first pass this
-	* is just the user's goal (byte-for-byte unchanged). On a RE-plan it
-	* prepends the executed-step digest and the steering feedback so the
-	* planner revises the remaining work.
-	*/
-	buildPlanPrompt(feedback) {
-		if (feedback === void 0) return this.args.goal;
-		const digest = this.executedDigest();
-		const sections = [`Goal: ${this.args.goal}`, ""];
-		if (digest.length > 0) sections.push("Steps already completed:", ...digest, "");
-		sections.push(`Feedback requiring a revised plan: ${feedback}`, "", "Produce a plan for the REMAINING work only.");
-		return sections.join("\n");
-	}
-	/**
-	* Compose a step's effective input: the step's own `input`, prefixed
-	* with a compact digest of every prior step's output so a downstream
-	* capability can build on what ran before it. No prior output → the
-	* step's raw input.
-	*/
-	composeStepInput(step, previousOutputs) {
-		if (previousOutputs.length === 0) return step.input;
-		return [
-			"Context from earlier steps:",
-			...previousOutputs,
-			"",
-			`Task: ${step.input}`
-		].join("\n");
-	}
-	/**
-	* Pull the usable output off a capability's result. Prefers structured
-	* `data` (agents/workflows with an `output` schema, tools), and falls
-	* back to an agent's raw `text` when no structured data was produced —
-	* the common case for a plain text-producing capability agent.
-	*/
-	extractOutput(result) {
-		const shaped = result;
-		if (shaped.data !== void 0) return shaped.data;
-		if (typeof shaped.text === "string") return shaped.text;
-	}
-	/** Serialize a capability output into a single context line for the next step. */
-	stringifyOutput(capability, output) {
-		if (output === void 0) return `- ${capability}: (no output)`;
-		if (typeof output === "string") return `- ${capability}: ${output}`;
-		return `- ${capability}: ${JSON.stringify(output)}`;
-	}
-	/** Push a `skipped` snapshot for a step the planner never dispatched. */
-	recordSkipped(index, step) {
-		const now = (/* @__PURE__ */ new Date()).toISOString();
-		this.executedSteps.push({
-			index,
-			step,
-			status: "skipped",
-			startedAt: now,
-			endedAt: now,
-			duration: 0,
-			usage: {
-				input: 0,
-				output: 0,
-				total: 0
-			}
-		});
-	}
-	/** Fold a child's usage + report node into the planner's accumulators. */
-	absorb(usage, report) {
-		this.mergeUsage(this.usage, usage);
-		if (report) this.children.push(report);
-	}
-	/**
-	* Add a child's usage into the running total. Mirrors the batch
-	* primitive's rollup: scalar token channels sum directly, optional
-	* sub-channels accumulate only when reported, and the cost breakdown
-	* merges via {@link accumulateCost} so one unpriced child can't erase
-	* priced siblings.
-	*/
-	mergeUsage(target, child) {
-		target.input += child.input;
-		target.output += child.output;
-		target.total += child.total;
-		if (child.cachedTokens !== void 0) target.cachedTokens = (target.cachedTokens ?? 0) + child.cachedTokens;
-		if (child.reasoningTokens !== void 0) target.reasoningTokens = (target.reasoningTokens ?? 0) + child.reasoningTokens;
-		if (child.cacheWriteTokens !== void 0) target.cacheWriteTokens = (target.cacheWriteTokens ?? 0) + child.cacheWriteTokens;
-		const mergedCost = accumulateCost(target.cost, child.cost);
-		if (mergedCost !== void 0) target.cost = mergedCost;
-	}
-	/**
-	* Re-derive the sequential cursor + prior-output context from the
-	* persisted ledger on resume. Threads every already-`completed` node's
-	* output into `previousOutputs`, returns the first index NOT completed
-	* as the resume cursor, and prunes stale non-completed ledger entries
-	* (the failed node + any skipped tail) at-or-after that cursor so the
-	* re-run repopulates them without duplicating.
-	*/
-	rehydrateSequentialState(steps, previousOutputs) {
-		let cursor = 0;
-		for (let index = 0; index < steps.length; index++) {
-			const snapshot = this.snapshotFor(index);
-			if (snapshot?.status === "completed") {
-				const step = steps[index];
-				previousOutputs.push(this.stringifyOutput(step.capability, snapshot.output));
-				cursor = index + 1;
-				continue;
-			}
-			break;
-		}
-		this.pruneLedgerFrom(cursor);
-		return cursor;
-	}
-	/**
-	* Re-derive the DAG scheduler's working sets from the persisted ledger
-	* on resume. Completed nodes go into `completed` + `done` with their
-	* string + raw outputs restored (so dependents read the right context);
-	* stale non-completed entries are pruned so the re-run repopulates them.
-	* Returns the count of nodes already dispatched (for the `maxSteps`
-	* truncation budget).
-	*/
-	rehydrateDagState(dag, completed, done, outputs, rawOutputs) {
-		const completedIndices = /* @__PURE__ */ new Set();
-		for (const node of dag.nodes) {
-			const snapshot = this.snapshotFor(node.index);
-			if (snapshot?.status !== "completed") continue;
-			completed.add(node.id);
-			done.add(node.id);
-			completedIndices.add(node.index);
-			rawOutputs.set(node.id, snapshot.output);
-			outputs.set(node.id, this.stringifyOutput(node.step.capability, snapshot.output));
-		}
-		const retained = this.executedSteps.filter((snapshot) => completedIndices.has(snapshot.index));
-		this.executedSteps.length = 0;
-		this.executedSteps.push(...retained);
-		return completedIndices.size;
-	}
-	/**
-	* Drop every ledger entry whose index is at or after `from`. Used by
-	* the sequential resume re-seed to clear the crashed run's failed /
-	* skipped frontier before the re-run repopulates it.
-	*/
-	pruneLedgerFrom(from) {
-		const retained = this.executedSteps.filter((snapshot) => snapshot.index < from);
-		this.executedSteps.length = 0;
-		this.executedSteps.push(...retained);
-	}
-	/**
-	* Map the run's terminal outcome to the persisted snapshot status.
-	* `awaiting-approval` (plan-only) never persists a durable snapshot
-	* (resume is always an execution), so it folds to `running` here —
-	* but the durable + plan-only combination is disallowed at the call
-	* site, so this path is effectively unreachable.
-	*/
-	resolveSnapshotStatus() {
-		if (this.cancelledAt !== void 0) return "cancelled";
-		if (this.error) return "failed";
-		if (this.awaitingApproval) return "running";
-		return "completed";
-	}
-	/**
-	* Build and persist a {@link PlannerSnapshot} from the current
-	* accumulators. The per-node and terminal checkpoints both route
-	* through here. No-op when `durable` is absent. A failed persist is
-	* logged and swallowed (never aborts the run), matching the supervisor
-	* / workflow checkpoint policy.
-	*/
-	async checkpoint(status) {
-		if (!this.args.config.durable || !this.plan) return;
-		const outcome = await persistPlannerSnapshot({
-			durable: this.args.config.durable,
-			runId: this.runId,
-			plannerName: this.args.config.name,
-			signature: this.args.signature,
-			version: this.args.config.version,
-			goal: this.args.goal,
-			plan: this.plan,
-			executedSteps: this.executedSteps,
-			usage: this.usage,
-			children: this.children,
-			replanCount: this.replanCount,
-			status,
-			startedAt: this.startedAt
-		});
-		if (!outcome.ok) this.logDurableFailure("snapshot.persist.failed", outcome.error);
-	}
-	/**
-	* Re-derive the terminal state when a resume short-circuits a snapshot
-	* whose run already COMPLETED. The persisted ledger is the
-	* authoritative outcome — `this.data` is restored from the last
-	* completed node so the rebuilt result carries the final output.
-	*
-	* Only reached for a `completed` snapshot — `failed` / `cancelled`
-	* snapshots re-enter execution to retry the unfinished frontier instead.
-	*/
-	rebuildResumedTerminal(_status) {
-		const lastCompleted = [...this.executedSteps].reverse().find((snapshot) => snapshot.status === "completed");
-		if (lastCompleted) this.data = lastCompleted.output;
-	}
-	/** Structured-log a durable persist/delete failure. */
-	logDurableFailure(action, error) {
-		log.warn("ai.planner", action, "durable snapshot operation failed", {
-			runId: this.runId,
-			planner: this.args.config.name,
-			error: error instanceof Error ? error.message : String(error)
-		});
-	}
-	/** Whether the caller's abort signal has fired. */
-	isAborted() {
-		return this.args.options?.signal?.aborted === true;
-	}
-	/** Record a cancellation observation, setting the run error once. */
-	markCancelled() {
-		if (this.cancelledAt !== void 0) return;
-		this.cancelledAt = (/* @__PURE__ */ new Date()).toISOString();
-		const reason = this.args.options?.signal?.reason;
-		this.error = new PlannerCancelledError(`ai.planner("${this.args.config.name}"): run cancelled`, {
-			cancelledAt: this.cancelledAt,
-			reason: typeof reason === "string" ? reason : void 0,
-			context: { runId: this.runId }
-		});
-	}
-	/** Normalize any thrown value into a typed {@link AIError}. */
-	toAIError(caught) {
-		if (caught instanceof AIError) return caught;
-		const message = caught instanceof Error ? caught.message : String(caught);
-		return new PlannerFailedError(`ai.planner("${this.args.config.name}"): ${message}`, {
-			cause: caught,
-			context: { runId: this.runId }
-		});
-	}
-};
-
-//#endregion
-export { PlannerRun };
-//# sourceMappingURL=planner-run.mjs.map