@warlock.js/ai 4.2.10 → 4.3.0

package/esm/planner/planner-run.d.mts

@@ -0,0 +1,23 @@
+import { AgentContract } from "../contracts/agent/agent.contract.mjs";
+import { PlannerCapability } from "../contracts/planner/planner-capability.type.mjs";
+import { PlannerConfig } from "../contracts/planner/planner-config.type.mjs";
+import { PlannerExecuteOptions } from "../contracts/planner/planner-execute-options.type.mjs";
+
+//#region ../@warlock.js/ai/src/planner/planner-run.d.ts
+/**
+ * Construction args for one {@link PlannerRun}. Carries everything the
+ * factory resolved once (config, capability map, signature, planning
+ * agent) plus the per-call goal and options.
+ */
+type PlannerRunArgs<TOutput> = {
+  config: PlannerConfig<TOutput>;
+  capabilities: Map<string, PlannerCapability>;
+  maxSteps: number;
+  signature: string;
+  planningAgent: AgentContract<unknown>;
+  goal: string;
+  options?: PlannerExecuteOptions<TOutput>;
+};
+//#endregion
+export { PlannerRunArgs };
+//# sourceMappingURL=planner-run.d.mts.map

package/esm/planner/planner-run.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-run.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/planner/planner-run.ts"],"mappings":";;;;;;;AA8BA;;;;KAAY,cAAA;EACV,MAAA,EAAQ,aAAA,CAAc,OAAA;EACtB,YAAA,EAAc,GAAA,SAAY,iBAAA;EAC1B,QAAA;EACA,SAAA;EACA,aAAA,EAAe,aAAA;EACf,IAAA;EACA,OAAA,GAAU,qBAAA,CAAsB,OAAA;AAAA"}

package/esm/planner/planner-run.mjs

@@ -0,0 +1,344 @@
+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 { REPORT_SCHEMA_VERSION } from "../contracts/result/base-report.type.mjs";
+import { stampReportLineage } from "../utils/stamp-report-lineage.mjs";
+import { planSchema } from "./plan-schema.mjs";
+
+//#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.runId = args.options?.runId ?? generateRunId("planner");
+	}
+	/**
+	* 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() {
+		try {
+			if (this.isAborted()) {
+				this.markCancelled();
+				return this.buildResult();
+			}
+			const plan = await this.generatePlan();
+			if (this.error || !plan) return this.buildResult();
+			this.plan = plan;
+			await this.executePlan(plan);
+			await this.finalizeOutput();
+		} catch (caught) {
+			this.error = this.toAIError(caught);
+		}
+		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.
+	*/
+	async generatePlan() {
+		const schema = planSchema([...this.args.capabilities.keys()], this.args.maxSteps);
+		const result = await this.args.planningAgent.execute(this.buildPlanPrompt(), {
+			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;
+		}
+		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
+			} });
+			return;
+		}
+		return plan;
+	}
+	/**
+	* Phase 2 — execute the plan's steps strictly in order, threading each
+	* completed step's output into the next step's input context. Stops at
+	* the first step failure (its `error` becomes the run error) or when
+	* the abort signal fires between steps. Steps beyond `maxSteps` are
+	* recorded as `skipped` without running.
+	*/
+	async executePlan(plan) {
+		const previousOutputs = [];
+		for (let index = 0; index < plan.steps.length; index++) {
+			const step = plan.steps[index];
+			if (index >= this.args.maxSteps) {
+				this.recordSkipped(index, step);
+				continue;
+			}
+			if (this.isAborted()) {
+				this.markCancelled();
+				this.recordSkipped(index, step);
+				continue;
+			}
+			if (!await this.executeStep(index, step, previousOutputs)) {
+				for (let rest = index + 1; rest < plan.steps.length; rest++) this.recordSkipped(rest, plan.steps[rest]);
+				return;
+			}
+		}
+	}
+	/**
+	* 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 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
+		});
+		if (failed) {
+			this.error = result.error;
+			return false;
+		}
+		previousOutputs.push(this.stringifyOutput(step.capability, output));
+		this.data = output;
+		return true;
+	}
+	/**
+	* 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,
+			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
+		});
+		return {
+			type: "planner",
+			data: this.error ? void 0 : this.data,
+			error: this.error,
+			usage: this.usage,
+			report
+		};
+	}
+	/**
+	* Resolve the terminal status from the accumulated outcome. Cancelled
+	* wins over failed (an abort that also produced a step error still
+	* reads as cancelled); failed wins over completed.
+	*/
+	resolveStatus() {
+		if (this.cancelledAt !== void 0) return "cancelled";
+		if (this.error) return "failed";
+		return "completed";
+	}
+	/** Build the prompt handed to the planning agent — the user's goal. */
+	buildPlanPrompt() {
+		return this.args.goal;
+	}
+	/**
+	* 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;
+	}
+	/** 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

package/esm/planner/planner-run.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-run.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/planner/planner-run.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { AgentContract } from \"../contracts/agent/agent.contract\";\nimport type { PlannerCapability } from \"../contracts/planner/planner-capability.type\";\nimport type { PlannerConfig } from \"../contracts/planner/planner-config.type\";\nimport type { PlannerExecuteOptions } from \"../contracts/planner/planner-execute-options.type\";\nimport type { PlannerPlan, PlannerStep } from \"../contracts/planner/planner-plan.type\";\nimport type {\n  PlannerReport,\n  PlannerResult,\n  PlannerStepSnapshot,\n} from \"../contracts/planner/planner-result.type\";\nimport type { BaseReport } from \"../contracts/result/base-report.type\";\nimport { REPORT_SCHEMA_VERSION } from \"../contracts/result/base-report.type\";\nimport type { BaseResult } from \"../contracts/result/base-result.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport { AIError } from \"../errors/ai-error\";\nimport { PlannerCancelledError } from \"../errors/planner-cancelled-error\";\nimport { PlannerFailedError } from \"../errors/planner-failed-error\";\nimport { PlannerPlanInvalidError } from \"../errors/planner-plan-invalid-error\";\nimport { SchemaValidationError } from \"../errors/schema-validation-error\";\nimport { accumulateCost } from \"../utils/compute-cost\";\nimport { generateRunId } from \"../utils/generate-run-id\";\nimport { stampReportLineage } from \"../utils/stamp-report-lineage\";\nimport { planSchema } from \"./plan-schema\";\n\n/**\n * Construction args for one {@link PlannerRun}. Carries everything the\n * factory resolved once (config, capability map, signature, planning\n * agent) plus the per-call goal and options.\n */\nexport type PlannerRunArgs<TOutput> = {\n  config: PlannerConfig<TOutput>;\n  capabilities: Map<string, PlannerCapability>;\n  maxSteps: number;\n  signature: string;\n  planningAgent: AgentContract<unknown>;\n  goal: string;\n  options?: PlannerExecuteOptions<TOutput>;\n};\n\n/**\n * Per-call orchestration state for one `planner.execute()` invocation.\n *\n * **Role.** Owns the full bounded-v1 planning lifecycle across four\n * phases that share mutable accumulators: (1) ask the LLM to GENERATE a\n * plan, (2) execute each plan step through its capability's `execute()`,\n * (3) optionally validate the final output, (4) assemble the unified\n * {@link PlannerResult}. Instantiated fresh per call inside the factory\n * so the accumulators (`usage`, `children`, `executedSteps`) are never\n * shared across runs. Unexported — callers only ever see the plain\n * {@link PlannerResult}.\n *\n * **Composition, not a fork.** Plan generation runs through a normal\n * `agent.execute()`; each step runs through the capability's own\n * `executable.execute()`. The planner adds the plan-generation brain and\n * the ordered-dispatch loop on top of the existing executable machinery —\n * it does not reimplement agent or step internals.\n */\nexport class PlannerRun<TOutput> {\n  private readonly runId: string;\n  private readonly startedAt = new Date().toISOString();\n  private readonly startPerf = performance.now();\n\n  private readonly usage: Usage = { input: 0, output: 0, total: 0 };\n  private readonly children: BaseReport[] = [];\n  private readonly executedSteps: PlannerStepSnapshot[] = [];\n\n  private plan?: PlannerPlan;\n  private data?: TOutput;\n  private error?: AIError;\n  private cancelledAt?: string;\n\n  public constructor(private readonly args: PlannerRunArgs<TOutput>) {\n    this.runId = args.options?.runId ?? generateRunId(\"planner\");\n  }\n\n  /**\n   * Run the planner end-to-end. Never throws on runtime failure —\n   * generation errors, plan-validity errors, step failures, and\n   * cancellation all surface on `result.error` with a narrowing\n   * `report.status`.\n   */\n  public async run(): Promise<PlannerResult<TOutput>> {\n    try {\n      if (this.isAborted()) {\n        this.markCancelled();\n        return this.buildResult();\n      }\n\n      const plan = await this.generatePlan();\n\n      if (this.error || !plan) {\n        return this.buildResult();\n      }\n\n      this.plan = plan;\n\n      await this.executePlan(plan);\n\n      await this.finalizeOutput();\n    } catch (caught) {\n      this.error = this.toAIError(caught);\n    }\n\n    return this.buildResult();\n  }\n\n  /**\n   * Phase 1 — ask the planning agent for a structured plan. The plan\n   * schema (built from the live capability names) is supplied as the\n   * agent's per-call `output`, so the model is steered to reference only\n   * real capabilities. The planning trip's usage + report roll into the\n   * planner's totals regardless of outcome.\n   */\n  private async generatePlan(): Promise<PlannerPlan | undefined> {\n    const schema = planSchema([...this.args.capabilities.keys()], this.args.maxSteps);\n\n    const result = await this.args.planningAgent.execute(this.buildPlanPrompt(), {\n      output: schema as StandardSchemaV1<unknown>,\n      placeholders: this.args.options?.placeholders,\n      signal: this.args.options?.signal,\n      sessionId: this.args.options?.sessionId,\n    });\n\n    this.absorb(result.usage, result.report);\n\n    if (result.error) {\n      // A schema rejection from the planning trip (e.g. an empty\n      // `steps` array tripping the plan schema) is really an invalid\n      // plan — re-wrap it into the typed planner contract so callers\n      // branch on `PlannerPlanInvalidError` rather than the agent's raw\n      // `SchemaValidationError`. Any other child error flows through\n      // unchanged.\n      this.error =\n        result.error instanceof SchemaValidationError\n          ? new PlannerPlanInvalidError(\n              `ai.planner(\"${this.args.config.name}\"): the planner produced no usable plan`,\n              { cause: result.error, context: { runId: this.runId } },\n            )\n          : result.error;\n      return undefined;\n    }\n\n    const plan = result.data as PlannerPlan | undefined;\n\n    if (!plan || !Array.isArray(plan.steps) || plan.steps.length === 0) {\n      this.error = new PlannerPlanInvalidError(\n        `ai.planner(\"${this.args.config.name}\"): the planner produced no usable plan`,\n        { context: { runId: this.runId } },\n      );\n      return undefined;\n    }\n\n    const unknownStep = plan.steps.find((step) => !this.args.capabilities.has(step.capability));\n\n    if (unknownStep) {\n      this.error = new PlannerPlanInvalidError(\n        `ai.planner(\"${this.args.config.name}\"): plan references unknown capability \"${unknownStep.capability}\"`,\n        { context: { runId: this.runId, capability: unknownStep.capability } },\n      );\n      return undefined;\n    }\n\n    return plan;\n  }\n\n  /**\n   * Phase 2 — execute the plan's steps strictly in order, threading each\n   * completed step's output into the next step's input context. Stops at\n   * the first step failure (its `error` becomes the run error) or when\n   * the abort signal fires between steps. Steps beyond `maxSteps` are\n   * recorded as `skipped` without running.\n   */\n  private async executePlan(plan: PlannerPlan): Promise<void> {\n    const previousOutputs: string[] = [];\n\n    for (let index = 0; index < plan.steps.length; index++) {\n      const step = plan.steps[index] as PlannerStep;\n\n      if (index >= this.args.maxSteps) {\n        this.recordSkipped(index, step);\n        continue;\n      }\n\n      if (this.isAborted()) {\n        this.markCancelled();\n        this.recordSkipped(index, step);\n        continue;\n      }\n\n      const completed = await this.executeStep(index, step, previousOutputs);\n\n      if (!completed) {\n        // Step failed — record the remaining steps as skipped so the\n        // report still describes the whole intended plan, then stop.\n        for (let rest = index + 1; rest < plan.steps.length; rest++) {\n          this.recordSkipped(rest, plan.steps[rest] as PlannerStep);\n        }\n        return;\n      }\n    }\n  }\n\n  /**\n   * Dispatch one plan step through its capability's `executable.execute()`\n   * and fold the outcome into the accumulators. Returns `true` when the\n   * step completed, `false` when it failed (setting the run error).\n   */\n  private async executeStep(\n    index: number,\n    step: PlannerStep,\n    previousOutputs: string[],\n  ): Promise<boolean> {\n    const capability = this.args.capabilities.get(step.capability) as PlannerCapability;\n    const stepStart = performance.now();\n    const startedAt = new Date().toISOString();\n    const input = this.composeStepInput(step, previousOutputs);\n\n    const result = await capability.executable.execute(input, {\n      signal: this.args.options?.signal,\n      sessionId: this.args.options?.sessionId,\n    });\n\n    const childReport = \"report\" in result ? (result.report as BaseReport) : undefined;\n    this.absorb(result.usage, childReport);\n\n    const output = this.extractOutput(result);\n    const failed = result.error !== undefined;\n\n    this.executedSteps.push({\n      index,\n      step,\n      status: failed ? \"failed\" : \"completed\",\n      output: failed ? undefined : output,\n      error: result.error,\n      startedAt,\n      endedAt: new Date().toISOString(),\n      duration: performance.now() - stepStart,\n      usage: result.usage,\n      childReport,\n    });\n\n    if (failed) {\n      this.error = result.error;\n      return false;\n    }\n\n    previousOutputs.push(this.stringifyOutput(step.capability, output));\n    this.data = output as TOutput;\n\n    return true;\n  }\n\n  /**\n   * Phase 3 — when an `output` schema is configured (factory or per-call\n   * override), validate the final completed step's output into typed\n   * `result.data`. A validation failure replaces the run error and flips\n   * the status to failed.\n   */\n  private async finalizeOutput(): Promise<void> {\n    const schema = this.args.options?.output ?? this.args.config.output;\n\n    if (!schema || this.error) {\n      return;\n    }\n\n    if (this.data === undefined) {\n      // An `output` schema is configured but the final completed step\n      // produced nothing to validate — returning `{ data: undefined,\n      // error: undefined, status: \"completed\" }` would be a silent\n      // contract violation. Surface it as an invalid plan instead.\n      this.error = new PlannerPlanInvalidError(\n        `ai.planner(\"${this.args.config.name}\"): plan completed without producing output for the configured \\`output\\` schema`,\n        { context: { runId: this.runId } },\n      );\n      return;\n    }\n\n    const validation = await schema[\"~standard\"].validate(this.data);\n\n    if (validation.issues) {\n      this.error = new PlannerPlanInvalidError(\n        `ai.planner(\"${this.args.config.name}\"): final output failed validation`,\n        {\n          context: {\n            runId: this.runId,\n            issues: validation.issues.map((issue) => issue.message),\n          },\n        },\n      );\n      this.data = undefined;\n      return;\n    }\n\n    this.data = validation.value as TOutput;\n  }\n\n  /**\n   * Phase 4 — fold the accumulators into the planner's own\n   * {@link PlannerReport} node and the final {@link PlannerResult}, then\n   * stamp lineage across the whole subtree so every child shares this\n   * run's root id.\n   */\n  private buildResult(): PlannerResult<TOutput> {\n    const status = this.resolveStatus();\n\n    const report: PlannerReport = {\n      runId: this.runId,\n      rootRunId: this.runId,\n      name: this.args.config.name,\n      version: this.args.config.version,\n      type: \"planner\",\n      status,\n      startedAt: this.startedAt,\n      endedAt: new Date().toISOString(),\n      duration: performance.now() - this.startPerf,\n      usage: this.usage,\n      children: this.children,\n      signature: this.args.signature,\n      plan: this.plan,\n      executedSteps: this.executedSteps,\n      cancelledAt: this.cancelledAt,\n      reportSchemaVersion: REPORT_SCHEMA_VERSION,\n    };\n\n    stampReportLineage(report, {\n      rootRunId: this.runId,\n      sessionId: this.args.options?.sessionId,\n    });\n\n    return {\n      type: \"planner\",\n      data: this.error ? undefined : this.data,\n      error: this.error,\n      usage: this.usage,\n      report,\n    };\n  }\n\n  /**\n   * Resolve the terminal status from the accumulated outcome. Cancelled\n   * wins over failed (an abort that also produced a step error still\n   * reads as cancelled); failed wins over completed.\n   */\n  private resolveStatus(): PlannerReport[\"status\"] {\n    if (this.cancelledAt !== undefined) {\n      return \"cancelled\";\n    }\n\n    if (this.error) {\n      return \"failed\";\n    }\n\n    return \"completed\";\n  }\n\n  /** Build the prompt handed to the planning agent — the user's goal. */\n  private buildPlanPrompt(): string {\n    return this.args.goal;\n  }\n\n  /**\n   * Compose a step's effective input: the step's own `input`, prefixed\n   * with a compact digest of every prior step's output so a downstream\n   * capability can build on what ran before it. No prior output → the\n   * step's raw input.\n   */\n  private composeStepInput(step: PlannerStep, previousOutputs: string[]): string {\n    if (previousOutputs.length === 0) {\n      return step.input;\n    }\n\n    return [\n      \"Context from earlier steps:\",\n      ...previousOutputs,\n      \"\",\n      `Task: ${step.input}`,\n    ].join(\"\\n\");\n  }\n\n  /**\n   * Pull the usable output off a capability's result. Prefers structured\n   * `data` (agents/workflows with an `output` schema, tools), and falls\n   * back to an agent's raw `text` when no structured data was produced —\n   * the common case for a plain text-producing capability agent.\n   */\n  private extractOutput(result: BaseResult): unknown {\n    const shaped = result as { data?: unknown; text?: unknown };\n\n    if (shaped.data !== undefined) {\n      return shaped.data;\n    }\n\n    if (typeof shaped.text === \"string\") {\n      return shaped.text;\n    }\n\n    return undefined;\n  }\n\n  /** Serialize a capability output into a single context line for the next step. */\n  private stringifyOutput(capability: string, output: unknown): string {\n    if (output === undefined) {\n      return `- ${capability}: (no output)`;\n    }\n\n    if (typeof output === \"string\") {\n      return `- ${capability}: ${output}`;\n    }\n\n    return `- ${capability}: ${JSON.stringify(output)}`;\n  }\n\n  /** Push a `skipped` snapshot for a step the planner never dispatched. */\n  private recordSkipped(index: number, step: PlannerStep): void {\n    const now = new Date().toISOString();\n\n    this.executedSteps.push({\n      index,\n      step,\n      status: \"skipped\",\n      startedAt: now,\n      endedAt: now,\n      duration: 0,\n      usage: { input: 0, output: 0, total: 0 },\n    });\n  }\n\n  /** Fold a child's usage + report node into the planner's accumulators. */\n  private absorb(usage: Usage, report: BaseReport | undefined): void {\n    this.mergeUsage(this.usage, usage);\n\n    if (report) {\n      this.children.push(report);\n    }\n  }\n\n  /**\n   * Add a child's usage into the running total. Mirrors the batch\n   * primitive's rollup: scalar token channels sum directly, optional\n   * sub-channels accumulate only when reported, and the cost breakdown\n   * merges via {@link accumulateCost} so one unpriced child can't erase\n   * priced siblings.\n   */\n  private mergeUsage(target: Usage, child: Usage): void {\n    target.input += child.input;\n    target.output += child.output;\n    target.total += child.total;\n\n    if (child.cachedTokens !== undefined) {\n      target.cachedTokens = (target.cachedTokens ?? 0) + child.cachedTokens;\n    }\n\n    if (child.reasoningTokens !== undefined) {\n      target.reasoningTokens = (target.reasoningTokens ?? 0) + child.reasoningTokens;\n    }\n\n    if (child.cacheWriteTokens !== undefined) {\n      target.cacheWriteTokens = (target.cacheWriteTokens ?? 0) + child.cacheWriteTokens;\n    }\n\n    const mergedCost = accumulateCost(target.cost, child.cost);\n\n    if (mergedCost !== undefined) {\n      target.cost = mergedCost;\n    }\n  }\n\n  /** Whether the caller's abort signal has fired. */\n  private isAborted(): boolean {\n    return this.args.options?.signal?.aborted === true;\n  }\n\n  /** Record a cancellation observation, setting the run error once. */\n  private markCancelled(): void {\n    if (this.cancelledAt !== undefined) {\n      return;\n    }\n\n    this.cancelledAt = new Date().toISOString();\n\n    const reason = this.args.options?.signal?.reason;\n\n    this.error = new PlannerCancelledError(\n      `ai.planner(\"${this.args.config.name}\"): run cancelled`,\n      {\n        cancelledAt: this.cancelledAt,\n        reason: typeof reason === \"string\" ? reason : undefined,\n        context: { runId: this.runId },\n      },\n    );\n  }\n\n  /** Normalize any thrown value into a typed {@link AIError}. */\n  private toAIError(caught: unknown): AIError {\n    if (caught instanceof AIError) {\n      return caught;\n    }\n\n    const message = caught instanceof Error ? caught.message : String(caught);\n\n    return new PlannerFailedError(`ai.planner(\"${this.args.config.name}\"): ${message}`, {\n      cause: caught,\n      context: { runId: this.runId },\n    });\n  }\n}\n"],"mappings":"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"}

package/esm/planner/planner.d.mts

@@ -0,0 +1,37 @@
+import { PlannerConfig } from "../contracts/planner/planner-config.type.mjs";
+import { PlannerContract } from "../contracts/planner/planner.contract.mjs";
+
+//#region ../@warlock.js/ai/src/planner/planner.d.ts
+/**
+ * `ai.planner(config)` — construct a {@link PlannerContract}.
+ *
+ * Validates the config at author time (throws {@link PlannerFailedError}
+ * on a bad shape), builds (or adopts) the plan-generation agent, computes
+ * a stable structural signature, and returns an instance satisfying
+ * `ExecutableContract` so the planner composes into supervisors,
+ * orchestrators, and outer agents through the same uniform surface.
+ *
+ * At `execute(goal)` the planner asks its LLM for an ordered plan over
+ * the registered `capabilities`, then executes that plan step-by-step
+ * through each capability's own `execute()` — reusing the existing
+ * executable machinery rather than forking it — and returns the unified
+ * `{ data, report, usage, error }` envelope with `report.type ===
+ * "planner"`.
+ *
+ * @example
+ * const research = ai.planner({
+ *   name: "research-assistant",
+ *   model: ai.openai.model({ name: "gpt-4o" }),
+ *   capabilities: [
+ *     { name: "search", description: "Search the web", executable: searchAgent },
+ *     { name: "write", description: "Draft a summary", executable: writerAgent },
+ *   ],
+ *   maxSteps: 6,
+ * });
+ *
+ * const { data, report } = await research.execute("Compare React vs Vue in 2026");
+ */
+declare function planner<TOutput = unknown>(config: PlannerConfig<TOutput>): PlannerContract<TOutput>;
+//#endregion
+export { planner };
+//# sourceMappingURL=planner.d.mts.map

package/esm/planner/planner.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/planner/planner.ts"],"mappings":";;;;;;AA4CA;;;;;;;;;;;;;;;;AAE0B;;;;;;;;;;;iBAFV,OAAA,oBACd,MAAA,EAAQ,aAAA,CAAc,OAAA,IACrB,eAAA,CAAgB,OAAA"}

package/esm/planner/planner.mjs

@@ -0,0 +1,120 @@
+import { PlannerFailedError } from "../errors/planner-failed-error.mjs";
+import "../errors/index.mjs";
+import { agent } from "../agent/agent.mjs";
+import { buildPlanSystemPrompt } from "./plan-prompt.mjs";
+import { PlannerRun } from "./planner-run.mjs";
+import { computeSignature } from "./signature.mjs";
+import { log } from "@warlock.js/logger";
+
+//#region ../@warlock.js/ai/src/planner/planner.ts
+const LOG_MODULE = "ai.planner";
+/**
+* `ai.planner(config)` — construct a {@link PlannerContract}.
+*
+* Validates the config at author time (throws {@link PlannerFailedError}
+* on a bad shape), builds (or adopts) the plan-generation agent, computes
+* a stable structural signature, and returns an instance satisfying
+* `ExecutableContract` so the planner composes into supervisors,
+* orchestrators, and outer agents through the same uniform surface.
+*
+* At `execute(goal)` the planner asks its LLM for an ordered plan over
+* the registered `capabilities`, then executes that plan step-by-step
+* through each capability's own `execute()` — reusing the existing
+* executable machinery rather than forking it — and returns the unified
+* `{ data, report, usage, error }` envelope with `report.type ===
+* "planner"`.
+*
+* @example
+* const research = ai.planner({
+*   name: "research-assistant",
+*   model: ai.openai.model({ name: "gpt-4o" }),
+*   capabilities: [
+*     { name: "search", description: "Search the web", executable: searchAgent },
+*     { name: "write", description: "Draft a summary", executable: writerAgent },
+*   ],
+*   maxSteps: 6,
+* });
+*
+* const { data, report } = await research.execute("Compare React vs Vue in 2026");
+*/
+function planner(config) {
+	validateConfig(config);
+	const maxSteps = config.maxSteps ?? 10;
+	const capabilities = /* @__PURE__ */ new Map();
+	for (const capability of config.capabilities) capabilities.set(capability.name, capability);
+	const signature = computeSignature(config.name, config.capabilities);
+	const planningAgent = resolvePlanningAgent(config, maxSteps);
+	async function execute(goal, options) {
+		log.debug(LOG_MODULE, "execute", "Planner run starting", {
+			name: config.name,
+			capabilities: capabilities.size
+		});
+		return new PlannerRun({
+			config,
+			capabilities,
+			maxSteps,
+			signature,
+			planningAgent,
+			goal,
+			options
+		}).run();
+	}
+	return {
+		name: config.name,
+		signature,
+		execute
+	};
+}
+/**
+* Resolve the plan-generation agent: either adopt the dev's `planner`
+* agent, or build an internal one from `model` with the generated
+* plan-system-prompt baked on. The plan output schema is supplied
+* per-call in {@link PlannerRun}, so it isn't baked here.
+*
+* **`maxSteps` and BYO planners.** In `model` mode the cap is woven
+* into the generated plan-system-prompt *and* the per-call plan schema
+* (`steps.maxItems`). In `planner` (BYO) mode the dev owns the prompt,
+* so the cap is communicated only through that same per-call schema —
+* and, regardless of mode, {@link PlannerRun} truncates any over-long
+* plan to `skipped` at execution time, so the cap is always enforced.
+*/
+function resolvePlanningAgent(config, maxSteps) {
+	if (config.planner) return config.planner;
+	const systemPrompt = buildPlanSystemPrompt(config.capabilities, maxSteps, config.systemPrompt);
+	return agent({
+		name: `${config.name}-planner`,
+		description: "Generates an ordered execution plan over the planner's capabilities.",
+		model: config.model,
+		systemPrompt,
+		maxTrips: 1
+	});
+}
+/**
+* Factory-time validation. Surfaces every violation as a typed
+* {@link PlannerFailedError} tagged `authoring: true`, mirroring the
+* supervisor/orchestrator authoring-error convention.
+*/
+function validateConfig(config) {
+	if (!config.name || typeof config.name !== "string") throw new PlannerFailedError("ai.planner: `name` is required and must be a string", { context: { authoring: true } });
+	const hasModel = config.model !== void 0;
+	const hasPlanner = config.planner !== void 0;
+	if (!hasModel && !hasPlanner) throw new PlannerFailedError(`ai.planner("${config.name}"): one of \`model\` or \`planner\` is required`, { context: { authoring: true } });
+	if (hasModel && hasPlanner) throw new PlannerFailedError(`ai.planner("${config.name}"): \`model\` and \`planner\` are mutually exclusive — configure exactly one`, { context: { authoring: true } });
+	if (!Array.isArray(config.capabilities) || config.capabilities.length === 0) throw new PlannerFailedError(`ai.planner("${config.name}"): at least one capability is required`, { context: { authoring: true } });
+	const seen = /* @__PURE__ */ new Set();
+	for (const capability of config.capabilities) {
+		if (!capability || typeof capability.name !== "string" || capability.name.length === 0) throw new PlannerFailedError(`ai.planner("${config.name}"): every capability needs a non-empty \`name\``, { context: { authoring: true } });
+		if (typeof capability.description !== "string" || capability.description.length === 0) throw new PlannerFailedError(`ai.planner("${config.name}"): capability "${capability.name}" needs a \`description\``, { context: { authoring: true } });
+		if (!capability.executable || typeof capability.executable.execute !== "function") throw new PlannerFailedError(`ai.planner("${config.name}"): capability "${capability.name}" needs an \`executable\` with an execute() method`, { context: { authoring: true } });
+		if (seen.has(capability.name)) throw new PlannerFailedError(`ai.planner("${config.name}"): duplicate capability name "${capability.name}"`, { context: { authoring: true } });
+		seen.add(capability.name);
+	}
+	if (config.maxSteps !== void 0 && config.maxSteps < 1) throw new PlannerFailedError(`ai.planner("${config.name}"): \`maxSteps\` must be >= 1`, { context: {
+		authoring: true,
+		maxSteps: config.maxSteps
+	} });
+}
+
+//#endregion
+export { planner };
+//# sourceMappingURL=planner.mjs.map

package/esm/planner/planner.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/planner/planner.ts"],"sourcesContent":["import { log } from \"@warlock.js/logger\";\nimport { agent } from \"../agent/agent\";\nimport type { AgentContract } from \"../contracts/agent/agent.contract\";\nimport type { PlannerCapability } from \"../contracts/planner/planner-capability.type\";\nimport type { PlannerConfig } from \"../contracts/planner/planner-config.type\";\nimport type { PlannerExecuteOptions } from \"../contracts/planner/planner-execute-options.type\";\nimport type { PlannerResult } from \"../contracts/planner/planner-result.type\";\nimport type { PlannerContract } from \"../contracts/planner/planner.contract\";\nimport { PlannerFailedError } from \"../errors\";\nimport { buildPlanSystemPrompt } from \"./plan-prompt\";\nimport { PlannerRun } from \"./planner-run\";\nimport { computeSignature } from \"./signature\";\n\nconst LOG_MODULE = \"ai.planner\";\n\n/**\n * `ai.planner(config)` — construct a {@link PlannerContract}.\n *\n * Validates the config at author time (throws {@link PlannerFailedError}\n * on a bad shape), builds (or adopts) the plan-generation agent, computes\n * a stable structural signature, and returns an instance satisfying\n * `ExecutableContract` so the planner composes into supervisors,\n * orchestrators, and outer agents through the same uniform surface.\n *\n * At `execute(goal)` the planner asks its LLM for an ordered plan over\n * the registered `capabilities`, then executes that plan step-by-step\n * through each capability's own `execute()` — reusing the existing\n * executable machinery rather than forking it — and returns the unified\n * `{ data, report, usage, error }` envelope with `report.type ===\n * \"planner\"`.\n *\n * @example\n * const research = ai.planner({\n *   name: \"research-assistant\",\n *   model: ai.openai.model({ name: \"gpt-4o\" }),\n *   capabilities: [\n *     { name: \"search\", description: \"Search the web\", executable: searchAgent },\n *     { name: \"write\", description: \"Draft a summary\", executable: writerAgent },\n *   ],\n *   maxSteps: 6,\n * });\n *\n * const { data, report } = await research.execute(\"Compare React vs Vue in 2026\");\n */\nexport function planner<TOutput = unknown>(\n  config: PlannerConfig<TOutput>,\n): PlannerContract<TOutput> {\n  validateConfig(config);\n\n  const maxSteps = config.maxSteps ?? 10;\n  const capabilities = new Map<string, PlannerCapability>();\n\n  for (const capability of config.capabilities) {\n    capabilities.set(capability.name, capability);\n  }\n\n  const signature = computeSignature(config.name, config.capabilities);\n  const planningAgent = resolvePlanningAgent(config, maxSteps);\n\n  async function execute(\n    goal: string,\n    options?: PlannerExecuteOptions<TOutput>,\n  ): Promise<PlannerResult<TOutput>> {\n    log.debug(LOG_MODULE, \"execute\", \"Planner run starting\", {\n      name: config.name,\n      capabilities: capabilities.size,\n    });\n\n    return new PlannerRun<TOutput>({\n      config,\n      capabilities,\n      maxSteps,\n      signature,\n      planningAgent,\n      goal,\n      options,\n    }).run();\n  }\n\n  return {\n    name: config.name,\n    signature,\n    execute,\n  };\n}\n\n/**\n * Resolve the plan-generation agent: either adopt the dev's `planner`\n * agent, or build an internal one from `model` with the generated\n * plan-system-prompt baked on. The plan output schema is supplied\n * per-call in {@link PlannerRun}, so it isn't baked here.\n *\n * **`maxSteps` and BYO planners.** In `model` mode the cap is woven\n * into the generated plan-system-prompt *and* the per-call plan schema\n * (`steps.maxItems`). In `planner` (BYO) mode the dev owns the prompt,\n * so the cap is communicated only through that same per-call schema —\n * and, regardless of mode, {@link PlannerRun} truncates any over-long\n * plan to `skipped` at execution time, so the cap is always enforced.\n */\nfunction resolvePlanningAgent<TOutput>(\n  config: PlannerConfig<TOutput>,\n  maxSteps: number,\n): AgentContract<unknown> {\n  if (config.planner) {\n    return config.planner;\n  }\n\n  const systemPrompt = buildPlanSystemPrompt(config.capabilities, maxSteps, config.systemPrompt);\n\n  return agent({\n    name: `${config.name}-planner`,\n    description: \"Generates an ordered execution plan over the planner's capabilities.\",\n    model: config.model!,\n    systemPrompt,\n    maxTrips: 1,\n  });\n}\n\n/**\n * Factory-time validation. Surfaces every violation as a typed\n * {@link PlannerFailedError} tagged `authoring: true`, mirroring the\n * supervisor/orchestrator authoring-error convention.\n */\nfunction validateConfig<TOutput>(config: PlannerConfig<TOutput>): void {\n  if (!config.name || typeof config.name !== \"string\") {\n    throw new PlannerFailedError(\"ai.planner: `name` is required and must be a string\", {\n      context: { authoring: true },\n    });\n  }\n\n  const hasModel = config.model !== undefined;\n  const hasPlanner = config.planner !== undefined;\n\n  if (!hasModel && !hasPlanner) {\n    throw new PlannerFailedError(\n      `ai.planner(\"${config.name}\"): one of \\`model\\` or \\`planner\\` is required`,\n      { context: { authoring: true } },\n    );\n  }\n\n  if (hasModel && hasPlanner) {\n    throw new PlannerFailedError(\n      `ai.planner(\"${config.name}\"): \\`model\\` and \\`planner\\` are mutually exclusive — configure exactly one`,\n      { context: { authoring: true } },\n    );\n  }\n\n  if (!Array.isArray(config.capabilities) || config.capabilities.length === 0) {\n    throw new PlannerFailedError(\n      `ai.planner(\"${config.name}\"): at least one capability is required`,\n      { context: { authoring: true } },\n    );\n  }\n\n  const seen = new Set<string>();\n\n  for (const capability of config.capabilities) {\n    if (!capability || typeof capability.name !== \"string\" || capability.name.length === 0) {\n      throw new PlannerFailedError(\n        `ai.planner(\"${config.name}\"): every capability needs a non-empty \\`name\\``,\n        { context: { authoring: true } },\n      );\n    }\n\n    if (typeof capability.description !== \"string\" || capability.description.length === 0) {\n      throw new PlannerFailedError(\n        `ai.planner(\"${config.name}\"): capability \"${capability.name}\" needs a \\`description\\``,\n        { context: { authoring: true } },\n      );\n    }\n\n    if (!capability.executable || typeof capability.executable.execute !== \"function\") {\n      throw new PlannerFailedError(\n        `ai.planner(\"${config.name}\"): capability \"${capability.name}\" needs an \\`executable\\` with an execute() method`,\n        { context: { authoring: true } },\n      );\n    }\n\n    if (seen.has(capability.name)) {\n      throw new PlannerFailedError(\n        `ai.planner(\"${config.name}\"): duplicate capability name \"${capability.name}\"`,\n        { context: { authoring: true } },\n      );\n    }\n\n    seen.add(capability.name);\n  }\n\n  if (config.maxSteps !== undefined && config.maxSteps < 1) {\n    throw new PlannerFailedError(`ai.planner(\"${config.name}\"): \\`maxSteps\\` must be >= 1`, {\n      context: { authoring: true, maxSteps: config.maxSteps },\n    });\n  }\n}\n"],"mappings":"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"}

package/esm/planner/signature.d.mts

@@ -0,0 +1,18 @@
+import { PlannerCapability } from "../contracts/planner/planner-capability.type.mjs";
+
+//#region ../@warlock.js/ai/src/planner/signature.d.ts
+/**
+ * Compute a stable structural fingerprint for a planner definition —
+ * the planner name plus its ordered capability names. Stamped on every
+ * report node the planner produces so trace consumers can tell runs of
+ * structurally-different planners apart even when they share a name.
+ *
+ * Deliberately coarse: it captures WHICH capabilities the planner can
+ * dispatch (and in what registration order), not their descriptions or
+ * the underlying executables' internals — those don't change the set of
+ * plans the planner can produce.
+ */
+declare function computeSignature(name: string, capabilities: PlannerCapability[]): string;
+//#endregion
+export { computeSignature };
+//# sourceMappingURL=signature.d.mts.map

package/esm/planner/signature.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/planner/signature.ts"],"mappings":";;;;;AAsBA;;;;;;;;AAAgF;iBAAhE,gBAAA,CAAiB,IAAA,UAAc,YAAA,EAAc,iBAAiB"}

package/esm/planner/signature.mjs

@@ -0,0 +1,27 @@
+//#region ../@warlock.js/ai/src/planner/signature.ts
+/**
+* Delimiter between capability names in a planner signature. A NUL
+* control character can never appear in a real capability name, so it
+* keeps name boundaries unambiguous — a single capability literally
+* named `"a,b"` can never collide with the two capabilities
+* `["a", "b"]` (a comma delimiter would render both as `caps:a,b`).
+*/
+const CAPABILITY_DELIMITER = String.fromCharCode(0);
+/**
+* Compute a stable structural fingerprint for a planner definition —
+* the planner name plus its ordered capability names. Stamped on every
+* report node the planner produces so trace consumers can tell runs of
+* structurally-different planners apart even when they share a name.
+*
+* Deliberately coarse: it captures WHICH capabilities the planner can
+* dispatch (and in what registration order), not their descriptions or
+* the underlying executables' internals — those don't change the set of
+* plans the planner can produce.
+*/
+function computeSignature(name, capabilities) {
+	return `planner:${name}|caps:${capabilities.map((capability) => capability.name).join(CAPABILITY_DELIMITER)}`;
+}
+
+//#endregion
+export { computeSignature };
+//# sourceMappingURL=signature.mjs.map