@hilbras/omninode 2.0.0-alpha.10 → 2.0.0-alpha.11

package/README.md

@@ -18,7 +18,7 @@ existing intelligence; it does not try to become another model.
 
 ## Status
 
-**v2.0.0-alpha.10 — v2 Phase 10: Aggregation Improvements**
+**v2.0.0-alpha.11 — v2 Phase 11: Planner v2**
 (the reliability & interoperability line: architecture → execution →
 protocol → adapters → pipelines → providers → OmniHilbras → memory → reports) (the v2
 roadmap is [docs/ROADMAP_V2.md](docs/ROADMAP_V2.md); the v1 plan is complete:
@@ -31,6 +31,13 @@ for the plan and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the design).
 
 ### What's new in v2 (so far)
 
+- **Phase 11 — Planner v2**: the planner now receives the full §15 input —
+  task, project context, agent reports, **aggregated findings (consensus and
+  conflicts included)**, memory and **constraints** (settable per pipeline
+  step). Plans carry an explicit goal, every generated plan is **schema
+  validated**, invalid output produces a **structured error** or falls back to
+  heuristic planning, and a guard test proves the planner module depends on no
+  specific provider.
 - **Phase 10 — Aggregation Improvements**: when agents disagree,
   OmniNode now says so instead of flattening the answer — **conflict
   detection** preserves every position (severity spread, divergent

package/dist/cli/index.js

@@ -6,7 +6,7 @@ import { realpathSync } from "fs";
 import { Command } from "commander";
 
 // src/version.ts
-var OMNINODE_VERSION = "2.0.0-alpha.10";
+var OMNINODE_VERSION = "2.0.0-alpha.11";
 
 // src/errors/index.ts
 var OmniNodeError = class extends Error {
@@ -109,7 +109,9 @@ var pipelineStepConfigSchema = z.object({
   model: z.string().optional(),
   depends_on: z.array(z.string()).optional(),
   retries: z.number().int().min(0).max(10).optional(),
-  condition: z.enum(["always", "on-success", "on-failure"]).optional()
+  condition: z.enum(["always", "on-success", "on-failure"]).optional(),
+  /** Constraints passed to the planner for plan steps (§15). */
+  constraints: z.array(z.string()).optional()
 }).strict();
 var pipelineConfigSchema = z.object({
   id: z.string().min(1).regex(/^[a-z0-9][a-z0-9-]*$/, "pipeline id must be kebab-case"),
@@ -239,7 +241,8 @@ function toPipelineDefinition(raw) {
       model: step.model,
       dependsOn: step.depends_on,
       retries: step.retries,
-      condition: step.condition
+      condition: step.condition,
+      constraints: step.constraints
     }))
   };
 }
@@ -3532,19 +3535,32 @@ var HeuristicPlanner = class {
   name = "heuristic";
   async plan(request) {
     const steps = [];
-    const findings = request.reports.flatMap(
-      (report) => report.findings.map((finding) => ({ finding, agent: report.agent }))
-    );
     const recommendations = dedupe(request.reports.flatMap((r) => r.recommendations));
-    for (const [index, text] of recommendations.entries()) {
+    for (const text of recommendations) {
       steps.push({
         id: `step-${steps.length + 1}`,
         title: truncate5(text, 120),
         order: steps.length + 1,
-        ...index > 0 ? { dependsOn: [`step-${steps.length}`] } : {}
+        ...steps.length > 0 ? { dependsOn: [`step-${steps.length}`] } : {}
       });
     }
-    const significant = findings.filter(({ finding }) => finding.severity ? SEVERITY_RANK2[finding.severity] >= SEVERITY_RANK2.high : false).sort((a, b) => SEVERITY_RANK2[b.finding.severity ?? "info"] - SEVERITY_RANK2[a.finding.severity ?? "info"]);
+    const contributed = request.aggregated ? request.aggregated.findings.map((finding) => ({
+      finding: {
+        id: `agg-${slug(finding.title)}`,
+        title: finding.title,
+        detail: finding.details[0] ?? finding.title,
+        ...finding.severity ? { severity: finding.severity } : {},
+        ...finding.recommendations && finding.recommendations.length > 0 ? { recommendation: finding.recommendations[0] } : {}
+      },
+      agent: finding.sources.map((s) => s.agent).join("+")
+    })) : request.reports.flatMap(
+      (report) => report.findings.map((finding) => ({ finding, agent: report.agent }))
+    );
+    const significant = contributed.filter(
+      ({ finding }) => finding.severity ? SEVERITY_RANK2[finding.severity] >= SEVERITY_RANK2.high : false
+    ).sort(
+      (a, b) => SEVERITY_RANK2[b.finding.severity ?? "info"] - SEVERITY_RANK2[a.finding.severity ?? "info"]
+    );
     for (const { finding } of significant) {
       steps.push(remediationStep(finding, steps.length + 1));
     }
@@ -3557,12 +3573,20 @@ var HeuristicPlanner = class {
       });
     }
     const risks = significant.filter(({ finding }) => finding.severity === "critical").map(({ finding }) => `Critical finding unaddressed until its step completes: ${finding.title}`);
+    const conflicts = request.aggregated?.conflicts ?? [];
+    if (conflicts.length > 0) {
+      risks.push(
+        `${conflicts.length} unresolved agent disagreement(s): ${conflicts.map((c) => c.findingTitle).join("; ")}`
+      );
+    }
     return {
       id: `plan-${Date.now().toString(36)}-${randomBytes3(3).toString("hex")}`,
       objective: request.objective,
+      goal: request.aggregated?.title ?? truncate5(request.objective, 120),
       summary: `Derived from ${request.reports.length} report(s): ${recommendations.length} recommendation step(s), ${significant.length} remediation step(s).`,
       steps,
       ...risks.length > 0 ? { risks } : {},
+      ...request.constraints !== void 0 && request.constraints.length > 0 ? { constraints: request.constraints } : {},
       generatedBy: "heuristic",
       ...request.taskId !== void 0 ? { taskId: request.taskId } : {},
       ...request.pipelineRunId !== void 0 ? { pipelineRunId: request.pipelineRunId } : {},
@@ -3577,24 +3601,76 @@ function remediationStep(finding, order) {
     description: finding.detail,
     order,
     dependsOn: order > 1 ? [`step-${order - 1}`] : [],
-    sourceFindings: [finding.id]
+    sourceFindings: [finding.id],
+    ...finding.recommendation ? { recommendation: finding.recommendation } : {}
   };
 }
 function dedupe(texts) {
   return [...new Set(texts.map((t) => t.trim()).filter((t) => t.length > 0))];
 }
+function slug(text) {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40);
+}
 function truncate5(text, max) {
   return text.length > max ? `${text.slice(0, max - 1)}\u2026` : text;
 }
 
 // src/planner/model.ts
 import { randomBytes as randomBytes4 } from "crypto";
+
+// src/planner/schema.ts
 import { z as z3 } from "zod";
+var planStepSchema = z3.object({
+  id: z3.string().min(1).optional(),
+  title: z3.string().min(1),
+  description: z3.string().optional(),
+  order: z3.number().int().optional(),
+  targets: z3.array(z3.string()).optional(),
+  acceptance_criteria: z3.array(z3.string()).optional(),
+  depends_on: z3.array(z3.string()).optional(),
+  source_findings: z3.array(z3.string()).optional()
+});
+var planJsonSchema = z3.object({
+  goal: z3.string().min(1),
+  summary: z3.string().min(1),
+  steps: z3.array(planStepSchema).min(1),
+  risks: z3.array(z3.string()).optional(),
+  notes: z3.array(z3.string()).optional()
+});
+function validatePlan(plan) {
+  const issues = [];
+  const stepIds = /* @__PURE__ */ new Set();
+  for (const [index, step] of plan.steps.entries()) {
+    if (stepIds.has(step.id)) {
+      issues.push({ path: `steps.${index}.id`, message: `duplicate step id "${step.id}"` });
+    }
+    stepIds.add(step.id);
+    if (!step.title || step.title.trim().length === 0) {
+      issues.push({ path: `steps.${index}.title`, message: "title must not be empty" });
+    }
+    for (const dep of step.dependsOn ?? []) {
+      if (!stepIds.has(dep) && !plan.steps.some((s) => s.id === dep)) {
+        issues.push({ path: `steps.${index}.dependsOn`, message: `unknown step dependency "${dep}"` });
+      }
+    }
+  }
+  if (plan.steps.length === 0) {
+    issues.push({ path: "steps", message: "a plan needs at least one step" });
+  }
+  if (!plan.summary || plan.summary.trim().length === 0) {
+    issues.push({ path: "summary", message: "summary must not be empty" });
+  }
+  return issues.length > 0 ? { valid: false, issues, reason: `plan failed validation (${issues.length} issue(s))` } : { valid: true, plan };
+}
 
 // src/planner/context.ts
 function buildPlannerContext(request) {
-  const parts = [`# Objective
+  const parts = [`# Task
 ${request.objective}`];
+  if (request.projectContext) {
+    parts.push(`# Project context
+${request.projectContext}`);
+  }
   if (request.role) {
     const roleLines = [`# Role
 ${request.role.name} (${request.role.id})`];
@@ -3614,7 +3690,7 @@ ${request.role.name} (${request.role.id})`];
       )
     );
     parts.push(
-      `# Findings (${request.reports.length} report(s) by ${agents})
+      `# Agent reports (${request.reports.length} by ${agents})
 ` + (findingLines.length > 0 ? findingLines.join("\n") : "(no findings reported)")
     );
     const recommendationLines = request.reports.flatMap(
@@ -3624,9 +3700,20 @@ ${request.role.name} (${request.role.id})`];
       parts.push(`# Recommendations
 ${recommendationLines.join("\n")}`);
     }
-    const summaryLines = request.reports.map((report) => `- [${report.agent}] ${report.summary}`);
-    parts.push(`# Report summaries
-${summaryLines.join("\n")}`);
+  }
+  if (request.aggregated) {
+    const aggregatedLines = [
+      `- findings: ${request.aggregated.findings.length} (agreements: ${request.aggregated.agreements.length}, conflicts: ${request.aggregated.conflicts.length})`,
+      ...request.aggregated.findings.map(
+        (finding) => `- [${finding.severity ?? "info"}] ${finding.title} (x${finding.occurrences})`
+      ),
+      // Conflicts stay visible to the planner — it must plan around disagreement.
+      ...request.aggregated.conflicts.map(
+        (conflict) => `- CONFLICT (${conflict.type}) on "${conflict.findingTitle}": ${conflict.note}`
+      )
+    ];
+    parts.push(`# Aggregated findings
+${aggregatedLines.join("\n")}`);
   }
   if (request.memory && request.memory.length > 0) {
     parts.push(
@@ -3634,7 +3721,11 @@ ${summaryLines.join("\n")}`);
 ` + request.memory.map((entry2) => `- [${entry2.scope}] ${entry2.content}`).join("\n")
     );
   }
-  if (request.context && request.context.length > 0) {
+  if (request.constraints && request.constraints.length > 0) {
+    parts.push(`# Constraints
+${request.constraints.map((c) => `- ${c}`).join("\n")}`);
+  }
+  if (request.context) {
     parts.push(`# Research context
 ${request.context}`);
   }
@@ -3642,22 +3733,6 @@ ${request.context}`);
 }
 
 // src/planner/model.ts
-var planStepJsonSchema = z3.object({
-  id: z3.string().optional(),
-  title: z3.string().min(1),
-  description: z3.string().optional(),
-  order: z3.number().int().optional(),
-  targets: z3.array(z3.string()).optional(),
-  acceptance_criteria: z3.array(z3.string()).optional(),
-  depends_on: z3.array(z3.string()).optional(),
-  source_findings: z3.array(z3.string()).optional()
-}).strict();
-var planJsonSchema = z3.object({
-  summary: z3.string().min(1),
-  steps: z3.array(planStepJsonSchema).min(1),
-  risks: z3.array(z3.string()).optional(),
-  notes: z3.array(z3.string()).optional()
-}).strict();
 var ModelPlanner = class {
   constructor(options) {
     this.options = options;
@@ -3671,7 +3746,7 @@ var ModelPlanner = class {
     const messages = [
       {
         role: "system",
-        content: 'You are the OmniNode planner. Given the objective and the combined research context, produce a final analysis and a prioritized, actionable implementation plan. Respond with JSON ONLY (no prose, no code fences) matching exactly this shape: {"summary": string, "steps": [{"id": string, "title": string, "description": string, "order": number, "targets": string[], "acceptance_criteria": string[], "source_findings": string[]}], "risks": string[], "notes": string[]}. ' + (this.options.instruction ?? "")
+        content: 'You are the OmniNode planner. Given the objective and the combined research context, produce a final analysis and a prioritized, actionable implementation plan. Respond with JSON ONLY (no prose, no code fences) matching exactly this shape: {"goal": string, "summary": string, "steps": [{"id": string, "title": string, "description": string, "order": number, "targets": string[], "acceptance_criteria": string[], "source_findings": string[]}], "risks": string[], "notes": string[]}. ' + (this.options.instruction ?? "")
       },
       { role: "user", content: context }
     ];
@@ -3682,60 +3757,86 @@ var ModelPlanner = class {
       return this.degrade(request, `planner model call failed: ${describe(error)}`);
     }
     const parsed = parsePlanJson(responseText);
-    if (!parsed) {
-      return this.degrade(request, "planner model output was not valid plan JSON");
+    if (!parsed.ok) {
+      return this.degrade(request, `planner model output rejected: ${parsed.reason}`, parsed.issues);
     }
     const plan = {
       id: `plan-${Date.now().toString(36)}-${randomBytes4(3).toString("hex")}`,
       objective: request.objective,
+      goal: parsed.goal,
       summary: parsed.summary,
       steps: parsed.steps,
       ...parsed.risks !== void 0 ? { risks: parsed.risks } : {},
       ...parsed.notes !== void 0 ? { notes: parsed.notes } : {},
+      ...request.constraints !== void 0 && request.constraints.length > 0 ? { constraints: request.constraints } : {},
       generatedBy: `model:${this.options.model}`,
       model: this.options.model,
       ...request.taskId !== void 0 ? { taskId: request.taskId } : {},
       ...request.pipelineRunId !== void 0 ? { pipelineRunId: request.pipelineRunId } : {},
       createdAt: (/* @__PURE__ */ new Date()).toISOString()
     };
-    return plan;
+    const validation = validatePlan(plan);
+    if (!validation.valid) {
+      return this.degrade(request, `generated plan rejected: ${validation.reason}`, validation.issues);
+    }
+    return validation.plan;
   }
-  async degrade(request, reason) {
+  async degrade(request, reason, issues = []) {
     if (this.options.fallback) {
       this.log.warn(`${reason} \u2014 using the heuristic fallback planner.`);
       return this.options.fallback.plan(request);
     }
-    throw new PlannerError("PLANNER_FAILED", `Planner failed: ${reason}.`);
+    throw new PlannerError("PLAN_INVALID", `Planner failed: ${reason}.`, {
+      details: { reason, issues }
+    });
   }
 };
 function parsePlanJson(text) {
   const unfenced = text.replace(/```(?:json)?/gi, "");
   const start = unfenced.indexOf("{");
   const end = unfenced.lastIndexOf("}");
-  if (start < 0 || end <= start) return void 0;
+  if (start < 0 || end <= start) {
+    return { ok: false, reason: "planner output contained no JSON object", issues: [] };
+  }
+  let json;
   try {
-    const json = JSON.parse(unfenced.slice(start, end + 1));
-    const parsed = planJsonSchema.safeParse(json);
-    if (!parsed.success) return void 0;
-    const steps = parsed.data.steps.map((step, index) => ({
-      id: step.id ?? `step-${index + 1}`,
-      title: step.title,
-      description: step.description,
-      order: step.order ?? index + 1,
-      targets: step.targets,
-      acceptanceCriteria: step.acceptance_criteria,
-      dependsOn: step.depends_on,
-      sourceFindings: step.source_findings
-    }));
+    json = JSON.parse(unfenced.slice(start, end + 1));
+  } catch (error) {
     return {
-      summary: parsed.data.summary,
-      steps: steps.sort((a, b) => a.order - b.order),
-      risks: parsed.data.risks,
-      notes: parsed.data.notes
+      ok: false,
+      reason: `planner output was not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+      issues: []
     };
-  } catch {
-    return void 0;
   }
+  const parsed = planJsonSchema.safeParse(json);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      reason: "planner output did not match the plan schema",
+      issues: parsed.error.issues.map((issue) => ({
+        path: issue.path.join(".") || "(root)",
+        message: issue.message
+      }))
+    };
+  }
+  const steps = parsed.data.steps.map((step, index) => ({
+    id: step.id ?? `step-${index + 1}`,
+    title: step.title,
+    description: step.description,
+    order: step.order ?? index + 1,
+    targets: step.targets,
+    acceptanceCriteria: step.acceptance_criteria,
+    dependsOn: step.depends_on,
+    sourceFindings: step.source_findings
+  })).sort((a, b) => a.order - b.order);
+  return {
+    ok: true,
+    goal: parsed.data.goal,
+    summary: parsed.data.summary,
+    steps,
+    risks: parsed.data.risks,
+    notes: parsed.data.notes
+  };
 }
 function describe(error) {
   return error instanceof Error ? error.message : String(error);
@@ -4173,11 +4274,14 @@ ${contribution}`);
     };
   }
   async runPlan(step, ctx) {
+    const aggregated = ctx.reports.length > 0 ? aggregateReports(ctx.reports) : void 0;
     const request = {
       objective: ctx.objective,
       reports: ctx.reports,
+      ...aggregated !== void 0 ? { aggregated } : {},
       ...ctx.combinedContext.length > 0 ? { context: ctx.combinedContext } : {},
       ...ctx.role ? { role: ctx.role } : {},
+      ...step.constraints !== void 0 && step.constraints.length > 0 ? { constraints: step.constraints } : {},
       ...ctx.pipelineRunId !== void 0 ? { pipelineRunId: ctx.pipelineRunId } : {}
     };
     let planner;