Skip to content

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

7.5 KB
Raw Blame
import { readFile } from "node:fs/promises";
import { hasFlag, parseCodexGoalJson, parseRecordEvidenceArgs, positionalText, readStdin, readValue, } from "./cli-arg-parser.js";
import { blockedDecisionHandoff, normalizeCodexGoalMode, printJson, printStatus } from "./cli-output.js";
import { parseSteeringProposals, printSteerBatchResult, printSteerResult } from "./cli-steering.js";
import { buildCodexGoalInstruction } from "./codex-goal-instruction.js";
import { isEssentialCriterion } from "./goal-status.js";
import { summarizeUlwLoopPlan } from "./plan-crud.js";
import { createAgentToolkit } from "./sdk.js";
import { steerUlwLoopBatch } from "./steering-batch.js";
import { resolveToolkitSurface } from "./surface.js";
import { UlwLoopError } from "./types.js";
export async function createGoals(repoRoot, argv, json, scope) {
    const briefFile = readValue(argv, "--brief-file");
    const brief = readValue(argv, "--brief") ??
        (briefFile === undefined ? undefined : await readFile(briefFile, "utf8")) ??
        (hasFlag(argv, "--from-stdin") ? await readStdin() : undefined) ??
        positionalText(argv);
    if (!brief.trim()) {
        throw new UlwLoopError("Missing brief text. Pass --brief, --brief-file, --from-stdin, or positional text.", "ULW_LOOP_BRIEF_REQUIRED");
    }
    const validationBatchesJson = readValue(argv, "--validation-batch-json");
    const plan = unwrap(await toolkitFor(repoRoot, scope).createGoals({
        brief,
        codexGoalMode: normalizeCodexGoalMode(readValue(argv, "--codex-goal-mode")),
        force: hasFlag(argv, "--force"),
        ...(validationBatchesJson === undefined ? {} : { validationBatchesJson }),
    }));
    if (json)
        printJson({ ok: true, plan, summary: summarizeUlwLoopPlan(plan) });
    else {
        process.stdout.write(`ulw-loop plan created: ${plan.goals.length} goal(s)\nbrief: ${plan.briefPath}\ngoals: ${plan.goalsPath}\nledger: ${plan.ledgerPath}\n`);
    }
    return 0;
}
export async function status(repoRoot, json, scope) {
    const status = unwrap(await toolkitFor(repoRoot, scope).status());
    if (json)
        printJson({ ok: true, ...status });
    else
        printStatus(status.plan);
    return 0;
}
export async function completeGoals(repoRoot, argv, json, scope) {
    const result = unwrap(await toolkitFor(repoRoot, scope).completeGoals({ retryFailed: hasFlag(argv, "--retry-failed") }));
    if ("done" in result) {
        const handoff = blockedDecisionHandoff(result.plan);
        if (json) {
            printJson({
                ok: true,
                done: true,
                blocked: handoff.length > 0,
                handoff,
                summary: summarizeUlwLoopPlan(result.plan),
                plan: result.plan,
            });
        }
        else
            process.stdout.write(`${handoff || "ulw-loop: all goals complete"}\n`);
        return 0;
    }
    const instruction = buildCodexGoalInstruction({ plan: result.plan, goal: result.goal });
    if (json)
        printJson({ ok: true, resumed: result.resumed, goal: result.goal, instruction, plan: result.plan });
    else
        process.stdout.write(`${instruction.text}\n`);
    return 0;
}
export async function steer(repoRoot, argv, json, scope) {
    const proposals = await parseSteeringProposals(argv);
    const single = proposals[0];
    if (single !== undefined && proposals.length === 1 && readValue(argv, "--proposals-json") === undefined) {
        const result = unwrap(await toolkitFor(repoRoot, scope).steer(single));
        printSteerResult(result, json);
        return result.accepted ? 0 : 1;
    }
    const result = await steerUlwLoopBatch(repoRoot, proposals, scope);
    printSteerBatchResult(result, json);
    return result.accepted ? 0 : 1;
}
export async function addGoal(repoRoot, argv, json, scope) {
    const result = unwrap(await toolkitFor(repoRoot, scope).addGoal({
        title: required(argv, "--title"),
        objective: required(argv, "--objective"),
    }));
    if (json)
        printJson({ ok: true, plan: result.plan, goal: result.goal, summary: summarizeUlwLoopPlan(result.plan) });
    else {
        process.stdout.write(`ulw-loop added goal: ${result.goal.id}\n`);
        printStatus(result.plan);
    }
    return 0;
}
export async function criteria(repoRoot, argv, json, scope) {
    const goalId = required(argv, "--goal-id");
    const result = unwrap(await toolkitFor(repoRoot, scope).criteria({ goalId }));
    if (json)
        printJson({ ok: true, goalId: result.goalId, criteria: result.criteria });
    else {
        process.stdout.write(`criteria for ${result.goalId}:\n${result.criteria.map(formatCriterionForCli).join("\n")}\n`);
    }
    return 0;
}
export async function captureEvidence(repoRoot, argv, json, scope) {
    const result = unwrap(await toolkitFor(repoRoot, scope).recordEvidence(parseRecordEvidenceArgs(argv)));
    if (json)
        printJson({ ok: true, ...result, summary: summarizeUlwLoopPlan(result.plan) });
    else {
        process.stdout.write(`ulw-loop evidence recorded: ${result.goal.id}/${result.criterion.id} -> ${result.criterion.status}\n`);
    }
    return 0;
}
export async function reviewBlockers(repoRoot, argv, json, scope) {
    const codexGoalJson = await parseCodexGoalJson(required(argv, "--codex-goal-json"));
    if (codexGoalJson === undefined) {
        throw new UlwLoopError("Missing --codex-goal-json.", "ULW_LOOP_CODEX_GOAL_JSON_REQUIRED");
    }
    const result = unwrap(await toolkitFor(repoRoot, scope).recordReviewBlockers({
        goalId: required(argv, "--goal-id"),
        title: required(argv, "--title"),
        objective: required(argv, "--objective"),
        evidence: required(argv, "--evidence"),
        codexGoalJson,
    }));
    if (json) {
        printJson({
            ok: true,
            plan: result.plan,
            blockedGoal: result.blockedGoal,
            goal: result.newGoal,
            ledgerEntries: result.ledgerEntries,
            nextActions: result.nextActions,
            warnings: result.warnings,
            summary: summarizeUlwLoopPlan(result.plan),
        });
    }
    else {
        process.stdout.write(`ulw-loop final review blockers recorded: ${result.blockedGoal.id} -> review_blocked; added ${result.newGoal.id}\n`);
    }
    return 0;
}
// Every subcommand runs through the SDK so state logic lives in one place; the CLI keeps only argv
// parsing and the legacy output shapes. A failed envelope is rethrown as the typed error the CLI's
// JSON error path already prints.
function toolkitFor(repoRoot, scope) {
    const sessionId = scope?.sessionId?.trim();
    if (sessionId === undefined || sessionId.length === 0) {
        throw new UlwLoopError("Missing --session-id.", "ULW_LOOP_SESSION_ID_REQUIRED", {
            details: { flag: "--session-id" },
        });
    }
    return createAgentToolkit({ cwd: repoRoot, sessionId, surface: resolveToolkitSurface() });
}
function unwrap(response) {
    if (response.ok)
        return response.result;
    throw new UlwLoopError(response.error.message, response.error.code);
}
function formatCriterionForCli(criterion) {
    const marker = isEssentialCriterion(criterion) ? "essential" : "non-essential";
    return `- ${criterion.id} [${criterion.status}] [${marker}] (${criterion.userModel}) ${criterion.scenario} evidence: ${criterion.capturedEvidence ?? "pending"}`;
}
function required(argv, flag) {
    const value = readValue(argv, flag)?.trim();
    if (value)
        return value;
    throw new UlwLoopError(`Missing ${flag}.`, "ULW_LOOP_ARGUMENT_MISSING", { details: { flag } });
}