loopforge 1.0.0 → 1.3.0

package/dist/autonomous.d.ts

@@ -0,0 +1,84 @@
+/** LoopForge — Autonomous loop driver (v1.1).
+ *
+ *  Closes the feedback loop: compile → agent executes → extract self-eval →
+ *  auto-feedback → compile next → ... until task complete or circuit breaker.
+ *
+ *  Zero API dependencies — LoopForge does NOT call AI APIs. The caller
+ *  provides an execute callback or feeds agent output round by round.
+ */
+import { type LoopHealth, type SelfEvaluation } from "./protocol.js";
+import { LoopForgeEngine } from "./engine.js";
+export interface AutonomousConfig {
+    /** The task description — becomes the loop objective. */
+    task: string;
+    /** Kebab-case loop identifier. */
+    loopId: string;
+    /** Optional explicit goal ID. Derived from task if omitted. */
+    goalId?: string;
+    /** Maximum rounds before forced stop. Default 20. */
+    maxRounds?: number;
+    /** Health check interval (rounds). Default 3. */
+    healthCheckInterval?: number;
+    /** Optional path to a plan/spec file for constraint extraction. */
+    planSource?: string;
+    /** Constraints extracted from the plan (provided by caller). */
+    constraintsFromPlan?: string[];
+    /** Domain hint for technique routing. */
+    domain?: string;
+}
+export interface RoundOutput {
+    round: number;
+    /** The compiled prompt — ready for agent execution. */
+    prompt: string;
+    /** L0 | L1 | L2 */
+    recompileLevel: string;
+    /** Selected prompting technique. */
+    techniqueUsed: string;
+    /** Cross-round health snapshot (null on round 1 if no prior data). */
+    health: LoopHealth | null;
+    /** Quality score from the PREVIOUS round (null on round 1). */
+    lastQualityScore: number | null;
+}
+export type StopReason = "task_complete" | "circuit_breaker" | "max_rounds" | "stalled" | "extraction_failed";
+export interface AutonomousResult {
+    /** Total rounds completed. */
+    roundsCompleted: number;
+    /** Why the loop stopped. */
+    stopReason: StopReason;
+    /** Health snapshot at stop. */
+    healthAtStop: LoopHealth | null;
+    /** Quality trajectory [round1_score, round2_score, ...]. */
+    qualityTrajectory: number[];
+    /** Whether the loop achieved its objective. */
+    success: boolean;
+}
+export interface RunOneRoundResult {
+    /** If stopNow is true, the loop should terminate. */
+    stopNow: boolean;
+    stopReason: StopReason | null;
+    /** The compiled prompt (null if stopping). */
+    roundOutput: RoundOutput | null;
+    /** Extracted self-evaluation (null on round 1 or if extraction failed). */
+    selfEval: SelfEvaluation | null;
+    /** Whether structured extraction succeeded. */
+    extractionSucceeded: boolean;
+}
+/** Run one round of the autonomous loop.
+ *
+ *  Round 1 (agentOutput = null): compile the first prompt (L2 full build).
+ *  Round N (agentOutput = string): extract self-eval, record auto-feedback,
+ *    compile next prompt (L0/L1/L2 decided by the 4-gate router).
+ *
+ *  Returns stopNow = true when the loop should terminate. */
+export declare function runOneRound(engine: LoopForgeEngine, config: AutonomousConfig, currentRound: number, agentOutput: string | null): RunOneRoundResult;
+/** Execute callback: takes a compiled prompt, returns the agent's output. */
+export type AgentExecutor = (prompt: string, round: number) => Promise<string>;
+/** Run a fully autonomous loop from start to finish.
+ *
+ *  The `execute` callback is called with each compiled prompt.
+ *  LoopForge does NOT call any AI API — the caller provides execution.
+ *
+ *  Stops when: task complete, circuit breaker triggered, max rounds
+ *  reached, or self-eval extraction fails. */
+export declare function runAutonomousLoop(engine: LoopForgeEngine, config: AutonomousConfig, execute: AgentExecutor): Promise<AutonomousResult>;
+//# sourceMappingURL=autonomous.d.ts.map

package/dist/autonomous.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autonomous.d.ts","sourceRoot":"","sources":["../src/autonomous.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAKL,KAAK,UAAU,EACf,KAAK,cAAc,EACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,eAAe,EAIhB,MAAM,aAAa,CAAC;AAMrB,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,oCAAoC;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IAC1B,+DAA+D;IAC/D,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,MAAM,UAAU,GAClB,eAAe,GACf,iBAAiB,GACjB,YAAY,GACZ,SAAS,GACT,mBAAmB,CAAC;AAExB,MAAM,WAAW,gBAAgB;IAC/B,8BAA8B;IAC9B,eAAe,EAAE,MAAM,CAAC;IACxB,4BAA4B;IAC5B,UAAU,EAAE,UAAU,CAAC;IACvB,+BAA+B;IAC/B,YAAY,EAAE,UAAU,GAAG,IAAI,CAAC;IAChC,4DAA4D;IAC5D,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;CAClB;AAMD,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B,8CAA8C;IAC9C,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IAChC,2EAA2E;IAC3E,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IAChC,+CAA+C;IAC/C,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;6DAM6D;AAC7D,wBAAgB,WAAW,CACzB,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,gBAAgB,EACxB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,GAAG,IAAI,GACzB,iBAAiB,CAwLnB;AAMD,6EAA6E;AAC7E,MAAM,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE/E;;;;;;8CAM8C;AAC9C,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,gBAAgB,CAAC,CAiE3B"}

package/dist/autonomous.js

@@ -0,0 +1,250 @@
+/** LoopForge — Autonomous loop driver (v1.1).
+ *
+ *  Closes the feedback loop: compile → agent executes → extract self-eval →
+ *  auto-feedback → compile next → ... until task complete or circuit breaker.
+ *
+ *  Zero API dependencies — LoopForge does NOT call AI APIs. The caller
+ *  provides an execute callback or feeds agent output round by round.
+ */
+import { makeLoopCompileRequest, makeLoopRoundResult, makeVaultConfig, } from "./protocol.js";
+import { extractSelfEvaluation, heuristicSelfEvaluation, } from "./engine.js";
+/** Run one round of the autonomous loop.
+ *
+ *  Round 1 (agentOutput = null): compile the first prompt (L2 full build).
+ *  Round N (agentOutput = string): extract self-eval, record auto-feedback,
+ *    compile next prompt (L0/L1/L2 decided by the 4-gate router).
+ *
+ *  Returns stopNow = true when the loop should terminate. */
+export function runOneRound(engine, config, currentRound, agentOutput) {
+    const maxRounds = config.maxRounds ?? 20;
+    const healthInterval = config.healthCheckInterval ?? 3;
+    // ── Check max rounds before doing anything ──────────────────────────
+    if (currentRound > maxRounds) {
+        return {
+            stopNow: true,
+            stopReason: "max_rounds",
+            roundOutput: null,
+            selfEval: null,
+            extractionSucceeded: false,
+        };
+    }
+    // ── Round N (N > 1): Extract self-eval and record feedback ──────────
+    let selfEval = null;
+    let extractionSucceeded = false;
+    if (agentOutput !== null && currentRound > 1) {
+        // Try structured extraction first
+        selfEval = extractSelfEvaluation(agentOutput);
+        extractionSucceeded = selfEval !== null;
+        // Fallback to heuristic if structured extraction failed
+        const usedHeuristic = selfEval === null;
+        if (selfEval === null) {
+            selfEval = heuristicSelfEvaluation(agentOutput);
+        }
+        // Record auto-feedback (even heuristic — best effort for vault audit trail)
+        if (selfEval !== null) {
+            engine.autoFeedback(selfEval, config.loopId, currentRound - 1, // feedback is for the PREVIOUS round
+            config.task);
+        }
+        // Stop if structured extraction failed — heuristic is too low-confidence
+        // to continue the loop autonomously
+        if (usedHeuristic) {
+            return {
+                stopNow: true,
+                stopReason: "extraction_failed",
+                roundOutput: null,
+                selfEval,
+                extractionSucceeded: false,
+            };
+        }
+        // Check stop conditions from agent's self-eval (structured only)
+        if (selfEval !== null && !selfEval.should_continue) {
+            return {
+                stopNow: true,
+                stopReason: "task_complete",
+                roundOutput: null,
+                selfEval,
+                extractionSucceeded,
+            };
+        }
+        // Check circuit breaker after recording feedback
+        if (engine.shouldBreak()) {
+            return {
+                stopNow: true,
+                stopReason: "circuit_breaker",
+                roundOutput: null,
+                selfEval,
+                extractionSucceeded,
+            };
+        }
+        // Check if extraction failed entirely
+        if (selfEval === null) {
+            return {
+                stopNow: true,
+                stopReason: "extraction_failed",
+                roundOutput: null,
+                selfEval: null,
+                extractionSucceeded: false,
+            };
+        }
+    }
+    // ── Compile the next prompt ────────────────────────────────────────
+    const lcr = makeLoopCompileRequest({
+        loop_id: config.loopId,
+        round: currentRound,
+        goal_id: config.goalId ?? "",
+        task: config.task,
+        domain: config.domain ?? "",
+        plan_source: config.planSource ?? null,
+        constraints_from_plan: config.constraintsFromPlan ?? [],
+        health_check_interval: healthInterval,
+        vault_config: makeVaultConfig(),
+    });
+    // Attach last round result if we have self-eval data
+    if (selfEval !== null && currentRound > 1) {
+        lcr.last_round_result = makeLoopRoundResult({
+            round: currentRound - 1,
+            success: selfEval.success,
+            output_summary: selfEval.output_summary,
+            constraint_violations: selfEval.constraint_violations,
+            manual_fixes_needed: "",
+            quality_score: 0, // Will be backfilled from vault
+        });
+    }
+    const result = engine.invokeLoopCompile({
+        task: config.task,
+        mode: "loop_compile",
+        vault_config: makeVaultConfig(),
+        feedback: null,
+        skill_name: null,
+        task_id: null,
+        loop_id: config.loopId,
+        round: currentRound,
+        goal_id: config.goalId ?? "",
+        domain: config.domain ?? "",
+        plan_source: config.planSource ?? null,
+        constraints_from_plan: config.constraintsFromPlan ?? [],
+        health_check_interval: healthInterval,
+        last_round_result: lcr.last_round_result ?? undefined,
+    });
+    if (result.status === "error" || !result.response?.prompt) {
+        return {
+            stopNow: true,
+            stopReason: "stalled",
+            roundOutput: null,
+            selfEval,
+            extractionSucceeded,
+        };
+    }
+    // Extract health from the response (it's embedded in the prompt text as markdown)
+    // The health data is in the LoopCompileResponse, but we need to get it from the engine
+    const context = engine.hydrateLoopContext(config.loopId);
+    let health = null;
+    if (context) {
+        const results = context.results ?? [];
+        const latest = results[results.length - 1];
+        if (latest) {
+            const lineage = (latest.loop_lineage ?? {});
+            // Health is computed per-round, not stored directly in lineage
+            // We'll report null for simplicity — the prompt text contains health info
+        }
+    }
+    // Determine last quality score
+    let lastQuality = null;
+    if (selfEval !== null) {
+        const fb = selfEval;
+        // Recompute using the same formula as scoreQuality
+        if (fb.success && fb.constraint_violations.length === 0)
+            lastQuality = 5;
+        else if (fb.success && fb.constraint_violations.length === 0)
+            lastQuality = 4;
+        else if (fb.success)
+            lastQuality = 3;
+        else if (fb.constraint_violations.length > 0)
+            lastQuality = 2;
+        else
+            lastQuality = 1;
+    }
+    return {
+        stopNow: false,
+        stopReason: null,
+        roundOutput: {
+            round: currentRound,
+            prompt: result.response.prompt,
+            recompileLevel: result.response.analysis?.rationale?.includes("l0")
+                ? "l0"
+                : result.response.analysis?.rationale?.includes("l1")
+                    ? "l1"
+                    : "l2",
+            techniqueUsed: result.response.analysis?.technique ?? "unknown",
+            health,
+            lastQualityScore: lastQuality,
+        },
+        selfEval,
+        extractionSucceeded,
+    };
+}
+/** Run a fully autonomous loop from start to finish.
+ *
+ *  The `execute` callback is called with each compiled prompt.
+ *  LoopForge does NOT call any AI API — the caller provides execution.
+ *
+ *  Stops when: task complete, circuit breaker triggered, max rounds
+ *  reached, or self-eval extraction fails. */
+export async function runAutonomousLoop(engine, config, execute) {
+    const maxRounds = config.maxRounds ?? 20;
+    const qualityTrajectory = [];
+    let agentOutput = null;
+    let finalStopReason = "max_rounds";
+    for (let round = 1; round <= maxRounds; round++) {
+        const roundResult = runOneRound(engine, config, round, agentOutput);
+        if (roundResult.stopNow) {
+            finalStopReason = roundResult.stopReason ?? "stalled";
+            break;
+        }
+        if (!roundResult.roundOutput) {
+            finalStopReason = "stalled";
+            break;
+        }
+        // Track quality
+        if (roundResult.roundOutput.lastQualityScore !== null) {
+            qualityTrajectory.push(roundResult.roundOutput.lastQualityScore);
+        }
+        // Execute the prompt
+        try {
+            agentOutput = await execute(roundResult.roundOutput.prompt, round);
+        }
+        catch {
+            finalStopReason = "stalled";
+            break;
+        }
+        // If this was the last round and we didn't stop earlier
+        if (round === maxRounds) {
+            finalStopReason = "max_rounds";
+        }
+    }
+    // Get final health snapshot
+    let healthAtStop = null;
+    try {
+        const context = engine.hydrateLoopContext(config.loopId);
+        if (context) {
+            const results = context.results ?? [];
+            if (results.length > 0) {
+                const latest = results[results.length - 1];
+                const lineage = (latest.loop_lineage ?? {});
+                // Health is in the lineage if it was stored
+                healthAtStop = lineage.loop_health ?? null;
+            }
+        }
+    }
+    catch {
+        // Best effort
+    }
+    return {
+        roundsCompleted: qualityTrajectory.length,
+        stopReason: finalStopReason,
+        healthAtStop,
+        qualityTrajectory,
+        success: finalStopReason === "task_complete",
+    };
+}
+//# sourceMappingURL=autonomous.js.map

package/dist/autonomous.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"autonomous.js","sourceRoot":"","sources":["../src/autonomous.ts"],"names":[],"mappings":"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"}

package/dist/backends/ai.d.ts

@@ -0,0 +1,37 @@
+/** LoopForge — Anthropic API backend (v1.1).
+ *
+ *  Calls Claude API via Node.js built-in fetch. Zero additional dependencies.
+ *  Uses ANTHROPIC_API_KEY from environment. Falls back gracefully on failure.
+ */
+export interface AiConfig {
+    /** Anthropic API key. Default: process.env.ANTHROPIC_API_KEY */
+    apiKey?: string;
+    /** Model ID. Default: claude-sonnet-4-6 */
+    model?: string;
+    /** Max output tokens. Default: 8192 */
+    maxTokens?: number;
+    /** Base URL override (for proxies / alternative endpoints). */
+    baseUrl?: string;
+    /** Timeout in ms. Default: 300_000 (5 min). */
+    timeoutMs?: number;
+}
+export interface AiResult {
+    /** The model's text response, or null on failure. */
+    text: string | null;
+    /** True if the API call succeeded. */
+    ok: boolean;
+    /** Error message if !ok. */
+    error: string | null;
+    /** Model used. */
+    model: string;
+}
+/** Call Claude with a single user message. Returns the text response. */
+export declare function callClaude(prompt: string, config?: AiConfig): Promise<AiResult>;
+import type { AgentExecutor } from "../autonomous.js";
+/** Create an AgentExecutor backed by Claude API.
+ *  Usage:
+ *    const executor = createClaudeExecutor({ apiKey: "sk-ant-..." });
+ *    const result = await runAutonomousLoop(engine, config, executor);
+ */
+export declare function createClaudeExecutor(aiConfig?: AiConfig): AgentExecutor;
+//# sourceMappingURL=ai.d.ts.map

package/dist/backends/ai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.d.ts","sourceRoot":"","sources":["../../src/backends/ai.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,MAAM,WAAW,QAAQ;IACvB,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,QAAQ;IACvB,qDAAqD;IACrD,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,sCAAsC;IACtC,EAAE,EAAE,OAAO,CAAC;IACZ,4BAA4B;IAC5B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,kBAAkB;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAQD,yEAAyE;AACzE,wBAAsB,UAAU,CAC9B,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,QAAa,GACpB,OAAO,CAAC,QAAQ,CAAC,CA+EnB;AAMD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,GAAE,QAAa,GAAG,aAAa,CAQ3E"}

package/dist/backends/ai.js

@@ -0,0 +1,98 @@
+/** LoopForge — Anthropic API backend (v1.1).
+ *
+ *  Calls Claude API via Node.js built-in fetch. Zero additional dependencies.
+ *  Uses ANTHROPIC_API_KEY from environment. Falls back gracefully on failure.
+ */
+// ═══════════════════════════════════════════════════════════════════════════
+// API call
+// ═══════════════════════════════════════════════════════════════════════════
+const DEFAULT_BASE_URL = "https://api.anthropic.com/v1";
+/** Call Claude with a single user message. Returns the text response. */
+export async function callClaude(prompt, config = {}) {
+    const apiKey = config.apiKey ?? process.env.ANTHROPIC_API_KEY ?? "";
+    const model = config.model ?? process.env.LOOPFORGE_MODEL ?? "claude-sonnet-4-6";
+    const maxTokens = config.maxTokens ?? 8192;
+    const baseUrl = config.baseUrl ?? process.env.ANTHROPIC_BASE_URL ?? DEFAULT_BASE_URL;
+    const timeoutMs = config.timeoutMs ?? 300_000;
+    if (!apiKey) {
+        return {
+            text: null,
+            ok: false,
+            error: "ANTHROPIC_API_KEY not set. Export it or pass apiKey in config.",
+            model,
+        };
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const resp = await fetch(`${baseUrl}/messages`, {
+            method: "POST",
+            headers: {
+                "x-api-key": apiKey,
+                "anthropic-version": "2023-06-01",
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({
+                model,
+                max_tokens: maxTokens,
+                messages: [{ role: "user", content: prompt }],
+            }),
+            signal: controller.signal,
+        });
+        clearTimeout(timer);
+        if (!resp.ok) {
+            const body = await resp.text().catch(() => "");
+            return {
+                text: null,
+                ok: false,
+                error: `API returned ${resp.status}: ${body.slice(0, 300)}`,
+                model,
+            };
+        }
+        const data = (await resp.json());
+        const content = data.content;
+        if (!Array.isArray(content) || content.length === 0) {
+            return {
+                text: null, ok: false,
+                error: `Unexpected response shape: ${JSON.stringify(data).slice(0, 200)}`,
+                model,
+            };
+        }
+        const first = content[0];
+        const text = String(first.text ?? "");
+        if (!text) {
+            return {
+                text: null, ok: false,
+                error: "Empty response text from model.",
+                model,
+            };
+        }
+        return { text, ok: true, error: null, model };
+    }
+    catch (err) {
+        clearTimeout(timer);
+        if (err instanceof DOMException && err.name === "AbortError") {
+            return { text: null, ok: false, error: `Request timed out after ${timeoutMs}ms`, model };
+        }
+        return {
+            text: null, ok: false,
+            error: `Fetch error: ${err instanceof Error ? err.message : String(err)}`,
+            model,
+        };
+    }
+}
+/** Create an AgentExecutor backed by Claude API.
+ *  Usage:
+ *    const executor = createClaudeExecutor({ apiKey: "sk-ant-..." });
+ *    const result = await runAutonomousLoop(engine, config, executor);
+ */
+export function createClaudeExecutor(aiConfig = {}) {
+    return async (prompt, _round) => {
+        const result = await callClaude(prompt, aiConfig);
+        if (!result.ok || result.text === null) {
+            throw new Error(`Claude API error (round ${_round}): ${result.error}`);
+        }
+        return result.text;
+    };
+}
+//# sourceMappingURL=ai.js.map

package/dist/backends/ai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.js","sourceRoot":"","sources":["../../src/backends/ai.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /** LoopForge CLI — command-line interface for the loop compiler.
  *
- * v1.0 — npm install loopforge
+ * v1.2 — npm install loopforge
  */
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -1,16 +1,17 @@
 #!/usr/bin/env node
 /** LoopForge CLI — command-line interface for the loop compiler.
  *
- * v1.0 — npm install loopforge
+ * v1.2 — npm install loopforge
  */
 import { createEngine } from "./engine.js";
 import { FSBackend } from "./backends/fs.js";
 import { ReplayBackend } from "./replay.js";
-import { makeExecutionFeedback, } from "./protocol.js";
+import { Mode, makeExecutionFeedback, } from "./protocol.js";
+import { LoopRuntime } from "./runtime.js";
 // ═══════════════════════════════════════════════════════════════════════════
 // Constants
 // ═══════════════════════════════════════════════════════════════════════════
-const VERSION = "1.0.0";
+const VERSION = "1.2.0";
 const VAULT_CONFIG = {
     project_vault: ".promptcraft/prompt_vault.json",
     global_vault: "~/.promptcraft/global_vault.json",
@@ -23,6 +24,7 @@ Usage:
   loopforge init                  Initialise .promptcraft vault
   loopforge compile [json]        Compile a loop prompt
   loopforge feedback [json]       Record execution feedback
+  loopforge run [json]            Autonomous loop (event-driven runtime)
   loopforge replay <loop-id>      Show loop timeline
   loopforge diff <loop-id> <a> <b> Diff two rounds
   loopforge review <loop-id> <rN> Audit stored prompt
@@ -38,6 +40,7 @@ const CMD_HELP = {
     init: "loopforge init — create .promptcraft/prompt_vault.json if it doesn't exist.",
     compile: "loopforge compile '<json>' — run loop_compile (L0/L1/L2).\n  Required: task, loop_id, goal_id. Optional: round, domain, constraints_from_plan, new_since_last_round, force_level.",
     feedback: "loopforge feedback '<json>' — record execution result.\n  Flat: {loop_id, round, success, score, output}\n  Nested: {loop_id, round, feedback: {success, score, output}}",
+    run: "loopforge run '<json>' — autonomous loop (v1.2).\n  Required: task, loop_id. Optional: max_rounds (default 20), plan_source, domain.\n  Outputs compiled prompt → reads agent output from stdin → continues until task complete or circuit breaker.",
     replay: "loopforge replay <loop-id> — show timeline: round, recompile level, quality, technique, task.",
     diff: "loopforge diff <loop-id> <round-a> <round-b> — field-level comparison between two rounds.",
     review: "loopforge review <loop-id> <round-num> — structural audit of a stored prompt.",
@@ -128,7 +131,7 @@ async function cmdCompile(engine, jsonArg) {
     const data = parseJson(raw);
     const result = engine.invokeLoopCompile({
         task: data.task ?? "",
-        mode: "loop_compile",
+        mode: Mode.LOOP_COMPILE,
         vault_config: { ...VAULT_CONFIG },
         feedback: null,
         skill_name: null,
@@ -159,7 +162,7 @@ async function cmdFeedback(engine, jsonArg) {
     }
     const result = engine.invokeFeedback({
         task: data.task ?? "",
-        mode: "feedback",
+        mode: Mode.FEEDBACK,
         vault_config: { ...VAULT_CONFIG },
         feedback: makeExecutionFeedback({
             output: fbPayload.output ?? "",
@@ -269,7 +272,7 @@ function cmdReview(loopId, roundStr) {
     }
     const result = engine.handleReview({
         task: target.task ?? "review",
-        mode: "review",
+        mode: Mode.REVIEW,
         vault_config: { ...VAULT_CONFIG },
         feedback: null,
         skill_name: null,
@@ -277,6 +280,62 @@ function cmdReview(loopId, roundStr) {
     }, { results: [target], global_entries: [] });
     console.log(result.response?.prompt ?? "Review produced no output.");
 }
+async function cmdRun(_engine, jsonArg) {
+    if (jsonArg === "--help" || jsonArg === "-h") {
+        showHelp("run");
+        return;
+    }
+    let raw;
+    if (jsonArg) {
+        raw = jsonArg;
+    }
+    else {
+        raw = await readStdin();
+    }
+    if (!raw.trim())
+        die("run requires JSON input (argument or stdin)");
+    const data = parseJson(raw);
+    const task = data.task ?? "";
+    const loopId = data.loop_id ?? "";
+    if (!task)
+        die("run requires 'task' field");
+    if (!loopId)
+        die("run requires 'loop_id' field");
+    const maxRounds = data.max_rounds ?? 20;
+    const runtime = new LoopRuntime({
+        task,
+        loopId,
+        maxRounds,
+        interactive: true,
+        goalId: data.goal_id ?? undefined,
+        planSource: data.plan_source ?? undefined,
+        constraintsFromPlan: data.constraints_from_plan ?? [],
+        domain: data.domain ?? "",
+        onRoundStart: (info) => {
+            console.log(`\n=== Round ${info.round} | Level: ${info.level.toUpperCase()} | ` +
+                `Technique: ${info.technique} ===\n`);
+            console.log(info.prompt);
+            console.log(`\n=== End Round ${info.round} Prompt ===\n` +
+                `[Paste agent output, then press Ctrl+D (Unix) or Ctrl+Z (Windows) to continue]\n`);
+        },
+        execute: async (_prompt, _ctx) => {
+            const output = await readStdin();
+            if (!output.trim()) {
+                throw new Error("No agent output provided.");
+            }
+            return output;
+        },
+    });
+    const result = await runtime.start();
+    console.log(`\n--- Loop stopped: ${result.stopReason} ---`);
+    console.log(`Rounds: ${result.roundsCompleted} | ` +
+        `Quality: [${result.qualityTrajectory.join(", ")}]`);
+    if (result.stopReason === "stalled" && result.qualityTrajectory.length > 0) {
+        const lastRound = result.roundsCompleted;
+        console.log(`WARNING: Could not extract self-evaluation from agent output in round ${lastRound}. ` +
+            "Ensure the agent outputs a ---loopforge-eval block.");
+    }
+}
 function cmdStatus() {
     const backend = new FSBackend();
     const vault = backend.readVault();
@@ -334,6 +393,9 @@ async function main() {
         case "feedback":
             await cmdFeedback(engine, args[1]);
             break;
+        case "run":
+            await cmdRun(engine, args[1]);
+            break;
         case "replay":
             cmdReplay(args[1]);
             break;