@warlock.js/ai 4.3.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/plan-schema.mjs

@@ -19,23 +19,20 @@
 * (the planner still truncates the tail to `skipped` defensively).
 */
 function planSchema(capabilityNames, maxSteps) {
-	const stepsSchema = {
-		type: "array",
-		minItems: 1,
-		description: "Ordered steps to execute, one capability dispatch each.",
-		items: stepItemsSchema(capabilityNames)
-	};
-	if (maxSteps !== void 0) stepsSchema.maxItems = maxSteps;
 	const jsonSchema = {
 		type: "object",
 		properties: {
 			summary: {
-				type: "string",
+				type: ["string", "null"],
 				description: "One-line summary of the overall strategy."
 			},
-			steps: stepsSchema
+			steps: {
+				type: "array",
+				description: "Ordered steps to execute, one capability dispatch each.",
+				items: stepItemsSchema(capabilityNames)
+			}
 		},
-		required: ["steps"],
+		required: ["summary", "steps"],
 		additionalProperties: false
 	};
 	return { "~standard": {
@@ -66,7 +63,7 @@ function stepItemsSchema(capabilityNames) {
 		type: "object",
 		properties: {
 			id: {
-				type: "string",
+				type: ["string", "null"],
 				description: "Stable step id, referenced by dependsOn."
 			},
 			capability: {
@@ -79,16 +76,22 @@ function stepItemsSchema(capabilityNames) {
 				description: "Concrete input passed to the capability's execute()."
 			},
 			reason: {
-				type: "string",
+				type: ["string", "null"],
 				description: "Why this step exists."
 			},
 			dependsOn: {
-				type: "array",
+				type: ["array", "null"],
 				items: { type: "string" },
 				description: "Ids of steps this one conceptually follows."
 			}
 		},
-		required: ["capability", "input"],
+		required: [
+			"id",
+			"capability",
+			"input",
+			"reason",
+			"dependsOn"
+		],
 		additionalProperties: false
 	};
 }

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

@@ -1 +1 @@
-{"version":3,"file":"plan-schema.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/planner/plan-schema.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { PlannerPlan, PlannerStep } from \"../contracts/planner/planner-plan.type\";\n\n/**\n * Build the Standard Schema the planning agent emits — an ordered\n * `{ steps: [...], summary? }` plan whose every step references one of\n * `capabilityNames` via the `capability` field.\n *\n * Mirrors the router's hand-built schema approach\n * (`supervisor/router-factory.ts`): the JSON Schema extension carries\n * the capability names as an `enum` so capable providers enforce the\n * choice natively, while `validate()` still accepts the shape softly so\n * providers without native structured output can pass a parsed object\n * through. Validation is intentionally lenient on `capability` — an\n * unknown name is surfaced later by the planner as a typed\n * `PlannerPlanInvalidError`, with the full forensic context, rather\n * than as an opaque schema issue here.\n *\n * `maxSteps`, when provided, is emitted as the `steps` array's\n * `maxItems` so capable providers refuse to over-produce up front\n * (the planner still truncates the tail to `skipped` defensively).\n */\nexport function planSchema(\n  capabilityNames: string[],\n  maxSteps?: number,\n): StandardSchemaV1<PlannerPlan> {\n  const stepsSchema: Record<string, unknown> = {\n    type: \"array\",\n    minItems: 1,\n    description: \"Ordered steps to execute, one capability dispatch each.\",\n    items: stepItemsSchema(capabilityNames),\n  };\n\n  if (maxSteps !== undefined) {\n    stepsSchema.maxItems = maxSteps;\n  }\n\n  const jsonSchema = {\n    type: \"object\",\n    properties: {\n      summary: {\n        type: \"string\",\n        description: \"One-line summary of the overall strategy.\",\n      },\n      steps: stepsSchema,\n    },\n    required: [\"steps\"],\n    additionalProperties: false,\n  };\n\n  return {\n    \"~standard\": {\n      version: 1,\n      vendor: \"warlock-planner\",\n      jsonSchema: {\n        input: () => jsonSchema,\n      },\n      validate(value: unknown): StandardSchemaV1.Result<PlannerPlan> {\n        if (!value || typeof value !== \"object\") {\n          return { issues: [{ message: \"plan must be an object\" }] };\n        }\n\n        const record = value as { steps?: unknown; summary?: unknown };\n\n        if (!Array.isArray(record.steps) || record.steps.length === 0) {\n          return { issues: [{ message: \"plan `steps` must be a non-empty array\" }] };\n        }\n\n        const steps: PlannerStep[] = [];\n\n        for (const raw of record.steps) {\n          const normalized = normalizeStep(raw);\n\n          if (!normalized) {\n            return {\n              issues: [{ message: \"each plan step must carry a string `capability` and `input`\" }],\n            };\n          }\n\n          steps.push(normalized);\n        }\n\n        const summary = typeof record.summary === \"string\" ? record.summary : undefined;\n\n        return { value: summary !== undefined ? { steps, summary } : { steps } };\n      },\n    } as StandardSchemaV1<PlannerPlan>[\"~standard\"] & {\n      jsonSchema: { input: () => Record<string, unknown> };\n    },\n  };\n}\n\n/** Per-step JSON Schema object — one capability dispatch. */\nfunction stepItemsSchema(capabilityNames: string[]): Record<string, unknown> {\n  return {\n    type: \"object\",\n    properties: {\n      id: { type: \"string\", description: \"Stable step id, referenced by dependsOn.\" },\n      capability: {\n        type: \"string\",\n        enum: capabilityNames,\n        description: \"Name of the capability to dispatch for this step.\",\n      },\n      input: {\n        type: \"string\",\n        description: \"Concrete input passed to the capability's execute().\",\n      },\n      reason: { type: \"string\", description: \"Why this step exists.\" },\n      dependsOn: {\n        type: \"array\",\n        items: { type: \"string\" },\n        description: \"Ids of steps this one conceptually follows.\",\n      },\n    },\n    required: [\"capability\", \"input\"],\n    additionalProperties: false,\n  };\n}\n\n/**\n * Coerce one raw step object into a {@link PlannerStep}, returning\n * `undefined` when the mandatory `capability` / `input` strings are\n * missing. Optional fields are copied only when well-typed.\n */\nfunction normalizeStep(raw: unknown): PlannerStep | undefined {\n  if (!raw || typeof raw !== \"object\") {\n    return undefined;\n  }\n\n  const record = raw as {\n    id?: unknown;\n    capability?: unknown;\n    input?: unknown;\n    reason?: unknown;\n    dependsOn?: unknown;\n  };\n\n  if (typeof record.capability !== \"string\" || record.capability.length === 0) {\n    return undefined;\n  }\n\n  if (typeof record.input !== \"string\") {\n    return undefined;\n  }\n\n  const step: PlannerStep = {\n    capability: record.capability,\n    input: record.input,\n  };\n\n  if (typeof record.id === \"string\") {\n    step.id = record.id;\n  }\n\n  if (typeof record.reason === \"string\") {\n    step.reason = record.reason;\n  }\n\n  if (Array.isArray(record.dependsOn) && record.dependsOn.every((entry) => typeof entry === \"string\")) {\n    step.dependsOn = record.dependsOn as string[];\n  }\n\n  return step;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,WACd,iBACA,UAC+B;CAC/B,MAAM,cAAuC;EAC3C,MAAM;EACN,UAAU;EACV,aAAa;EACb,OAAO,gBAAgB,eAAe;CACxC;CAEA,IAAI,aAAa,QACf,YAAY,WAAW;CAGzB,MAAM,aAAa;EACjB,MAAM;EACN,YAAY;GACV,SAAS;IACP,MAAM;IACN,aAAa;GACf;GACA,OAAO;EACT;EACA,UAAU,CAAC,OAAO;EAClB,sBAAsB;CACxB;CAEA,OAAO,EACL,aAAa;EACX,SAAS;EACT,QAAQ;EACR,YAAY,EACV,aAAa,WACf;EACA,SAAS,OAAsD;GAC7D,IAAI,CAAC,SAAS,OAAO,UAAU,UAC7B,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,yBAAyB,CAAC,EAAE;GAG3D,MAAM,SAAS;GAEf,IAAI,CAAC,MAAM,QAAQ,OAAO,KAAK,KAAK,OAAO,MAAM,WAAW,GAC1D,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,yCAAyC,CAAC,EAAE;GAG3E,MAAM,QAAuB,CAAC;GAE9B,KAAK,MAAM,OAAO,OAAO,OAAO;IAC9B,MAAM,aAAa,cAAc,GAAG;IAEpC,IAAI,CAAC,YACH,OAAO,EACL,QAAQ,CAAC,EAAE,SAAS,8DAA8D,CAAC,EACrF;IAGF,MAAM,KAAK,UAAU;GACvB;GAEA,MAAM,UAAU,OAAO,OAAO,YAAY,WAAW,OAAO,UAAU;GAEtE,OAAO,EAAE,OAAO,YAAY,SAAY;IAAE;IAAO;GAAQ,IAAI,EAAE,MAAM,EAAE;EACzE;CACF,EAGF;AACF;;AAGA,SAAS,gBAAgB,iBAAoD;CAC3E,OAAO;EACL,MAAM;EACN,YAAY;GACV,IAAI;IAAE,MAAM;IAAU,aAAa;GAA2C;GAC9E,YAAY;IACV,MAAM;IACN,MAAM;IACN,aAAa;GACf;GACA,OAAO;IACL,MAAM;IACN,aAAa;GACf;GACA,QAAQ;IAAE,MAAM;IAAU,aAAa;GAAwB;GAC/D,WAAW;IACT,MAAM;IACN,OAAO,EAAE,MAAM,SAAS;IACxB,aAAa;GACf;EACF;EACA,UAAU,CAAC,cAAc,OAAO;EAChC,sBAAsB;CACxB;AACF;;;;;;AAOA,SAAS,cAAc,KAAuC;CAC5D,IAAI,CAAC,OAAO,OAAO,QAAQ,UACzB;CAGF,MAAM,SAAS;CAQf,IAAI,OAAO,OAAO,eAAe,YAAY,OAAO,WAAW,WAAW,GACxE;CAGF,IAAI,OAAO,OAAO,UAAU,UAC1B;CAGF,MAAM,OAAoB;EACxB,YAAY,OAAO;EACnB,OAAO,OAAO;CAChB;CAEA,IAAI,OAAO,OAAO,OAAO,UACvB,KAAK,KAAK,OAAO;CAGnB,IAAI,OAAO,OAAO,WAAW,UAC3B,KAAK,SAAS,OAAO;CAGvB,IAAI,MAAM,QAAQ,OAAO,SAAS,KAAK,OAAO,UAAU,OAAO,UAAU,OAAO,UAAU,QAAQ,GAChG,KAAK,YAAY,OAAO;CAG1B,OAAO;AACT"}
+{"version":3,"file":"plan-schema.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/planner/plan-schema.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { PlannerPlan, PlannerStep } from \"../contracts/planner/planner-plan.type\";\n\n/**\n * Build the Standard Schema the planning agent emits — an ordered\n * `{ steps: [...], summary? }` plan whose every step references one of\n * `capabilityNames` via the `capability` field.\n *\n * Mirrors the router's hand-built schema approach\n * (`supervisor/router-factory.ts`): the JSON Schema extension carries\n * the capability names as an `enum` so capable providers enforce the\n * choice natively, while `validate()` still accepts the shape softly so\n * providers without native structured output can pass a parsed object\n * through. Validation is intentionally lenient on `capability` — an\n * unknown name is surfaced later by the planner as a typed\n * `PlannerPlanInvalidError`, with the full forensic context, rather\n * than as an opaque schema issue here.\n *\n * `maxSteps`, when provided, is emitted as the `steps` array's\n * `maxItems` so capable providers refuse to over-produce up front\n * (the planner still truncates the tail to `skipped` defensively).\n */\nexport function planSchema(\n  capabilityNames: string[],\n  maxSteps?: number,\n): StandardSchemaV1<PlannerPlan> {\n  // OpenAI strict `json_schema` mode (and other native structured-output\n  // providers) require EVERY property to appear in `required` — with truly\n  // optional fields expressed as nullable — and reject array `minItems` /\n  // `maxItems`. So the schema is strict-shaped: all keys required, the\n  // optional ones nullable, no item-count bounds. A non-empty plan is\n  // enforced in `validate()`, and `maxSteps` by the runtime's tail\n  // truncation, so neither bound is needed on the wire.\n  void maxSteps;\n\n  const jsonSchema = {\n    type: \"object\",\n    properties: {\n      summary: {\n        type: [\"string\", \"null\"],\n        description: \"One-line summary of the overall strategy.\",\n      },\n      steps: {\n        type: \"array\",\n        description: \"Ordered steps to execute, one capability dispatch each.\",\n        items: stepItemsSchema(capabilityNames),\n      },\n    },\n    required: [\"summary\", \"steps\"],\n    additionalProperties: false,\n  };\n\n  return {\n    \"~standard\": {\n      version: 1,\n      vendor: \"warlock-planner\",\n      jsonSchema: {\n        input: () => jsonSchema,\n      },\n      validate(value: unknown): StandardSchemaV1.Result<PlannerPlan> {\n        if (!value || typeof value !== \"object\") {\n          return { issues: [{ message: \"plan must be an object\" }] };\n        }\n\n        const record = value as { steps?: unknown; summary?: unknown };\n\n        if (!Array.isArray(record.steps) || record.steps.length === 0) {\n          return { issues: [{ message: \"plan `steps` must be a non-empty array\" }] };\n        }\n\n        const steps: PlannerStep[] = [];\n\n        for (const raw of record.steps) {\n          const normalized = normalizeStep(raw);\n\n          if (!normalized) {\n            return {\n              issues: [{ message: \"each plan step must carry a string `capability` and `input`\" }],\n            };\n          }\n\n          steps.push(normalized);\n        }\n\n        const summary = typeof record.summary === \"string\" ? record.summary : undefined;\n\n        return { value: summary !== undefined ? { steps, summary } : { steps } };\n      },\n    } as StandardSchemaV1<PlannerPlan>[\"~standard\"] & {\n      jsonSchema: { input: () => Record<string, unknown> };\n    },\n  };\n}\n\n/** Per-step JSON Schema object — one capability dispatch. */\nfunction stepItemsSchema(capabilityNames: string[]): Record<string, unknown> {\n  return {\n    type: \"object\",\n    properties: {\n      id: {\n        type: [\"string\", \"null\"],\n        description: \"Stable step id, referenced by dependsOn.\",\n      },\n      capability: {\n        type: \"string\",\n        enum: capabilityNames,\n        description: \"Name of the capability to dispatch for this step.\",\n      },\n      input: {\n        type: \"string\",\n        description: \"Concrete input passed to the capability's execute().\",\n      },\n      reason: { type: [\"string\", \"null\"], description: \"Why this step exists.\" },\n      dependsOn: {\n        type: [\"array\", \"null\"],\n        items: { type: \"string\" },\n        description: \"Ids of steps this one conceptually follows.\",\n      },\n    },\n    // Strict mode: every property required; the genuinely-optional ones\n    // (id / reason / dependsOn) are nullable. `validate()` treats null and\n    // missing identically, so a model emitting `null` round-trips fine.\n    required: [\"id\", \"capability\", \"input\", \"reason\", \"dependsOn\"],\n    additionalProperties: false,\n  };\n}\n\n/**\n * Coerce one raw step object into a {@link PlannerStep}, returning\n * `undefined` when the mandatory `capability` / `input` strings are\n * missing. Optional fields are copied only when well-typed.\n */\nfunction normalizeStep(raw: unknown): PlannerStep | undefined {\n  if (!raw || typeof raw !== \"object\") {\n    return undefined;\n  }\n\n  const record = raw as {\n    id?: unknown;\n    capability?: unknown;\n    input?: unknown;\n    reason?: unknown;\n    dependsOn?: unknown;\n  };\n\n  if (typeof record.capability !== \"string\" || record.capability.length === 0) {\n    return undefined;\n  }\n\n  if (typeof record.input !== \"string\") {\n    return undefined;\n  }\n\n  const step: PlannerStep = {\n    capability: record.capability,\n    input: record.input,\n  };\n\n  if (typeof record.id === \"string\") {\n    step.id = record.id;\n  }\n\n  if (typeof record.reason === \"string\") {\n    step.reason = record.reason;\n  }\n\n  if (Array.isArray(record.dependsOn) && record.dependsOn.every((entry) => typeof entry === \"string\")) {\n    step.dependsOn = record.dependsOn as string[];\n  }\n\n  return step;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,WACd,iBACA,UAC+B;CAU/B,MAAM,aAAa;EACjB,MAAM;EACN,YAAY;GACV,SAAS;IACP,MAAM,CAAC,UAAU,MAAM;IACvB,aAAa;GACf;GACA,OAAO;IACL,MAAM;IACN,aAAa;IACb,OAAO,gBAAgB,eAAe;GACxC;EACF;EACA,UAAU,CAAC,WAAW,OAAO;EAC7B,sBAAsB;CACxB;CAEA,OAAO,EACL,aAAa;EACX,SAAS;EACT,QAAQ;EACR,YAAY,EACV,aAAa,WACf;EACA,SAAS,OAAsD;GAC7D,IAAI,CAAC,SAAS,OAAO,UAAU,UAC7B,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,yBAAyB,CAAC,EAAE;GAG3D,MAAM,SAAS;GAEf,IAAI,CAAC,MAAM,QAAQ,OAAO,KAAK,KAAK,OAAO,MAAM,WAAW,GAC1D,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,yCAAyC,CAAC,EAAE;GAG3E,MAAM,QAAuB,CAAC;GAE9B,KAAK,MAAM,OAAO,OAAO,OAAO;IAC9B,MAAM,aAAa,cAAc,GAAG;IAEpC,IAAI,CAAC,YACH,OAAO,EACL,QAAQ,CAAC,EAAE,SAAS,8DAA8D,CAAC,EACrF;IAGF,MAAM,KAAK,UAAU;GACvB;GAEA,MAAM,UAAU,OAAO,OAAO,YAAY,WAAW,OAAO,UAAU;GAEtE,OAAO,EAAE,OAAO,YAAY,SAAY;IAAE;IAAO;GAAQ,IAAI,EAAE,MAAM,EAAE;EACzE;CACF,EAGF;AACF;;AAGA,SAAS,gBAAgB,iBAAoD;CAC3E,OAAO;EACL,MAAM;EACN,YAAY;GACV,IAAI;IACF,MAAM,CAAC,UAAU,MAAM;IACvB,aAAa;GACf;GACA,YAAY;IACV,MAAM;IACN,MAAM;IACN,aAAa;GACf;GACA,OAAO;IACL,MAAM;IACN,aAAa;GACf;GACA,QAAQ;IAAE,MAAM,CAAC,UAAU,MAAM;IAAG,aAAa;GAAwB;GACzE,WAAW;IACT,MAAM,CAAC,SAAS,MAAM;IACtB,OAAO,EAAE,MAAM,SAAS;IACxB,aAAa;GACf;EACF;EAIA,UAAU;GAAC;GAAM;GAAc;GAAS;GAAU;EAAW;EAC7D,sBAAsB;CACxB;AACF;;;;;;AAOA,SAAS,cAAc,KAAuC;CAC5D,IAAI,CAAC,OAAO,OAAO,QAAQ,UACzB;CAGF,MAAM,SAAS;CAQf,IAAI,OAAO,OAAO,eAAe,YAAY,OAAO,WAAW,WAAW,GACxE;CAGF,IAAI,OAAO,OAAO,UAAU,UAC1B;CAGF,MAAM,OAAoB;EACxB,YAAY,OAAO;EACnB,OAAO,OAAO;CAChB;CAEA,IAAI,OAAO,OAAO,OAAO,UACvB,KAAK,KAAK,OAAO;CAGnB,IAAI,OAAO,OAAO,WAAW,UAC3B,KAAK,SAAS,OAAO;CAGvB,IAAI,MAAM,QAAQ,OAAO,SAAS,KAAK,OAAO,UAAU,OAAO,UAAU,OAAO,UAAU,QAAQ,GAChG,KAAK,YAAY,OAAO;CAG1B,OAAO;AACT"}

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"}