loopforge 1.3.1 → 1.8.0

package/dist/engine.js

@@ -1,22 +1,22 @@
 /** LoopForge-loop_compile — Engine (outer loop manager).
  *
- * v1.0: 3-mode engine with vault-backed loop lineage persistence.
- * invokeLoopCompile (primary), invokeBuild (internal), invokeFeedback.
+ * 2-mode engine with vault-backed loop lineage persistence.
+ * invokeLoopCompile (primary), invokeFeedback.
  * Circuit breaker prevents infinite stall loops.
  * EngineMetrics tracks silent-failure counters for observability.
  */
 import { randomUUID } from "node:crypto";
 import { getPolicy } from "./policy.js";
 import { FSBackend, readLineageMd } from "./backends/fs.js";
-import { AgentStatus, Mode, makeAnalysis, makeExecutionFeedback, makeLoopCompileRequest, makeLoopObjective, makeLoopRoundResult, makeSelfEvaluation, makeSessionState, makeTaskId, makeVaultConfig, SELF_EVAL_REGEX, } from "./protocol.js";
-import { routeTechnique } from "./builder.js";
+import { AgentStatus, Mode, makeAnalysis, makeExecutionEvidence, makeExecutionFeedback, makeLoopCompileRequest, makeLoopObjective, makeLoopRoundResult, makeSelfEvaluation, makeSessionState, makeTaskId, makeVaultConfig, SELF_EVAL_REGEX, } from "./protocol.js";
 import { scoreQuality } from "./builder.js";
 import { compileLoop } from "./loop-compiler.js";
+import { logEvent } from "./observability.js";
 // ═══════════════════════════════════════════════════════════════════════════
 // Self-Evaluation extraction (v1.1 — autonomous loop feedback)
 // ═══════════════════════════════════════════════════════════════════════════
 /** Extract a structured SelfEvaluation from agent output text.
- *  Returns null if no valid self-evaluation block is found.
+ *  Returns null if no valid self-eval block is found.
  *  The agent is instructed to output JSON between the delimiters. */
 export function extractSelfEvaluation(text) {
     const match = text.match(SELF_EVAL_REGEX);
@@ -33,17 +33,109 @@ export function extractSelfEvaluation(text) {
             return null;
         if (typeof raw.should_continue !== "boolean")
             return null;
-        return makeSelfEvaluation({
-            success: raw.success,
-            output_summary: raw.output_summary,
-            constraint_violations: raw.constraint_violations,
-            should_continue: raw.should_continue,
-        });
+        return buildSelfEvaluation(raw);
     }
     catch {
         return null;
     }
 }
+/** Build a SelfEvaluation from a parsed JSON object.
+ *  Lenient parsing: missing optional fields get sensible defaults.
+ *  Used by extractSelfEvaluation() (regex path) and MCP tool handler
+ *  (structured evaluation parameter path). */
+export function buildSelfEvaluation(raw) {
+    // P4: Parse execution evidence from raw JSON
+    let executionEvidence;
+    const rawEvidence = raw.execution_evidence;
+    if (rawEvidence && typeof rawEvidence === "object") {
+        const testResults = rawEvidence.test_results;
+        executionEvidence = makeExecutionEvidence({
+            files_changed: Array.isArray(rawEvidence.files_changed)
+                ? rawEvidence.files_changed.filter((v) => typeof v === "string")
+                : [],
+            test_results: testResults && typeof testResults.passed === "number"
+                ? {
+                    passed: testResults.passed,
+                    failed: testResults.failed ?? 0,
+                    skipped: testResults.skipped ?? 0,
+                }
+                : null,
+            success_criteria_met: Array.isArray(rawEvidence.success_criteria_met)
+                ? rawEvidence.success_criteria_met.filter((v) => typeof v === "string")
+                : [],
+            success_criteria_remaining: Array.isArray(rawEvidence.success_criteria_remaining)
+                ? rawEvidence.success_criteria_remaining.filter((v) => typeof v === "string")
+                : [],
+            progress_estimate: typeof rawEvidence.progress_estimate === "number"
+                ? Math.max(0, Math.min(1, rawEvidence.progress_estimate))
+                : 0.0,
+        });
+    }
+    // P5: Parse corrections
+    const retractedConstraints = Array.isArray(raw.retracted_constraints)
+        ? raw.retracted_constraints.filter((v) => typeof v === "string")
+        : [];
+    const revisedCriteria = Array.isArray(raw.revised_success_criteria)
+        ? raw.revised_success_criteria
+            .filter((v) => typeof v === "object" && v !== null &&
+            typeof v.old === "string" &&
+            typeof v.new === "string")
+            .map((v) => {
+            const r = v;
+            return { old: r.old, new: r.new };
+        })
+        : [];
+    const wrongAssumptions = Array.isArray(raw.wrong_assumptions)
+        ? raw.wrong_assumptions.filter((v) => typeof v === "string")
+        : [];
+    // Multi-agent: Parse worker delegation results
+    const workerResults = Array.isArray(raw.worker_results)
+        ? raw.worker_results
+            .filter((v) => typeof v === "object" && v !== null &&
+            typeof v.agentId === "string" &&
+            typeof v.subTask === "string" &&
+            typeof v.resultSummary === "string")
+            .map((v) => {
+            const w = v;
+            return {
+                agentId: w.agentId,
+                subAgentType: typeof w.subAgentType === "string" ? w.subAgentType : "general-purpose",
+                subTask: w.subTask,
+                resultSummary: w.resultSummary,
+                success: typeof w.success === "boolean" ? w.success : false,
+                discoveredConstraints: Array.isArray(w.discoveredConstraints)
+                    ? w.discoveredConstraints.filter((c) => typeof c === "string")
+                    : [],
+            };
+        })
+        : [];
+    return makeSelfEvaluation({
+        success: typeof raw.success === "boolean" ? raw.success : false,
+        output_summary: typeof raw.output_summary === "string" ? raw.output_summary : "",
+        constraint_violations: Array.isArray(raw.constraint_violations)
+            ? raw.constraint_violations.filter((v) => typeof v === "string")
+            : [],
+        should_continue: typeof raw.should_continue === "boolean" ? raw.should_continue : true,
+        // P0–P2: Optional evolution fields
+        discovered_constraints: Array.isArray(raw.discovered_constraints)
+            ? raw.discovered_constraints.filter((v) => typeof v === "string")
+            : [],
+        objective_refinement: typeof raw.objective_refinement === "string"
+            ? raw.objective_refinement
+            : "",
+        emerged_subtasks: Array.isArray(raw.emerged_subtasks)
+            ? raw.emerged_subtasks.filter((v) => typeof v === "string")
+            : [],
+        // P4: Execution evidence
+        execution_evidence: executionEvidence,
+        // P5: Self-correction
+        retracted_constraints: retractedConstraints,
+        revised_success_criteria: revisedCriteria,
+        wrong_assumptions: wrongAssumptions,
+        // Multi-agent: Worker delegation results
+        worker_results: workerResults,
+    });
+}
 /** Fallback heuristic when structured self-eval extraction fails.
  *  Scans agent output for completion and error signals.
  *  Returns a low-confidence SelfEvaluation — the autonomous runner
@@ -99,6 +191,17 @@ export class LoopForgeEngine {
         }
         return this.backend;
     }
+    /** Public accessor for the vault backend — used by runtime/verification gate. */
+    getBackend() {
+        return this.resolveBackend();
+    }
+    /** Expose engine health counters for observability (MCP status, logging). */
+    getMetrics() {
+        if (this.metrics === null) {
+            this.metrics = makeEngineMetrics();
+        }
+        return this.metrics;
+    }
     ensureInit(request) {
         if (this.state === null) {
             this.state = makeSessionState(request.task_id || makeTaskId(request.task));
@@ -148,7 +251,7 @@ export class LoopForgeEngine {
                             : "partial",
                         quality_score: signal.quality_score ?? 0,
                         constraint_compliance: {
-                            all_hard_constraints_met: !signal.violations,
+                            all_hard_constraints_met: !Array.isArray(signal.violations) || signal.violations.length === 0,
                             violations: signal.violations ?? [],
                         },
                         output_summary: signal.task_type ?? "",
@@ -165,6 +268,7 @@ export class LoopForgeEngine {
             catch {
                 if (this.metrics)
                     this.metrics.vaultWriteErrors++;
+                logEvent("vault_write_error", { error: "feedback_entry_build" });
             }
         }
         if (entries.length > 0) {
@@ -174,6 +278,7 @@ export class LoopForgeEngine {
             catch {
                 if (this.metrics)
                     this.metrics.vaultWriteErrors += entries.length;
+                logEvent("vault_write_error", { error: "feedback_append_entries", count: entries.length });
                 return 0;
             }
         }
@@ -234,6 +339,7 @@ export class LoopForgeEngine {
         catch {
             if (this.metrics)
                 this.metrics.vaultWriteErrors++;
+            logEvent("vault_write_error", { error: "persist_lineage_json" });
         }
         // 2. Markdown write (secondary, non-blocking)
         try {
@@ -254,10 +360,51 @@ export class LoopForgeEngine {
         catch {
             if (this.metrics)
                 this.metrics.vaultWriteErrors++;
+            logEvent("vault_write_error", { error: "persist_lineage_md" });
         }
         return vaultOk;
     }
     // ═══════════════════════════════════════════════════════════════════════
+    // Delegation journal (v1.9 — AgentTool mode)
+    // ═══════════════════════════════════════════════════════════════════════
+    /** Record sub-agent delegations for this round into the vault.
+     *  Written as a lightweight journal entry so the main agent's rolling
+     *  summary can reference delegation history in subsequent rounds. */
+    recordDelegation(loopId, round, entries) {
+        if (!entries.length)
+            return;
+        const entry = {
+            id: randomUUID(),
+            task_id: `loop:${loopId}:r${round}:delegations`,
+            version_tag: "v1",
+            is_active: true,
+            timestamp: new Date().toISOString().replace(/\.\d+Z$/, ""),
+            user_intent: `Delegation journal — round ${round}`,
+            task_type: "delegation_journal",
+            loop_id: loopId,
+            loop_lineage: {
+                round,
+                delegations: entries.map((e) => ({
+                    index: e.index,
+                    agentId: e.agentId,
+                    subAgentType: e.subAgentType,
+                    subTask: e.subTask,
+                    resultSummary: e.resultSummary,
+                    success: e.success,
+                    discoveredConstraints: e.discoveredConstraints,
+                })),
+            },
+        };
+        try {
+            this.resolveBackend().appendEntry(entry);
+        }
+        catch {
+            if (this.metrics)
+                this.metrics.vaultWriteErrors++;
+            logEvent("vault_write_error", { error: "record_delegation" });
+        }
+    }
+    // ═══════════════════════════════════════════════════════════════════════
     // Hydrate loop context from vault
     // ═══════════════════════════════════════════════════════════════════════
     hydrateLoopContext(loopId) {
@@ -309,6 +456,10 @@ export class LoopForgeEngine {
                 entry.constraint_violations =
                     lineage.constraint_violations ?? [];
             }
+            // v1.7: Ensure quality_score is always populated for failure lineage weighting
+            if (entry.quality_score === undefined || entry.quality_score === null) {
+                entry.quality_score = lineage.quality_score ?? 0;
+            }
         }
         // Enrich: attach full prompt text from Markdown for L0 cache reuse
         for (const entry of finalResults) {
@@ -328,37 +479,6 @@ export class LoopForgeEngine {
         return { results: finalResults, global_entries: [] };
     }
     // ═══════════════════════════════════════════════════════════════════════
-    // Build (internal)
-    // ═══════════════════════════════════════════════════════════════════════
-    invokeBuild(request, _hydrateResults) {
-        this.ensureInit(request);
-        this.lastTask = request.task;
-        const analysis = routeTechnique(request.task);
-        const technique = analysis.technique;
-        const rationale = analysis.rationale;
-        const promptSections = [
-            "## LoopForge Build",
-            `**Technique**: ${technique}`,
-            `**Rationale**: ${rationale}`,
-            "",
-            "### Task",
-            request.task,
-            "",
-            "### Instructions",
-            `Apply the **${technique}** technique to complete the task above.`,
-            "Respect all hard constraints and provide verifiable output.",
-        ];
-        return {
-            status: AgentStatus.OK,
-            response: {
-                status: AgentStatus.OK,
-                prompt: promptSections.join("\n"),
-                analysis,
-                error: null,
-            },
-        };
-    }
-    // ═══════════════════════════════════════════════════════════════════════
     // Feedback (public)
     // ═══════════════════════════════════════════════════════════════════════
     invokeFeedback(request, _hydrateResults) {
@@ -420,6 +540,12 @@ export class LoopForgeEngine {
         else {
             this.state.circuit_breaker_count = 0;
         }
+        logEvent("round_complete", {
+            technique: "feedback",
+            quality,
+            loopId: loopId ?? "unknown",
+            round: loopRound ?? this.state.call_count,
+        });
         return {
             status: AgentStatus.OK,
             response: {
@@ -440,6 +566,8 @@ export class LoopForgeEngine {
     // ═══════════════════════════════════════════════════════════════════════
     /** Record self-evaluation from agent output without human intervention.
      *  Converts SelfEvaluation → ExecutionFeedback → vault persistence.
+     *  P0–P2: Also persists discovered_constraints, objective_refinement,
+     *  and emerged_subtasks for the compiler to consume next round.
      *  Call this BEFORE invokeLoopCompile for the next round so that
      *  hydrateLoopContext picks up the latest quality scores. */
     autoFeedback(selfEval, loopId, round, task) {
@@ -456,6 +584,13 @@ export class LoopForgeEngine {
             manual_fixes_needed: fb.manual_fixes_needed,
         });
         const taskId = `loop:${loopId}:r${round}:feedback`;
+        // Multi-agent: Merge sub-agent discovered constraints into the main constraint flow
+        const subDiscovered = (selfEval.worker_results ?? [])
+            .flatMap((w) => w.discoveredConstraints ?? [])
+            .filter((c) => c.length > 0);
+        const mergedDiscovered = [
+            ...new Set([...(selfEval.discovered_constraints ?? []), ...subDiscovered]),
+        ];
         const signal = {
             task_id: taskId,
             task_type: task.slice(0, 80),
@@ -465,9 +600,34 @@ export class LoopForgeEngine {
             manual_fixes: "",
             loop_id: loopId,
             round,
+            // P0–P2: Evolution fields
+            discovered_constraints: mergedDiscovered,
+            objective_refinement: selfEval.objective_refinement ?? "",
+            emerged_subtasks: selfEval.emerged_subtasks ?? [],
+            // P4: Execution evidence
+            execution_evidence: selfEval.execution_evidence ?? null,
+            // P5: Self-correction
+            retracted_constraints: selfEval.retracted_constraints ?? [],
+            revised_success_criteria: selfEval.revised_success_criteria ?? [],
+            wrong_assumptions: selfEval.wrong_assumptions ?? [],
+            // Multi-agent: Worker delegation results
+            worker_results: selfEval.worker_results ?? [],
         };
         this.persistFeedbackToVault(signal);
         this.flushFeedbackBuffer();
+        // Multi-agent: Auto-record delegation journal from worker_results
+        if (selfEval.worker_results && selfEval.worker_results.length > 0) {
+            const entries = selfEval.worker_results.map((w, i) => ({
+                index: i + 1,
+                agentId: w.agentId,
+                subAgentType: w.subAgentType,
+                subTask: w.subTask,
+                resultSummary: w.resultSummary,
+                success: w.success,
+                discoveredConstraints: w.discoveredConstraints ?? [],
+            }));
+            this.recordDelegation(loopId, round, entries);
+        }
         // Update state
         this.state.call_count++;
         this.state.quality_trend.push(quality);
@@ -481,6 +641,12 @@ export class LoopForgeEngine {
         else {
             this.state.circuit_breaker_count = 0;
         }
+        logEvent("round_complete", {
+            loopId,
+            round,
+            quality,
+            technique: this.state?.last_technique ?? "feedback",
+        });
         return quality;
     }
     // ═══════════════════════════════════════════════════════════════════════
@@ -503,12 +669,47 @@ export class LoopForgeEngine {
             new_since_last_round: extras.new_since_last_round ?? "",
             force_level: extras.force_level ?? "auto",
             health_check_interval: extras.health_check_interval ?? 1,
+            external_context: extras.external_context ?? "",
         });
         // Convert last_round_result if present
         const lastRR = extras.last_round_result;
         if (lastRR) {
             if (typeof lastRR === "object" && !Array.isArray(lastRR)) {
                 const rr = lastRR;
+                // Parse P4 execution evidence
+                let executionEvidence;
+                const rawEvidence = rr.execution_evidence;
+                if (rawEvidence && typeof rawEvidence === "object") {
+                    const testResults = rawEvidence.test_results;
+                    executionEvidence = makeExecutionEvidence({
+                        files_changed: Array.isArray(rawEvidence.files_changed)
+                            ? rawEvidence.files_changed.filter((v) => typeof v === "string")
+                            : [],
+                        test_results: testResults && typeof testResults.passed === "number"
+                            ? {
+                                passed: testResults.passed,
+                                failed: testResults.failed ?? 0,
+                                skipped: testResults.skipped ?? 0,
+                            }
+                            : null,
+                        success_criteria_met: Array.isArray(rawEvidence.success_criteria_met)
+                            ? rawEvidence.success_criteria_met.filter((v) => typeof v === "string")
+                            : [],
+                        success_criteria_remaining: Array.isArray(rawEvidence.success_criteria_remaining)
+                            ? rawEvidence.success_criteria_remaining.filter((v) => typeof v === "string")
+                            : [],
+                        progress_estimate: typeof rawEvidence.progress_estimate === "number"
+                            ? Math.max(0, Math.min(1, rawEvidence.progress_estimate))
+                            : 0.0,
+                    });
+                }
+                // Parse P5 revised_success_criteria
+                const revisedCriteria = Array.isArray(rr.revised_success_criteria)
+                    ? rr.revised_success_criteria
+                        .filter((v) => typeof v === "object" && v !== null &&
+                        typeof v.old === "string" && typeof v.new === "string")
+                        .map((v) => ({ old: v.old, new: v.new }))
+                    : [];
                 lcr.last_round_result = makeLoopRoundResult({
                     round: rr.round ?? 0,
                     success: rr.success ?? false,
@@ -516,6 +717,41 @@ export class LoopForgeEngine {
                     constraint_violations: rr.constraint_violations ?? [],
                     manual_fixes_needed: rr.manual_fixes_needed ?? "",
                     quality_score: rr.quality_score ?? 0,
+                    // P0–P2: Cognitive evolution fields
+                    discovered_constraints: Array.isArray(rr.discovered_constraints)
+                        ? rr.discovered_constraints.filter((v) => typeof v === "string")
+                        : [],
+                    objective_refinement: typeof rr.objective_refinement === "string"
+                        ? rr.objective_refinement
+                        : "",
+                    emerged_subtasks: Array.isArray(rr.emerged_subtasks)
+                        ? rr.emerged_subtasks.filter((v) => typeof v === "string")
+                        : [],
+                    // P4: Execution evidence
+                    execution_evidence: executionEvidence,
+                    // P5: Self-correction
+                    retracted_constraints: Array.isArray(rr.retracted_constraints)
+                        ? rr.retracted_constraints.filter((v) => typeof v === "string")
+                        : [],
+                    revised_success_criteria: revisedCriteria,
+                    wrong_assumptions: Array.isArray(rr.wrong_assumptions)
+                        ? rr.wrong_assumptions.filter((v) => typeof v === "string")
+                        : [],
+                    // Multi-agent: Worker delegation results
+                    worker_results: Array.isArray(rr.worker_results)
+                        ? rr.worker_results
+                            .filter((v) => typeof v?.agentId === "string" && typeof v?.subTask === "string")
+                            .map((v) => ({
+                            agentId: v.agentId,
+                            subAgentType: typeof v.subAgentType === "string" ? v.subAgentType : "general-purpose",
+                            subTask: v.subTask,
+                            resultSummary: typeof v.resultSummary === "string" ? v.resultSummary : "",
+                            success: typeof v.success === "boolean" ? v.success : false,
+                            discoveredConstraints: Array.isArray(v.discoveredConstraints)
+                                ? v.discoveredConstraints
+                                : [],
+                        }))
+                        : [],
                 });
             }
         }
@@ -568,6 +804,22 @@ export class LoopForgeEngine {
                 promptLines.push(`- ⚠️ ${w}`);
             }
         }
+        // Verification gate flags (v1.6) — injected after compiler warnings
+        const verificationFlags = extras.verification_flags ?? [];
+        if (verificationFlags.length) {
+            promptLines.push("");
+            promptLines.push("### Verification Gate");
+            for (const f of verificationFlags) {
+                const icon = f.severity === "error" ? "🚫" : "⚠️";
+                promptLines.push(`- ${icon} [${f.check}] ${f.detail}`);
+            }
+            const hasError = verificationFlags.some((f) => f.severity === "error");
+            if (hasError) {
+                promptLines.push("");
+                promptLines.push("**Gate Verdict: CONTRADICTED** — this round's quality score has been excluded " +
+                    "from the quality trend. Address each 🚫 flag explicitly in your next response.");
+            }
+        }
         if (response.loop_health) {
             const h = response.loop_health;
             promptLines.push("");
@@ -617,67 +869,6 @@ export class LoopForgeEngine {
         };
     }
     // ═══════════════════════════════════════════════════════════════════════
-    // Review handler
-    // ═══════════════════════════════════════════════════════════════════════
-    handleReview(request, hydrateResults) {
-        if (!hydrateResults) {
-            return {
-                status: AgentStatus.ERROR,
-                response: {
-                    status: AgentStatus.ERROR,
-                    prompt: null,
-                    analysis: null,
-                    error: "Review mode requires hydrate_results (prompt to review).",
-                },
-            };
-        }
-        const results = hydrateResults.results ?? [];
-        if (!results.length) {
-            return {
-                status: AgentStatus.ERROR,
-                response: {
-                    status: AgentStatus.ERROR,
-                    prompt: null,
-                    analysis: null,
-                    error: "No matching prompt found in vault to review.",
-                },
-            };
-        }
-        const promptData = results[0];
-        const fullText = promptData.full_prompt ?? "";
-        const issues = [];
-        // Structural checks
-        const requiredSections = [
-            "角色", "任务", "输入", "输出格式", "硬约束", "生成要求",
-        ];
-        for (const section of requiredSections) {
-            if (!fullText.includes(section)) {
-                issues.push(`Missing section: ${section}`);
-            }
-        }
-        // Constraint check
-        const globalEntries = hydrateResults.global_entries ?? [];
-        for (const entry of globalEntries) {
-            for (const c of entry.hard_constraints_added ?? []) {
-                if (!fullText.includes(c)) {
-                    issues.push(`GLOBAL constraint not reflected: ${c}`);
-                }
-            }
-        }
-        const reviewReport = issues.length
-            ? issues.map((i) => `- ${i}`).join("\n")
-            : "All checks passed.";
-        return {
-            status: AgentStatus.OK,
-            response: {
-                status: AgentStatus.OK,
-                prompt: `## Review Report\n\n${reviewReport}\n\n---\n\n${fullText}`,
-                analysis: null,
-                error: null,
-            },
-        };
-    }
-    // ═══════════════════════════════════════════════════════════════════════
     // Circuit breaker
     // ═══════════════════════════════════════════════════════════════════════
     shouldBreak() {
@@ -688,7 +879,14 @@ export class LoopForgeEngine {
         if (this.state.quality_trend.length < maxCB)
             return false;
         const recent = this.state.quality_trend.slice(-maxCB);
-        return recent.every((val, i) => i === 0 || recent[i - 1] >= val);
+        const isFlat = recent.every((val, i) => i === 0 || recent[i - 1] >= val);
+        if (isFlat) {
+            logEvent("circuit_breaker", {
+                trend: recent,
+                totalRounds: this.state.quality_trend.length,
+            });
+        }
+        return isFlat;
     }
 }
 // ═══════════════════════════════════════════════════════════════════════════