Skip to content

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

9.2 KB
Raw Blame
// biome-ignore-all format: long agent-facing instruction strings are intentionally stable.
import { codexGoalMode, expectedCodexObjective, isEssentialCriterion, isFinalRunCompletionCandidate, } from "./goal-status.js";
import { resolveToolkitSurface, reviewerRolesFor } from "./surface.js";
export function buildCodexGoalInstruction(args) {
    const mode = codexGoalMode(args.plan);
    const createGoal = buildCreateGoalPayload(args.plan, args.goal);
    const isFinal = args.isFinal ?? isFinalRunCompletionCandidate(args.plan, args.goal);
    const surface = args.surface ?? resolveToolkitSurface();
    return { text: buildText(mode, args.plan, args.goal, createGoal, isFinal, surface), json: createGoal };
}
function buildCreateGoalPayload(plan, goal) {
    return { objective: expectedCodexObjective(plan, goal) };
}
function buildText(mode, plan, goal, createGoal, isFinal, surface) {
    return joinLines([
        mode === "aggregate" ? "UlwLoop aggregate-goal handoff" : "UlwLoop active-goal handoff",
        `Mode: ${mode}`,
        `Plan: ${plan.goalsPath}`,
        `Ledger: ${plan.ledgerPath}`,
        `Goal: ${goal.id} - ${goal.title}`,
        "",
        ...activeGoalLines(goal),
        "",
        ...successCriteriaLines(goal.successCriteria),
        "",
        "Codex goal integration constraints:",
        "- Use the create_goal payload exactly as rendered: objective only.",
        "- Goals are unlimited. Do not add numeric limits.",
        ...modeConstraintLines(mode, isFinal),
        ...evidenceLayoutLines(plan),
        finalSection(plan, goal, isFinal, mode === "aggregate", surface),
        ...checkpointLines(plan, mode),
        "",
        "create_goal payload:",
        JSON.stringify(createGoal, null, 2),
    ]);
}
function modeConstraintLines(mode, isFinal) {
    if (mode === "per_story") {
        return [
            "- First call get_goal. If no active goal exists, call create_goal with the payload below.",
            "- If a different active Codex goal exists, finish/checkpoint that goal before starting this ulw-loop.",
            "- Work only this goal until its completion audit passes.",
        ];
    }
    return [
        "- Codex goal = the whole omo-agent-toolkit ulw-loop run; OMO G001/G002/etc. = ledger stories.",
        "- First call get_goal. If no active goal exists, call create_goal with the aggregate payload below.",
        "- If get_goal reports the same aggregate objective as active, continue this OMO story without creating a new Codex goal.",
        "- If a different active or incomplete Codex goal exists, finish/checkpoint that goal before starting this ulw-loop.",
        isFinal
            ? "- This is the final story; update_goal is allowed only after the mandatory quality gate passes."
            : "- This is not the final story: do not call update_goal mid-aggregate; checkpoint this OMO ledger story and continue the remaining stories. update_goal is reserved for the final story after the mandatory quality gate passes.",
    ];
}
function checkpointLines(plan, mode) {
    const failureLine = `- If blocked or failed, checkpoint with --status failed and the failure evidence; rerun complete-goals${sessionOption(plan)} --retry-failed to resume.`;
    if (mode === "per_story")
        return [failureLine];
    return [
        "- Checkpoint this OMO story with a fresh get_goal snapshot whose objective matches the aggregate payload.",
        failureLine,
    ];
}
function activeGoalLines(goal) {
    return ["Active goal:", `- id: ${goal.id}`, `- title: ${goal.title}`, `- objective: ${goal.objective}`];
}
function successCriteriaLines(criteria) {
    if (criteria.length === 0)
        return ["Success criteria:", "- No success criteria recorded for this goal."];
    return ["Success criteria:", ...criteria.map(formatCriterionLine)];
}
function formatCriterionLine(criterion) {
    const remainingWork = criterion.status === "pending" ? " remaining work:" : "";
    const marker = isEssentialCriterion(criterion) ? "essential" : "non-essential";
    return `-${remainingWork} [${criterion.id}] [${marker}] (${criterion.userModel}) ${criterion.scenario} - expect: ${criterion.expectedEvidence} - status: ${criterion.status}`;
}
function evidenceLayoutLines(plan) {
    if (plan.evidenceLayoutVersion !== 2)
        return [];
    return [
        "- Evidence layout v2: write every artifact for the active goal (QA matrix, review reports, receipts) under the current attempt directory. Read currentAttemptDir from `omo-agent-toolkit ulw-loop status --json` (.omo/evidence/ulw/<session>/<goalId>/a<attempt>). The final checkpoint rejects quality-gate artifacts outside that directory.",
    ];
}
function finalSection(plan, goal, isFinal, aggregate, surface) {
    const roles = reviewerRolesFor(surface);
    if (!isFinal)
        return "- This is not the final ulw-loop story; do not run the final reviewer/manual-QA/gate-review quality gate yet.";
    const option = sessionOption(plan);
    if (surface === "omo-senpi")
        return senpiFinalSection(plan, goal, aggregate);
    const blockerCommand = `omo-agent-toolkit ulw-loop record-review-blockers${option} --goal-id ${goal.id} --title "Resolve final code-review blockers" --objective "<blocker-resolution objective>" --evidence "<review findings>" --codex-goal-json "<active get_goal JSON or path>"`;
    const checkpointCommand = `omo-agent-toolkit ulw-loop checkpoint${option} --goal-id ${goal.id} --status complete --evidence "<targeted verification/manualQa/gateReview evidence>" --codex-goal-json "<fresh complete get_goal JSON or path>" --quality-gate-json "<quality gate JSON or path>"`;
    return joinLines([
        "Final story: self-review and manual QA are the default; use the quality gate before update_goal:",
        "- Run targeted verification for changed behavior.",
        "- Confirm every manualQa artifact path exists and has non-zero size.",
        `- Run manual QA yourself and write its artifact under currentAttemptDir. Only if the user explicitly demands strict, rigorous, or high-accuracy review, spawn ${roles.gateReview}, optionally also ${roles.codeReview} and ${roles.manualQa}; otherwise set manualQa.by and gateReview.by to "main-session".`,
        "- Require passed manualQa, approved gateReview, passed iteration, and complete criteriaCoverage; include codeReview only when strict review was requested. criteriaCoverage must summarize originalIntent, desiredOutcome, and userOutcomeReview; counts alone are not approval.",
        "- On a reviewer REJECT, fix only the cited blockers, rerun the affected verification/Manual-QA, and re-review the delta at most TWICE; if blockers remain, record them and surface to the user.",
        "- If codeQualityStatus is WATCH, include the WATCH notes verbatim in your final user-facing message.",
        "- If any reviewer is blocked/inconclusive or the quality gate is not clean, do not call update_goal. Record blocker work first:",
        `  ${blockerCommand}`,
        aggregate
            ? '- If the quality gate is clean, call update_goal({status: "complete"}), call get_goal again, then checkpoint the aggregate story:'
            : '- If the quality gate is clean, call update_goal({status: "complete"}), call get_goal again, then checkpoint:',
        `  ${checkpointCommand}`,
    ]);
}
function senpiFinalSection(plan, goal, aggregate) {
    const option = sessionOption(plan);
    const checkpointCommand = `omo-agent-toolkit ulw-loop checkpoint${option} --goal-id ${goal.id} --status complete --evidence "<manualQa/gateReview evidence>" --codex-goal-json "<fresh complete get_goal JSON or path>" --quality-gate-json "$(omo-agent-toolkit ulw-loop checkpoint${option} --print-template)"`;
    return joinLines([
        "Final story: run the single-reviewer quality gate before update_goal:",
        "- Run manual QA yourself and write the non-empty artifact under currentAttemptDir; set manualQa.by to \"main-session\".",
        '- Spawn exactly one gate reviewer with task(category: "deep-high").',
        "- If that task fails with any model_unavailable failure, retry with category:deep-low, then category:unspecified-high, then category:unspecified-low.",
        '- Set gateReview.by to the exact category:<name> literal used for the successful task.',
        '- Build the gate JSON with omo-agent-toolkit ulw-loop checkpoint --print-template, then fill manualQa, gateReview, iteration, and criteriaCoverage.',
        '- Require passed manualQa, approved gateReview, passed iteration, and complete criteriaCoverage before update_goal({status: "complete"}).',
        aggregate
            ? `- If the gate is clean, call update_goal({status: "complete"}), call get_goal again, then checkpoint the aggregate story: ${checkpointCommand}`
            : `- If the gate is clean, call update_goal({status: "complete"}), call get_goal again, then checkpoint: ${checkpointCommand}`,
    ]);
}
function sessionOption(plan) {
    const prefix = ".omo/ulw-loop/";
    const suffix = "/goals.json";
    if (!plan.goalsPath.startsWith(prefix) || !plan.goalsPath.endsWith(suffix))
        return "";
    const sessionId = plan.goalsPath.slice(prefix.length, -suffix.length);
    return sessionId.length === 0 ? "" : ` --session-id ${sessionId}`;
}
function joinLines(lines) {
    return lines.join("\n");
}