The one and only agent harness for complex codebases. Project memory, planning, execution, and verified completion inside Codex.
JavaScript aiai-agentsclaudeclaude-codeclicodexdeveloper-toolslazylazycodexoh-my-openagentomoopenaiorchestrationtypescript
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;
}