Skip to content

The one and only agent harness for complex codebases. Project memory, planning, execution, and verified completion inside Codex.

4.7 KB
Raw Blame
import { existsSync, readdirSync, readFileSync } from "node:fs";
import { join } from "node:path";
import { ulwLoopDir } from "./paths.js";
import { UlwLoopError } from "./types.js";
export function hasCode(error, code) {
    return error instanceof Error && "code" in error && error.code === code;
}
export function readOptional(path) {
    try {
        return readFileSync(path, "utf8");
    }
    catch (error) {
        if (hasCode(error, "ENOENT"))
            return undefined;
        throw error;
    }
}
export function logNames(dir) {
    try {
        return readdirSync(join(dir, "revisions"))
            .filter((name) => /^\d{8,}\.json$/.test(name))
            .sort();
    }
    catch (error) {
        if (hasCode(error, "ENOENT"))
            return [];
        throw error;
    }
}
function readRecord(dir, name) {
    try {
        const record = JSON.parse(readFileSync(join(dir, "revisions", name), "utf8"));
        return record.version === 1 &&
            Number.isInteger(record.revision) &&
            record.plan?.version === 1 &&
            Array.isArray(record.plan.goals) &&
            Array.isArray(record.ledger)
            ? record
            : undefined;
    }
    catch (error) {
        if (!(error instanceof SyntaxError))
            throw error;
        return undefined;
    }
}
// Only the audit trail needs every record; plan reads use readNewestRecord.
export function readRecords(dir) {
    const records = [];
    for (const name of logNames(dir)) {
        const record = readRecord(dir, name);
        if (record !== undefined)
            records.push(record);
    }
    return records.sort((a, b) => a.revision - b.revision);
}
// Every ulw-loop status probe reads the plan, each record embeds a full plan copy, and records are never
// deleted - so a plan read parses the newest record only, newest first, and stops there. Names are ordered
// by their parsed revision because a wider zero-padding would break lexicographic order.
export function readNewestRecord(dir) {
    const names = logNames(dir).sort((a, b) => Number.parseInt(b, 10) - Number.parseInt(a, 10));
    for (const name of names) {
        const record = readRecord(dir, name);
        if (record !== undefined)
            return record;
    }
    return undefined;
}
export function reconcilePlan(dir) {
    const raw = readOptional(join(dir, "goals.json"));
    let cached;
    if (raw !== undefined) {
        try {
            cached = JSON.parse(raw);
        }
        catch (error) {
            if (!(error instanceof SyntaxError))
                throw error;
        }
    }
    const latest = readNewestRecord(dir);
    if (latest === undefined)
        return cached;
    if (cached === undefined)
        return latest.plan;
    if ((cached.revision ?? 0) > latest.revision)
        return cached;
    // A goals.json written outside the commit log (the removed tool path rewrote it wholesale, never
    // stamping `revision`) can hold goals no snapshot has. Serving the snapshot would drop them, so the
    // cache wins and is stamped with the snapshot's revision: the next publish derives N+1 from it and
    // folds the whole plan into a real record instead of colliding with an existing revision file.
    // A cache that names an OLDER revision is a lagging view of a force-recreate and never wins.
    if (cached.revision === undefined || cached.revision === latest.revision) {
        const published = new Set(latest.plan.goals.map((goal) => goal.id));
        if (Array.isArray(cached.goals) && cached.goals.some((goal) => !published.has(goal.id)))
            return { ...cached, revision: latest.revision };
    }
    return latest.plan;
}
// Goals are never removed from a plan, so every `goal_added` the reconciled ledger still carries must
// have a goal in the projection. A projection that lacks one is truncated and must not become goals.json.
export function assertProjectionComplete(plan, ledger) {
    const present = new Set(plan.goals.map((goal) => goal.id));
    const missing = new Set();
    for (const entry of ledger)
        if (entry.kind === "goal_added" && entry.goalId !== undefined && !present.has(entry.goalId))
            missing.add(entry.goalId);
    if (missing.size === 0)
        return;
    throw new UlwLoopError(`Refusing to rewrite goals.json: the ledger records goals the plan projection lacks (${[...missing].join(", ")}). Restore those goals into the newest revisions/ record (keeping plan.revision equal to its file number) before mutating this run.`, "ULW_LOOP_PROJECTION_TRUNCATED", { details: { missingGoalIds: [...missing] } });
}
export function planExists(repoRoot, scope) {
    const dir = ulwLoopDir(repoRoot, scope);
    return existsSync(join(dir, "goals.json")) || logNames(dir).length > 0;
}