loopforge 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kyrielrving11
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# LoopForge
+
+**Loop-Time Intelligence Layer** for AI coding agents. Per-iteration prompt compiler
+with structured memory, constraint inheritance, and drift correction — maintains
+cognitive stability across long-horizon agent loops.
+
+Spec: [`../docs/loopforge-spec.md`](../docs/loopforge-spec.md)
+
+## Quick Start
+
+```bash
+npm install loopforge
+
+# CLI
+npx loopforge init
+npx loopforge compile '{"task":"Audit ERC20","loop_id":"audit","round":1,"goal_id":"audit"}'
+npx loopforge status
+```
+
+```typescript
+// Library API
+import { createEngine, ReplayBackend, FSBackend } from "loopforge";
+
+const engine = createEngine();
+const result = engine.invokeLoopCompile({
+  task: "Audit ERC20 token",
+  mode: "loop_compile",
+  loop_id: "audit",
+  round: 1,
+  goal_id: "audit",
+});
+```
+
+## 3 Modes
+
+| Mode | When | Returns |
+|------|------|---------|
+| `loop_compile` | Every agent loop iteration | Compiled prompt + recompile level + health + advisories |
+| `feedback` | After execution | Quality score → vault persistence |
+| `review` | Audit prompt quality | Structural checks + constraint compliance |
+
+## Recompile Levels
+
+- **L0 Fast Path** — goal unchanged, no new failures → reuse cached prompt
+- **L1 Patch** — new constraints or repair signals → patch previous prompt
+- **L2 Full Recompile** — round 1, goal changed, plan_source, strategy collapse → full build
+
+## CLI Commands
+
+```bash
+loopforge init                     # Init vault
+loopforge compile '<json>'         # Compile prompt (or pipe via stdin)
+loopforge feedback '<json>'        # Record feedback
+loopforge replay <loop-id>         # Loop timeline
+loopforge diff <loop-id> <a> <b>   # Diff two rounds
+loopforge review <loop-id> <rN>    # Audit stored prompt
+loopforge status                   # Vault health
+```
+
+## API Modules
+
+| Module | Import | Purpose |
+|--------|--------|---------|
+| `loopforge` | Main entry | `handle`, `createEngine`, types |
+| `loopforge/compiler` | `compileLoop`, `decideLevel` | Pure-function compiler |
+| `loopforge/replay` | `ReplayBackend` | Time-travel audit queries |
+
+## Zero Dependencies
+
+No runtime dependencies — Node.js stdlib only. TypeScript strict mode.
+Tests use Node.js built-in test runner (`node:test`).
+
+## License
+
+MIT

package/dist/adapter.d.ts

@@ -0,0 +1,17 @@
+/** LoopForge-loop_compile — Sub-agent adapter (unified entry point).
+ *
+ * This is the single entry point when LoopForge is invoked as a sub-agent.
+ * It wraps the Engine, routes by mode, and always prepends a compact health line.
+ *
+ * Three modes (v1.0):
+ *     loop_compile — Per-iteration prompt compiler (primary entry point)
+ *     feedback     — Record execution results → quality scoring → vault persistence
+ *     review       — Audit prompt quality (structural checks + constraint compliance)
+ *
+ * build is an internal path (loop_compile L2 delegation) — not an exposed mode.
+ */
+import { type LoopForgeRequest } from "./protocol.js";
+import { LoopForgeEngine } from "./engine.js";
+export declare function handle(requestInput: string | Record<string, unknown> | LoopForgeRequest, engine?: LoopForgeEngine): string;
+export declare function main(): void;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAKL,KAAK,gBAAgB,EACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,eAAe,EAGhB,MAAM,aAAa,CAAC;AAiBrB,wBAAgB,MAAM,CACpB,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,gBAAgB,EACjE,MAAM,CAAC,EAAE,eAAe,GACvB,MAAM,CAwER;AAsJD,wBAAgB,IAAI,IAAI,IAAI,CA8B3B"}

package/dist/adapter.js

@@ -0,0 +1,228 @@
+/** LoopForge-loop_compile — Sub-agent adapter (unified entry point).
+ *
+ * This is the single entry point when LoopForge is invoked as a sub-agent.
+ * It wraps the Engine, routes by mode, and always prepends a compact health line.
+ *
+ * Three modes (v1.0):
+ *     loop_compile — Per-iteration prompt compiler (primary entry point)
+ *     feedback     — Record execution results → quality scoring → vault persistence
+ *     review       — Audit prompt quality (structural checks + constraint compliance)
+ *
+ * build is an internal path (loop_compile L2 delegation) — not an exposed mode.
+ */
+import { AgentStatus, makeVaultConfig, Mode, } from "./protocol.js";
+import { createEngine, } from "./engine.js";
+// ═══════════════════════════════════════════════════════════════════════════
+// Mode mapping
+// ═══════════════════════════════════════════════════════════════════════════
+const MODE_MAP = {
+    loop_compile: Mode.LOOP_COMPILE,
+    feedback: Mode.FEEDBACK,
+    review: Mode.REVIEW,
+    build: Mode.BUILD,
+};
+// ═══════════════════════════════════════════════════════════════════════════
+// Main entry point
+// ═══════════════════════════════════════════════════════════════════════════
+export function handle(requestInput, engine) {
+    // Parse request
+    let rawMode;
+    let rawData = null;
+    let request;
+    if (typeof requestInput === "string") {
+        rawData = JSON.parse(requestInput);
+        rawMode = rawData.mode ?? "build";
+    }
+    else if (isLoopForgeRequest(requestInput)) {
+        rawMode =
+            typeof requestInput.mode === "string"
+                ? requestInput.mode
+                : requestInput.mode;
+        request = requestInput;
+        rawData = null;
+    }
+    else {
+        rawData = requestInput;
+        rawMode = rawData.mode ?? "build";
+    }
+    if (rawData !== null) {
+        request = parseRequest(rawData);
+    }
+    else {
+        request = requestInput;
+    }
+    // Normalise mode for engine
+    const engineMode = MODE_MAP[rawMode];
+    if (!engineMode) {
+        return JSON.stringify({
+            health: "[PC: 0 records, normal]",
+            status: "error",
+            result: { mode: rawMode, error: `Unknown mode: ${rawMode}` },
+        }, null, 2);
+    }
+    if (rawData !== null) {
+        request.mode = engineMode;
+    }
+    // Inline input validation
+    const task = request.task || "";
+    if (!task.trim()) {
+        return JSON.stringify({
+            health: "[PC: 0 records, normal]",
+            status: "error",
+            result: { mode: rawMode, error: "Task is required." },
+        }, null, 2);
+    }
+    // Initialise engine
+    if (!engine) {
+        const skillsDir = request.vault_config?.skills_dir ?? "skills";
+        engine = createEngine(skillsDir);
+    }
+    // Execute via dedicated engine method
+    const result = routeToEngine(engine, request);
+    // Build compact health line
+    const healthLine = compactHealth(engine);
+    // Build and return response
+    return buildAgentResponse(result, healthLine, rawMode);
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Helpers
+// ═══════════════════════════════════════════════════════════════════════════
+function routeToEngine(engine, request) {
+    const mode = request.mode;
+    if (mode === Mode.LOOP_COMPILE) {
+        return engine.invokeLoopCompile(request);
+    }
+    if (mode === Mode.FEEDBACK) {
+        return engine.invokeFeedback(request);
+    }
+    if (mode === Mode.REVIEW) {
+        return engine.handleReview(request);
+    }
+    if (mode === Mode.BUILD) {
+        return engine.invokeBuild(request);
+    }
+    return {
+        status: AgentStatus.ERROR,
+        response: null,
+    };
+}
+function isLoopForgeRequest(obj) {
+    return (typeof obj === "object" &&
+        obj !== null &&
+        "mode" in obj &&
+        typeof obj.mode === "string" &&
+        [Mode.LOOP_COMPILE, Mode.FEEDBACK, Mode.REVIEW, Mode.BUILD].includes(obj.mode));
+}
+function parseRequest(raw) {
+    // Normalise mode
+    const modeStr = raw.mode ?? "build";
+    const validModes = new Set(Object.values(Mode));
+    const mode = validModes.has(modeStr)
+        ? modeStr
+        : Mode.BUILD;
+    // Known LoopForgeRequest fields
+    const knownFields = new Set([
+        "task", "mode", "vault_config", "feedback", "skill_name", "task_id",
+    ]);
+    const base = {};
+    const extras = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (knownFields.has(key)) {
+            base[key] = value;
+        }
+        else {
+            extras[key] = value;
+        }
+    }
+    const req = {
+        task: base.task ?? "",
+        mode: mode,
+        vault_config: makeVaultConfig(base.vault_config),
+        feedback: base.feedback ?? null,
+        skill_name: base.skill_name ?? null,
+        task_id: base.task_id ?? null,
+    };
+    // Attach extras
+    Object.assign(req, extras);
+    return req;
+}
+function compactHealth(engine) {
+    const recordCount = engine.state?.quality_trend.length ?? 0;
+    const stalled = engine.state ? engine.shouldBreak() : false;
+    const status = stalled ? "STALLED" : "normal";
+    const parts = [`PC: ${recordCount} records`, status];
+    const m = engine._metrics ??
+        engine.metrics;
+    if (m) {
+        if (m.vaultWriteErrors)
+            parts.push(`write_err=${m.vaultWriteErrors}`);
+        if (m.vaultWriteTimeouts)
+            parts.push(`write_timeout=${m.vaultWriteTimeouts}`);
+        if (m.hydrateCacheMisses)
+            parts.push(`cache_miss=${m.hydrateCacheMisses}`);
+    }
+    return "[" + parts.join(", ") + "]";
+}
+function buildAgentResponse(result, healthLine, mode) {
+    let promptOrOverlay = null;
+    let analysis = null;
+    let techniqueUsed = null;
+    if (result.response) {
+        const r = result.response;
+        promptOrOverlay = r.prompt;
+        if (r.analysis) {
+            analysis = r.analysis;
+            techniqueUsed = r.analysis.technique;
+        }
+    }
+    // Inline output size guard
+    let promptText = promptOrOverlay || "";
+    if (promptText.length > 32_000) {
+        promptText = promptText.slice(0, 32_000) + "\n\n[truncated — exceeds 32KB]";
+    }
+    const payload = {
+        mode: mode || "unknown",
+        prompt_or_overlay: promptText,
+        analysis,
+        technique_used: techniqueUsed,
+        confidence: 0.0,
+        proactive_signals: [],
+    };
+    const output = {
+        health: healthLine,
+        status: result.status,
+        result: payload,
+    };
+    return JSON.stringify(output, null, 2);
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// CLI entry point
+// ═══════════════════════════════════════════════════════════════════════════
+export function main() {
+    const chunks = [];
+    process.stdin.on("data", (chunk) => chunks.push(chunk));
+    process.stdin.on("end", () => {
+        const raw = Buffer.concat(chunks).toString("utf-8");
+        if (!raw.trim()) {
+            process.stdout.write(JSON.stringify({ status: "error", error: "No input provided." }) + "\n");
+            process.exit(1);
+        }
+        try {
+            const output = handle(raw);
+            process.stdout.write(output + "\n");
+        }
+        catch (exc) {
+            process.stdout.write(JSON.stringify({
+                health: "[PC: 0 records, normal]",
+                status: "error",
+                result: { error: String(exc) },
+            }, null, 2) + "\n");
+            process.exit(1);
+        }
+    });
+}
+// Allow direct execution
+if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/\\/g, "/"))) {
+    main();
+}
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

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

package/dist/backends/fs.d.ts

@@ -0,0 +1,31 @@
+/** FSBackend — filesystem implementation of VaultBackend.
+ *
+ * Wraps Node.js fs for JSON vault read/write and Markdown lineage I/O.
+ * All file I/O is contained in this single module — engine.ts never
+ * touches the filesystem directly.
+ */
+import type { VaultBackend, VaultEntry } from "./interface.js";
+export declare function readLineageMd(loopId: string, roundNum: number, vaultPath?: string): {
+    full_prompt: string;
+    metadata: Record<string, unknown>;
+} | null;
+export declare function writeLineageMd(loopId: string, roundNum: number, content: string, metadata: Record<string, unknown>, vaultPath?: string): string | null;
+export declare function scanLineageMd(loopId: string, vaultPath?: string): VaultEntry[];
+export declare class FSBackend implements VaultBackend {
+    private readonly vaultPath;
+    private readonly globalVaultPath;
+    constructor(vaultPath?: string, globalVaultPath?: string);
+    readVault(): Record<string, unknown>;
+    writeVault(data: Record<string, unknown>): void;
+    queryEntries(opts?: {
+        prefix?: string;
+        taskIdPattern?: string;
+        feedbackOnly?: boolean;
+    }): VaultEntry[];
+    appendEntry(entry: VaultEntry): void;
+    appendEntries(entries: VaultEntry[]): number;
+    writeLineageMd(loopId: string, roundNum: number, content: string, metadata: Record<string, unknown>): string | null;
+    readLineageMd(loopId: string, roundNum: number): string | null;
+    scanLineageMd(loopId: string): VaultEntry[];
+}
+//# sourceMappingURL=fs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../src/backends/fs.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAsJ/D,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,GACjB;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG,IAAI,CAkBnE;AAED,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CAef;AAED,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,GACjB,UAAU,EAAE,CAqDd;AAMD,qBAAa,SAAU,YAAW,YAAY;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;gBAGvC,SAAS,SAAmC,EAC5C,eAAe,SAAqC;IAQtD,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAUpC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAQ/C,YAAY,CAAC,IAAI,CAAC,EAAE;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,YAAY,CAAC,EAAE,OAAO,CAAC;KACxB,GAAG,UAAU,EAAE;IA+BhB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAQpC,aAAa,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM;IAW5C,cAAc,CACZ,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,MAAM,GAAG,IAAI;IAIhB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAK9D,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,EAAE;CAG5C"}