@warlock.js/ai 4.4.0 → 4.5.0

package/esm/planner/dag-scheduler.mjs

@@ -0,0 +1,97 @@
+import { PlannerPlanInvalidError } from "../errors/planner-plan-invalid-error.mjs";
+
+//#region ../@warlock.js/ai/src/planner/dag-scheduler.ts
+/**
+* Build the execution DAG from a plan's steps.
+*
+* Each step's `id` (falling back to its array index) and its `dependsOn`
+* become an adjacency list. A `dependsOn` that names a step not in the
+* plan, or any dependency cycle, raises a typed
+* {@link PlannerPlanInvalidError} BEFORE any step runs — the same error
+* class `generatePlan` uses for an unusable plan, with forensic context.
+*
+* @throws PlannerPlanInvalidError on a duplicate id, an unknown
+*   `dependsOn` target, or a cycle.
+*/
+function buildDag(steps, plannerName = "planner") {
+	const nodes = [];
+	const byId = /* @__PURE__ */ new Map();
+	for (let index = 0; index < steps.length; index++) {
+		const step = steps[index];
+		const id = step.id ?? String(index);
+		if (byId.has(id)) throw new PlannerPlanInvalidError(`ai.planner("${plannerName}"): duplicate step id "${id}" in DAG plan`, { context: { id } });
+		const node = {
+			id,
+			index,
+			step,
+			dependencies: []
+		};
+		nodes.push(node);
+		byId.set(id, node);
+	}
+	const dependents = /* @__PURE__ */ new Map();
+	for (const node of nodes) {
+		const seen = /* @__PURE__ */ new Set();
+		for (const dependency of node.step.dependsOn ?? []) {
+			if (dependency === node.id) continue;
+			if (!byId.has(dependency)) throw new PlannerPlanInvalidError(`ai.planner("${plannerName}"): step "${node.id}" depends on unknown step "${dependency}"`, { context: {
+				id: node.id,
+				dependency
+			} });
+			if (seen.has(dependency)) continue;
+			seen.add(dependency);
+			node.dependencies.push(dependency);
+			const reverse = dependents.get(dependency) ?? [];
+			reverse.push(node.id);
+			dependents.set(dependency, reverse);
+		}
+	}
+	assertAcyclic(nodes, byId, plannerName);
+	return {
+		nodes,
+		byId,
+		dependents
+	};
+}
+/**
+* Compute the next ready set: nodes not yet done whose every dependency
+* is in `completed`. Preserves original plan order so a level dispatches
+* deterministically. A node whose dependency is `unreachable` (a failed
+* or skipped ancestor) is NOT ready — it never becomes ready and is
+* recorded skipped by the caller.
+*/
+function readyNodes(dag, completed, done) {
+	return dag.nodes.filter((node) => !done.has(node.id) && node.dependencies.every((dependency) => completed.has(dependency)));
+}
+/**
+* The topological sink(s) — nodes nothing depends on. Used to define the
+* "final output" under parallelism: with an `output` schema set, a
+* single sink is the unambiguous final step; multiple sinks are a
+* convergence error the caller surfaces.
+*/
+function sinkNodes(dag) {
+	return dag.nodes.filter((node) => (dag.dependents.get(node.id) ?? []).length === 0);
+}
+/**
+* Depth-first cycle detection over the dependency edges. A back-edge to
+* a node on the current recursion stack means a cycle — raised as a
+* typed {@link PlannerPlanInvalidError} naming the offending node.
+*/
+function assertAcyclic(nodes, byId, plannerName) {
+	const VISITING = 1;
+	const DONE = 2;
+	const state = /* @__PURE__ */ new Map();
+	const visit = (node) => {
+		const current = state.get(node.id);
+		if (current === DONE) return;
+		if (current === VISITING) throw new PlannerPlanInvalidError(`ai.planner("${plannerName}"): dependency cycle detected at step "${node.id}"`, { context: { id: node.id } });
+		state.set(node.id, VISITING);
+		for (const dependency of node.dependencies) visit(byId.get(dependency));
+		state.set(node.id, DONE);
+	};
+	for (const node of nodes) visit(node);
+}
+
+//#endregion
+export { buildDag, readyNodes, sinkNodes };
+//# sourceMappingURL=dag-scheduler.mjs.map

package/esm/planner/dag-scheduler.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dag-scheduler.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/planner/dag-scheduler.ts"],"sourcesContent":["import type { PlannerStep } from \"../contracts/planner/planner-plan.type\";\nimport { PlannerPlanInvalidError } from \"../errors/planner-plan-invalid-error\";\n\n/**\n * One node in the planner's execution DAG — a plan step plus the\n * resolved structural metadata the scheduler needs to order it.\n *\n * `id` is the step's own `id` when present, falling back to the step's\n * array index stringified (exactly as {@link PlannerStep.id} documents).\n * `dependencies` is the resolved set of node ids this step waits on,\n * de-duplicated and self-references dropped.\n */\nexport type DagNode = {\n  /** Stable id — the step's own `id`, or its array index as a string. */\n  id: string;\n  /** 0-based position of the step in the original plan array. */\n  index: number;\n  /** The plan step this node schedules. */\n  step: PlannerStep;\n  /** Resolved ids this step depends on (subset of the DAG's node ids). */\n  dependencies: string[];\n};\n\n/**\n * The built execution DAG — the ordered node list plus the lookups the\n * scheduler walks. Ordering follows the original plan array so a\n * dependency-free plan executes in author order, level by level.\n */\nexport type PlannerDag = {\n  /** Nodes in original plan order. */\n  nodes: DagNode[];\n  /** id → node, for dependency resolution and sink detection. */\n  byId: Map<string, DagNode>;\n  /** id → ids of the nodes that depend on it (reverse edges). */\n  dependents: Map<string, string[]>;\n};\n\n/**\n * Build the execution DAG from a plan's steps.\n *\n * Each step's `id` (falling back to its array index) and its `dependsOn`\n * become an adjacency list. A `dependsOn` that names a step not in the\n * plan, or any dependency cycle, raises a typed\n * {@link PlannerPlanInvalidError} BEFORE any step runs — the same error\n * class `generatePlan` uses for an unusable plan, with forensic context.\n *\n * @throws PlannerPlanInvalidError on a duplicate id, an unknown\n *   `dependsOn` target, or a cycle.\n */\nexport function buildDag(steps: PlannerStep[], plannerName = \"planner\"): PlannerDag {\n  const nodes: DagNode[] = [];\n  const byId = new Map<string, DagNode>();\n\n  // Pass 1 — assign every step a stable id (own id or array index) and\n  // index the nodes. Duplicate explicit ids are a malformed plan.\n  for (let index = 0; index < steps.length; index++) {\n    const step = steps[index] as PlannerStep;\n    const id = step.id ?? String(index);\n\n    if (byId.has(id)) {\n      throw new PlannerPlanInvalidError(\n        `ai.planner(\"${plannerName}\"): duplicate step id \"${id}\" in DAG plan`,\n        { context: { id } },\n      );\n    }\n\n    const node: DagNode = { id, index, step, dependencies: [] };\n    nodes.push(node);\n    byId.set(id, node);\n  }\n\n  // Pass 2 — resolve dependencies against the id set; reject unknowns,\n  // dedupe, and drop self-references (a no-op edge, never a cycle).\n  const dependents = new Map<string, string[]>();\n\n  for (const node of nodes) {\n    const seen = new Set<string>();\n\n    for (const dependency of node.step.dependsOn ?? []) {\n      if (dependency === node.id) {\n        continue;\n      }\n\n      if (!byId.has(dependency)) {\n        throw new PlannerPlanInvalidError(\n          `ai.planner(\"${plannerName}\"): step \"${node.id}\" depends on unknown step \"${dependency}\"`,\n          { context: { id: node.id, dependency } },\n        );\n      }\n\n      if (seen.has(dependency)) {\n        continue;\n      }\n\n      seen.add(dependency);\n      node.dependencies.push(dependency);\n\n      const reverse = dependents.get(dependency) ?? [];\n      reverse.push(node.id);\n      dependents.set(dependency, reverse);\n    }\n  }\n\n  assertAcyclic(nodes, byId, plannerName);\n\n  return { nodes, byId, dependents };\n}\n\n/**\n * Compute the next ready set: nodes not yet done whose every dependency\n * is in `completed`. Preserves original plan order so a level dispatches\n * deterministically. A node whose dependency is `unreachable` (a failed\n * or skipped ancestor) is NOT ready — it never becomes ready and is\n * recorded skipped by the caller.\n */\nexport function readyNodes(\n  dag: PlannerDag,\n  completed: ReadonlySet<string>,\n  done: ReadonlySet<string>,\n): DagNode[] {\n  return dag.nodes.filter(\n    (node) =>\n      !done.has(node.id) &&\n      node.dependencies.every((dependency) => completed.has(dependency)),\n  );\n}\n\n/**\n * The topological sink(s) — nodes nothing depends on. Used to define the\n * \"final output\" under parallelism: with an `output` schema set, a\n * single sink is the unambiguous final step; multiple sinks are a\n * convergence error the caller surfaces.\n */\nexport function sinkNodes(dag: PlannerDag): DagNode[] {\n  return dag.nodes.filter((node) => (dag.dependents.get(node.id) ?? []).length === 0);\n}\n\n/**\n * Depth-first cycle detection over the dependency edges. A back-edge to\n * a node on the current recursion stack means a cycle — raised as a\n * typed {@link PlannerPlanInvalidError} naming the offending node.\n */\nfunction assertAcyclic(\n  nodes: DagNode[],\n  byId: Map<string, DagNode>,\n  plannerName: string,\n): void {\n  const VISITING = 1;\n  const DONE = 2;\n  const state = new Map<string, number>();\n\n  const visit = (node: DagNode): void => {\n    const current = state.get(node.id);\n\n    if (current === DONE) {\n      return;\n    }\n\n    if (current === VISITING) {\n      throw new PlannerPlanInvalidError(\n        `ai.planner(\"${plannerName}\"): dependency cycle detected at step \"${node.id}\"`,\n        { context: { id: node.id } },\n      );\n    }\n\n    state.set(node.id, VISITING);\n\n    for (const dependency of node.dependencies) {\n      visit(byId.get(dependency) as DagNode);\n    }\n\n    state.set(node.id, DONE);\n  };\n\n  for (const node of nodes) {\n    visit(node);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;AAiDA,SAAgB,SAAS,OAAsB,cAAc,WAAuB;CAClF,MAAM,QAAmB,CAAC;CAC1B,MAAM,uBAAO,IAAI,IAAqB;CAItC,KAAK,IAAI,QAAQ,GAAG,QAAQ,MAAM,QAAQ,SAAS;EACjD,MAAM,OAAO,MAAM;EACnB,MAAM,KAAK,KAAK,MAAM,OAAO,KAAK;EAElC,IAAI,KAAK,IAAI,EAAE,GACb,MAAM,IAAI,wBACR,eAAe,YAAY,yBAAyB,GAAG,gBACvD,EAAE,SAAS,EAAE,GAAG,EAAE,CACpB;EAGF,MAAM,OAAgB;GAAE;GAAI;GAAO;GAAM,cAAc,CAAC;EAAE;EAC1D,MAAM,KAAK,IAAI;EACf,KAAK,IAAI,IAAI,IAAI;CACnB;CAIA,MAAM,6BAAa,IAAI,IAAsB;CAE7C,KAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,uBAAO,IAAI,IAAY;EAE7B,KAAK,MAAM,cAAc,KAAK,KAAK,aAAa,CAAC,GAAG;GAClD,IAAI,eAAe,KAAK,IACtB;GAGF,IAAI,CAAC,KAAK,IAAI,UAAU,GACtB,MAAM,IAAI,wBACR,eAAe,YAAY,YAAY,KAAK,GAAG,6BAA6B,WAAW,IACvF,EAAE,SAAS;IAAE,IAAI,KAAK;IAAI;GAAW,EAAE,CACzC;GAGF,IAAI,KAAK,IAAI,UAAU,GACrB;GAGF,KAAK,IAAI,UAAU;GACnB,KAAK,aAAa,KAAK,UAAU;GAEjC,MAAM,UAAU,WAAW,IAAI,UAAU,KAAK,CAAC;GAC/C,QAAQ,KAAK,KAAK,EAAE;GACpB,WAAW,IAAI,YAAY,OAAO;EACpC;CACF;CAEA,cAAc,OAAO,MAAM,WAAW;CAEtC,OAAO;EAAE;EAAO;EAAM;CAAW;AACnC;;;;;;;;AASA,SAAgB,WACd,KACA,WACA,MACW;CACX,OAAO,IAAI,MAAM,QACd,SACC,CAAC,KAAK,IAAI,KAAK,EAAE,KACjB,KAAK,aAAa,OAAO,eAAe,UAAU,IAAI,UAAU,CAAC,CACrE;AACF;;;;;;;AAQA,SAAgB,UAAU,KAA4B;CACpD,OAAO,IAAI,MAAM,QAAQ,UAAU,IAAI,WAAW,IAAI,KAAK,EAAE,KAAK,CAAC,EAAC,CAAE,WAAW,CAAC;AACpF;;;;;;AAOA,SAAS,cACP,OACA,MACA,aACM;CACN,MAAM,WAAW;CACjB,MAAM,OAAO;CACb,MAAM,wBAAQ,IAAI,IAAoB;CAEtC,MAAM,SAAS,SAAwB;EACrC,MAAM,UAAU,MAAM,IAAI,KAAK,EAAE;EAEjC,IAAI,YAAY,MACd;EAGF,IAAI,YAAY,UACd,MAAM,IAAI,wBACR,eAAe,YAAY,yCAAyC,KAAK,GAAG,IAC5E,EAAE,SAAS,EAAE,IAAI,KAAK,GAAG,EAAE,CAC7B;EAGF,MAAM,IAAI,KAAK,IAAI,QAAQ;EAE3B,KAAK,MAAM,cAAc,KAAK,cAC5B,MAAM,KAAK,IAAI,UAAU,CAAY;EAGvC,MAAM,IAAI,KAAK,IAAI,IAAI;CACzB;CAEA,KAAK,MAAM,QAAQ,OACjB,MAAM,IAAI;AAEd"}

package/esm/planner/plan-prompt.d.mts

@@ -11,7 +11,7 @@ import { PlannerCapability } from "../contracts/planner/planner-capability.type.
  * planner's lifetime) — the produced string is baked onto the internal
  * planning agent.
  */
-declare function buildPlanSystemPrompt(capabilities: PlannerCapability[], maxSteps: number, prefix: SystemPromptContract | string | undefined): string;
+declare function buildPlanSystemPrompt(capabilities: PlannerCapability[], maxSteps: number, prefix: SystemPromptContract | string | undefined, dag?: boolean): string;
 //#endregion
 export { buildPlanSystemPrompt };
 //# sourceMappingURL=plan-prompt.d.mts.map

package/esm/planner/plan-prompt.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"plan-prompt.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/planner/plan-prompt.ts"],"mappings":";;;;;;AAYA;;;;;;;iBAAgB,qBAAA,CACd,YAAA,EAAc,iBAAA,IACd,QAAA,UACA,MAAA,EAAQ,oBAAoB"}
+{"version":3,"file":"plan-prompt.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/planner/plan-prompt.ts"],"mappings":";;;;;;AAYA;;;;;;;iBAAgB,qBAAA,CACd,YAAA,EAAc,iBAAA,IACd,QAAA,UACA,MAAA,EAAQ,oBAAoB,uBAC5B,GAAA"}

package/esm/planner/plan-prompt.mjs

@@ -8,12 +8,13 @@
 * planner's lifetime) — the produced string is baked onto the internal
 * planning agent.
 */
-function buildPlanSystemPrompt(capabilities, maxSteps, prefix) {
+function buildPlanSystemPrompt(capabilities, maxSteps, prefix, dag = false) {
 	const capabilityLines = capabilities.map((capability) => `- ${capability.name}: ${capability.description}`);
 	const sections = [];
 	const resolvedPrefix = resolvePrefix(prefix);
 	if (resolvedPrefix && resolvedPrefix.trim().length > 0) sections.push(resolvedPrefix.trim(), "");
 	sections.push("You are a planner. Break the user's goal into an ordered sequence of steps,", "each one dispatching exactly one of the available capabilities below.", "", "Available capabilities:", ...capabilityLines, "", "Rules:", `- Produce at most ${maxSteps} steps.`, "- Each step's `capability` must be exactly one name from the list above.", "- Each step's `input` is the concrete instruction passed to that capability.", "- Order the steps so each builds on the outputs of the ones before it.", "- Never invent a capability name that is not listed.", "- Keep the plan minimal — only the steps actually needed to satisfy the goal.");
+	if (dag) sections.push("- Give each step a stable `id` and list the ids it builds on in `dependsOn`.", "- Steps with no `dependsOn` between them run in PARALLEL — only add a", "  dependency when a step genuinely needs an earlier step's output.", "- The plan must converge: avoid dependency cycles.");
 	return sections.join("\n");
 }
 /**

package/esm/planner/plan-prompt.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"plan-prompt.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/planner/plan-prompt.ts"],"sourcesContent":["import type { PlannerCapability } from \"../contracts/planner/planner-capability.type\";\nimport type { SystemPromptContract } from \"../contracts/system-prompt.contract\";\n\n/**\n * Assemble the plan-generation system prompt: optional caller framing on\n * top, then the mechanical block listing every capability + its\n * description and the rules for emitting an ordered plan.\n *\n * Runs once at factory time (the capability set is fixed for the\n * planner's lifetime) — the produced string is baked onto the internal\n * planning agent.\n */\nexport function buildPlanSystemPrompt(\n  capabilities: PlannerCapability[],\n  maxSteps: number,\n  prefix: SystemPromptContract | string | undefined,\n): string {\n  const capabilityLines = capabilities.map(\n    (capability) => `- ${capability.name}: ${capability.description}`,\n  );\n\n  const sections: string[] = [];\n  const resolvedPrefix = resolvePrefix(prefix);\n\n  if (resolvedPrefix && resolvedPrefix.trim().length > 0) {\n    sections.push(resolvedPrefix.trim(), \"\");\n  }\n\n  sections.push(\n    \"You are a planner. Break the user's goal into an ordered sequence of steps,\",\n    \"each one dispatching exactly one of the available capabilities below.\",\n    \"\",\n    \"Available capabilities:\",\n    ...capabilityLines,\n    \"\",\n    \"Rules:\",\n    `- Produce at most ${maxSteps} steps.`,\n    \"- Each step's `capability` must be exactly one name from the list above.\",\n    \"- Each step's `input` is the concrete instruction passed to that capability.\",\n    \"- Order the steps so each builds on the outputs of the ones before it.\",\n    \"- Never invent a capability name that is not listed.\",\n    \"- Keep the plan minimal — only the steps actually needed to satisfy the goal.\",\n  );\n\n  return sections.join(\"\\n\");\n}\n\n/**\n * Resolve a caller-supplied `systemPrompt` (string or contract) to plain\n * text. Returns `undefined` when none was supplied.\n */\nfunction resolvePrefix(prompt: SystemPromptContract | string | undefined): string | undefined {\n  if (!prompt) {\n    return undefined;\n  }\n\n  return typeof prompt === \"string\" ? prompt : prompt.resolve();\n}\n"],"mappings":";;;;;;;;;;AAYA,SAAgB,sBACd,cACA,UACA,QACQ;CACR,MAAM,kBAAkB,aAAa,KAClC,eAAe,KAAK,WAAW,KAAK,IAAI,WAAW,aACtD;CAEA,MAAM,WAAqB,CAAC;CAC5B,MAAM,iBAAiB,cAAc,MAAM;CAE3C,IAAI,kBAAkB,eAAe,KAAK,CAAC,CAAC,SAAS,GACnD,SAAS,KAAK,eAAe,KAAK,GAAG,EAAE;CAGzC,SAAS,KACP,+EACA,yEACA,IACA,2BACA,GAAG,iBACH,IACA,UACA,qBAAqB,SAAS,UAC9B,4EACA,gFACA,0EACA,wDACA,+EACF;CAEA,OAAO,SAAS,KAAK,IAAI;AAC3B;;;;;AAMA,SAAS,cAAc,QAAuE;CAC5F,IAAI,CAAC,QACH;CAGF,OAAO,OAAO,WAAW,WAAW,SAAS,OAAO,QAAQ;AAC9D"}
+{"version":3,"file":"plan-prompt.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/planner/plan-prompt.ts"],"sourcesContent":["import type { PlannerCapability } from \"../contracts/planner/planner-capability.type\";\nimport type { SystemPromptContract } from \"../contracts/system-prompt.contract\";\n\n/**\n * Assemble the plan-generation system prompt: optional caller framing on\n * top, then the mechanical block listing every capability + its\n * description and the rules for emitting an ordered plan.\n *\n * Runs once at factory time (the capability set is fixed for the\n * planner's lifetime) — the produced string is baked onto the internal\n * planning agent.\n */\nexport function buildPlanSystemPrompt(\n  capabilities: PlannerCapability[],\n  maxSteps: number,\n  prefix: SystemPromptContract | string | undefined,\n  dag = false,\n): string {\n  const capabilityLines = capabilities.map(\n    (capability) => `- ${capability.name}: ${capability.description}`,\n  );\n\n  const sections: string[] = [];\n  const resolvedPrefix = resolvePrefix(prefix);\n\n  if (resolvedPrefix && resolvedPrefix.trim().length > 0) {\n    sections.push(resolvedPrefix.trim(), \"\");\n  }\n\n  sections.push(\n    \"You are a planner. Break the user's goal into an ordered sequence of steps,\",\n    \"each one dispatching exactly one of the available capabilities below.\",\n    \"\",\n    \"Available capabilities:\",\n    ...capabilityLines,\n    \"\",\n    \"Rules:\",\n    `- Produce at most ${maxSteps} steps.`,\n    \"- Each step's `capability` must be exactly one name from the list above.\",\n    \"- Each step's `input` is the concrete instruction passed to that capability.\",\n    \"- Order the steps so each builds on the outputs of the ones before it.\",\n    \"- Never invent a capability name that is not listed.\",\n    \"- Keep the plan minimal — only the steps actually needed to satisfy the goal.\",\n  );\n\n  if (dag) {\n    // DAG mode — the runtime schedules independent steps in parallel off\n    // `dependsOn`, so the model should declare dependencies explicitly\n    // rather than relying purely on array order.\n    sections.push(\n      \"- Give each step a stable `id` and list the ids it builds on in `dependsOn`.\",\n      \"- Steps with no `dependsOn` between them run in PARALLEL — only add a\",\n      \"  dependency when a step genuinely needs an earlier step's output.\",\n      \"- The plan must converge: avoid dependency cycles.\",\n    );\n  }\n\n  return sections.join(\"\\n\");\n}\n\n/**\n * Resolve a caller-supplied `systemPrompt` (string or contract) to plain\n * text. Returns `undefined` when none was supplied.\n */\nfunction resolvePrefix(prompt: SystemPromptContract | string | undefined): string | undefined {\n  if (!prompt) {\n    return undefined;\n  }\n\n  return typeof prompt === \"string\" ? prompt : prompt.resolve();\n}\n"],"mappings":";;;;;;;;;;AAYA,SAAgB,sBACd,cACA,UACA,QACA,MAAM,OACE;CACR,MAAM,kBAAkB,aAAa,KAClC,eAAe,KAAK,WAAW,KAAK,IAAI,WAAW,aACtD;CAEA,MAAM,WAAqB,CAAC;CAC5B,MAAM,iBAAiB,cAAc,MAAM;CAE3C,IAAI,kBAAkB,eAAe,KAAK,CAAC,CAAC,SAAS,GACnD,SAAS,KAAK,eAAe,KAAK,GAAG,EAAE;CAGzC,SAAS,KACP,+EACA,yEACA,IACA,2BACA,GAAG,iBACH,IACA,UACA,qBAAqB,SAAS,UAC9B,4EACA,gFACA,0EACA,wDACA,+EACF;CAEA,IAAI,KAIF,SAAS,KACP,gFACA,yEACA,sEACA,oDACF;CAGF,OAAO,SAAS,KAAK,IAAI;AAC3B;;;;;AAMA,SAAS,cAAc,QAAuE;CAC5F,IAAI,CAAC,QACH;CAGF,OAAO,OAAO,WAAW,WAAW,SAAS,OAAO,QAAQ;AAC9D"}

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

@@ -1 +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"}
+{"version":3,"file":"planner-run.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/planner/planner-run.ts"],"mappings":";;;;;;;AAqCA;;;;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

@@ -5,8 +5,11 @@ import { PlannerPlanInvalidError } from "../errors/planner-plan-invalid-error.mj
 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 { REPORT_SCHEMA_VERSION } from "../contracts/result/base-report.type.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";
 
 //#region ../@warlock.js/ai/src/planner/planner-run.ts
@@ -40,6 +43,8 @@ var PlannerRun = class {
 		};
 		this.children = [];
 		this.executedSteps = [];
+		this.awaitingApproval = false;
+		this.replanCount = 0;
 		this.runId = args.options?.runId ?? generateRunId("planner");
 	}
 	/**
@@ -49,14 +54,31 @@ var PlannerRun = class {
 	* `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() {
 		try {
 			if (this.isAborted()) {
 				this.markCancelled();
 				return this.buildResult();
 			}
-			const plan = await this.generatePlan();
+			const plan = this.args.options?.approvedPlan ?? await this.generatePlan();
 			if (this.error || !plan) return this.buildResult();
+			this.assertPlanValid(plan);
+			if (this.error) return this.buildResult();
 			this.plan = plan;
+			if (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) {
@@ -70,15 +92,19 @@ var PlannerRun = class {
 	* 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() {
+	async generatePlan(feedback) {
 		const schema = planSchema([...this.args.capabilities.keys()], this.args.maxSteps);
-		const result = await this.args.planningAgent.execute(this.buildPlanPrompt(), {
+		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`, {
@@ -92,43 +118,174 @@ var PlannerRun = class {
 			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
-			} });
+		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;
 		}
-		return plan;
+		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'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.
+	* 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 = [];
-		for (let index = 0; index < plan.steps.length; index++) {
-			const step = plan.steps[index];
+		let steps = plan.steps;
+		let index = 0;
+		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 (!await this.executeStep(index, step, previousOutputs)) {
-				for (let rest = index + 1; rest < plan.steps.length; rest++) this.recordSkipped(rest, plan.steps[rest]);
+			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;
+		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).
@@ -138,10 +295,10 @@ var PlannerRun = class {
 		const stepStart = performance.now();
 		const startedAt = (/* @__PURE__ */ new Date()).toISOString();
 		const input = this.composeStepInput(step, previousOutputs);
-		const result = await capability.executable.execute(input, {
+		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);
@@ -167,6 +324,104 @@ var PlannerRun = class {
 		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
@@ -205,6 +460,7 @@ var PlannerRun = class {
 			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,
@@ -220,27 +476,42 @@ var PlannerRun = class {
 			rootRunId: this.runId,
 			sessionId: this.args.options?.sessionId
 		});
-		return {
+		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. Cancelled
-	* wins over failed (an abort that also produced a step error still
-	* reads as cancelled); failed wins over completed.
+	* 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 — the user's goal. */
-	buildPlanPrompt() {
-		return this.args.goal;
+	/**
+	* 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