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
// biome-ignore-all format: compact steering module must stay below the 240 pure-LOC budget
import { isUlwLoopDone } from "./goal-status.js";
import { commit } from "./plan-commit.js";
import { findAcceptedSteeringLedgerEntry, readUlwLoopPlan, withUlwLoopMutationLock } from "./plan-io.js";
import { makeGoal, reviseCriterion, reviseWording, splitOrBlock } from "./steering-mutations.js";
import { buildSteeringPlanSnapshot, changedGoalIdsBetween } from "./steering-snapshot.js";
import { iso, ULW_LOOP_STEERING_MUTATION_KINDS, ULW_LOOP_SUCCESS_CRITERION_USER_MODELS } from "./types.js";
import { batchUpdateLedgerEntry } from "./validation-batch.js";
const SOURCES = ["user_prompt_submit", "finding", "cli"];
const PROTECTED = new Set(["aggregateCompletion", "codexObjective", "codexObjectiveAliases", "acknowledgedDriverObjectives", "originalConstraints", "qualityGate", "status", "completedAt", "completionStatus"]);
const isObject = (value) => typeof value === "object" && value !== null;
const isPlain = (value) => isObject(value) && !Array.isArray(value);
const read = (value, key) => Object.entries(value).find(([name]) => name === key)?.[1];
const isText = (value) => typeof value === "string" && value.trim().length > 0;
const text = (value, key) => {
const candidate = read(value, key);
return isText(candidate) ? candidate.trim() : undefined;
};
const isKind = (value) => typeof value === "string" && ULW_LOOP_STEERING_MUTATION_KINDS.some((kind) => kind === value);
const isSource = (value) => typeof value === "string" && SOURCES.some((source) => source === value);
const isModel = (value) => typeof value === "string" && ULW_LOOP_SUCCESS_CRITERION_USER_MODELS.some((model) => model === value);
const texts = (value, key) => {
const candidate = read(value, key);
return Array.isArray(candidate) && candidate.every((item) => typeof item === "string") ? candidate : [];
};
function targets(proposal) {
const many = texts(proposal, "targetGoalIds");
const one = text(proposal, "targetGoalId") ?? text(proposal, "goalId");
return many.length > 0 ? many : one === undefined ? [] : [one];
}
const after = (proposal) => {
const candidate = read(proposal, "after");
return isPlain(candidate) ? candidate : undefined;
};
const revised = (proposal, direct, nested) => text(proposal, direct) ?? text(after(proposal) ?? proposal, nested);
function child(value) {
if (!isPlain(value))
return null;
const title = text(value, "title");
const objective = text(value, "objective");
if (title === undefined || objective === undefined)
return null;
return { title, objective };
}
function childValues(proposal) {
const direct = read(proposal, "childGoals");
if (Array.isArray(direct) && direct.length > 0)
return direct;
const nested = after(proposal);
const fromAfter = nested === undefined ? undefined : read(nested, "children");
return Array.isArray(fromAfter) ? fromAfter : [];
}
const pendingOrder = (proposal) => {
const direct = texts(proposal, "pendingOrder");
return direct.length > 0 ? direct : texts(after(proposal) ?? proposal, "pendingGoalIds");
};
function hasProtected(value) {
if (!isObject(value))
return false;
for (const [key, childValue] of Object.entries(value))
if (PROTECTED.has(key) || key.toLowerCase().includes("complete") || hasProtected(childValue))
return true;
return false;
}
function allText(value) {
if (typeof value === "string")
return value;
return isObject(value) ? Object.values(value).map(allText).filter(Boolean).join("\n") : "";
}
function weakens(value) {
const valueText = allText(value).toLowerCase();
return /\b(skip|bypass|weaken|remove|omit|auto[-\s]?complete|mark complete|complete faster)\b/.test(valueText) && /\b(test|tests|verification|review|quality gate|complete|completion)\b/.test(valueText);
}
function auditFor(proposal, reasons) {
const object = isPlain(proposal) ? proposal : undefined;
const kindRaw = object === undefined ? undefined : read(object, "kind");
const sourceRaw = object === undefined ? undefined : read(object, "source");
const evidence = object === undefined ? "" : (text(object, "evidence") ?? "");
const rationale = object === undefined ? "" : (text(object, "rationale") ?? "");
const audit = { kind: isKind(kindRaw) ? kindRaw : "annotate_ledger", source: isSource(sourceRaw) ? sourceRaw : "cli", targetGoalIds: object === undefined ? [] : targets(object), evidence, rationale, invariant: { accepted: reasons.length === 0, structuralInvariantAccepted: reasons.length === 0, evidenceBackedNecessity: evidence.length > 0 && rationale.length > 0, noEasierCompletion: !weakens(proposal), rejectedReasons: reasons, reasons } };
if (object === undefined)
return audit;
const criterionId = text(object, "criterionId");
const directiveText = text(object, "directiveText");
const promptSignature = text(object, "promptSignature");
const idempotencyKey = text(object, "idempotencyKey");
if (criterionId !== undefined)
audit.criterionId = criterionId;
if (directiveText !== undefined)
audit.directiveText = directiveText;
if (promptSignature !== undefined)
audit.promptSignature = promptSignature;
if (idempotencyKey !== undefined)
audit.idempotencyKey = idempotencyKey;
return audit;
}
export function validateUlwLoopSteeringProposal(plan, proposal) {
const reasons = [];
if (!isPlain(proposal))
reasons.push("proposal must be an object");
const object = isPlain(proposal) ? proposal : {};
const kind = read(object, "kind");
if (!isKind(kind))
reasons.push(`invalid kind: ${String(kind)}`);
if (!isSource(read(object, "source")))
reasons.push(`invalid source: ${String(read(object, "source"))}`);
if (text(object, "evidence") === undefined)
reasons.push("missing evidence");
if (text(object, "rationale") === undefined)
reasons.push("missing rationale");
if (hasProtected(proposal))
reasons.push("protected payload");
if (weakens(proposal))
reasons.push("weakened completion");
if (isUlwLoopDone(plan))
reasons.push("plan already complete");
if (isKind(kind))
validateKind(plan, object, kind, reasons);
return auditFor(proposal, reasons);
}
function goal(plan, id) {
return id === undefined ? undefined : plan.goals.find((item) => item.id === id);
}
function validateKind(plan, proposal, kind, reasons) {
const target = goal(plan, targets(proposal)[0]);
if (kind === "add_subgoal" && (text(proposal, "title") === undefined || text(proposal, "objective") === undefined))
reasons.push("add_subgoal requires title/objective");
if ((kind === "split_subgoal" || kind === "revise_pending_wording" || kind === "mark_blocked_superseded") && target === undefined)
reasons.push(`${kind} requires target`);
if ((kind === "split_subgoal" || kind === "revise_pending_wording") && target !== undefined && target.status !== "pending")
reasons.push(`${kind} requires pending target`);
const rawChildren = childValues(proposal);
if (kind === "split_subgoal" && rawChildren.length === 0)
reasons.push("split_subgoal requires children");
if ((kind === "split_subgoal" || kind === "mark_blocked_superseded") && rawChildren.some((item) => child(item) === null))
reasons.push(`${kind} children require title/objective`);
if (kind === "reorder_pending")
validateOrder(plan, proposal, reasons);
if (kind === "revise_pending_wording" && revised(proposal, "revisedTitle", "title") === undefined && revised(proposal, "revisedObjective", "objective") === undefined)
reasons.push("revise_pending_wording requires update");
if (kind === "revise_criterion")
validateCriterion(plan, proposal, reasons);
}
function validateOrder(plan, proposal, reasons) {
const requested = pendingOrder(proposal);
const pending = plan.goals.filter((item) => item.status === "pending" && item.steeringStatus === undefined).map((item) => item.id);
if (requested.length === 0)
reasons.push("reorder_pending requires ids");
if (new Set(requested).size !== requested.length)
reasons.push("duplicate pending id");
if (requested.some((id) => !pending.includes(id)))
reasons.push("unknown pending id");
}
function validateCriterion(plan, proposal, reasons) {
const target = goal(plan, targets(proposal)[0]);
const criterionId = text(proposal, "criterionId");
if (target === undefined)
reasons.push("revise_criterion requires goalId");
else if (criterionId === undefined || target.successCriteria.every((item) => item.id !== criterionId))
reasons.push("revise_criterion requires criterionId");
const model = read(proposal, "userModel");
if (read(proposal, "scenario") === undefined && read(proposal, "expectedEvidence") === undefined && model === undefined)
reasons.push("revise_criterion requires update");
if (model !== undefined && !isModel(model))
reasons.push("invalid userModel");
}
export function applySteeringMutation(plan, proposal, audit, surface = "lazycodex") {
const next = structuredClone(plan);
if (!audit.invariant.accepted)
return next;
const now = proposal.now?.toISOString() ?? iso();
if (proposal.kind === "add_subgoal")
next.goals.push(makeGoal(next, { title: proposal.title ?? "", objective: proposal.objective ?? "" }, proposal.evidence, now, 1, surface));
if (proposal.kind === "reorder_pending") {
const order = pendingOrder(proposal);
next.goals = [...order.map((id) => goal(next, id)).filter((item) => item !== undefined), ...next.goals.filter((item) => !order.includes(item.id))];
}
if (proposal.kind === "revise_pending_wording")
reviseWording(next, proposal, now);
if (proposal.kind === "split_subgoal" || proposal.kind === "mark_blocked_superseded")
splitOrBlock(next, proposal, now, surface);
if (proposal.kind === "revise_criterion")
reviseCriterion(next, proposal, now);
if (proposal.kind !== "annotate_ledger")
next.updatedAt = now;
return next;
}
function isProposal(value) {
return isPlain(value) && isKind(read(value, "kind")) && isSource(read(value, "source")) && isText(read(value, "evidence")) && isText(read(value, "rationale"));
}
export function parseUlwLoopSteeringDirective(text) {
const match = /(?:^|\s)(?:OMO_ULW_LOOP_STEER|omo\.ulw-loop\.steer|omo ulw-loop steer|omo-agent-toolkit ulw-loop steer):\s*([\s\S]+)$/u.exec(text);
if (match?.[1] === undefined)
return null;
try {
const parsed = JSON.parse(match[1].trim());
return isProposal(parsed) ? parsed : null;
}
catch (error) {
if (error instanceof SyntaxError)
return null;
throw error;
}
}
export async function steerUlwLoop(repoRoot, proposal, scope, surface = "lazycodex") {
return withUlwLoopMutationLock(repoRoot, scope, async () => {
const plan = await readUlwLoopPlan(repoRoot, scope);
const key = proposal.idempotencyKey ?? proposal.promptSignature;
const prior = key === undefined ? undefined : await findAcceptedSteeringLedgerEntry(repoRoot, key, scope);
if (prior?.steering !== undefined) {
// Legacy entries embedded full-plan before/after snapshots; never
// re-surface those multi-MB payloads on the dedup path.
const { before: _before, after: _after, ...compactPrior } = prior.steering;
return { plan, accepted: true, audit: { ...compactPrior, deduped: true }, rejectedReasons: [], deduped: true };
}
const audit = validateUlwLoopSteeringProposal(plan, proposal);
const accepted = audit.invariant.accepted;
const next = accepted ? applySteeringMutation(plan, proposal, audit, surface) : plan;
const finalAudit = { ...audit };
if (accepted) {
const changed = changedGoalIdsBetween(plan, next);
finalAudit.before = buildSteeringPlanSnapshot(plan, changed);
finalAudit.after = buildSteeringPlanSnapshot(next, changed);
}
const at = proposal.now?.toISOString() ?? iso();
const batchEntry = accepted ? batchUpdateLedgerEntry(plan, next, at) : null;
const entries = [ledgerEntry(proposal, finalAudit, at)];
if (batchEntry !== null)
entries.push(batchEntry);
await commit(repoRoot, scope, { plan: next, entries });
return { plan: next, accepted, audit: finalAudit, rejectedReasons: audit.invariant.rejectedReasons, deduped: false };
});
}
function ledgerEntry(proposal, audit, at) {
const entry = { at, kind: audit.invariant.accepted ? (proposal.kind === "revise_criterion" ? "criteria_revised" : "steering_accepted") : "steering_rejected", evidence: proposal.evidence, message: proposal.rationale, steering: audit, mutationKind: proposal.kind };
const goalId = audit.targetGoalIds[0];
if (goalId !== undefined)
entry.goalId = goalId;
if (proposal.criterionId !== undefined)
entry.criterionId = proposal.criterionId;
if (proposal.idempotencyKey !== undefined)
entry.idempotencyKey = proposal.idempotencyKey;
return entry;
}