@code-yeongyu/lazycodex 0.1.1

package/packages/omo-codex/plugin/components/ulw-loop/dist/cli-output.js

@@ -0,0 +1,55 @@
+import { UlwLoopError } from "./types.js";
+export const ULW_LOOP_HELP = `Usage:
+  omo ulw-loop create-goals --brief "..." [--brief-file <path>] [--from-stdin] [--codex-goal-mode aggregate|per_story] [--force] [--json]
+  omo ulw-loop status [--json]
+  omo ulw-loop complete-goals [--retry-failed] [--json]
+  omo ulw-loop criteria --goal-id <id> [--json]
+  omo ulw-loop record-evidence --goal-id <id> --criterion-id <id> --status pass|fail|blocked --evidence "..." [--notes "..."] [--json]
+  omo ulw-loop checkpoint --goal-id <id> --status complete|failed|blocked --evidence "..." --codex-goal-json <...> [--quality-gate-json <...>] [--json]
+  omo ulw-loop steer --kind <kind> ... --evidence "..." --rationale "..." [--json]
+  omo ulw-loop add-goal --title "..." --objective "..." [--json]
+  omo ulw-loop record-review-blockers --goal-id <id> --title "..." --objective "..." --evidence "..." --codex-goal-json <...> [--json]
+
+All subcommands accept [--session-id <id>] to isolate state under .omo/ulw-loop/<id>/; without it, Codex session env is used when present.`;
+export function printJson(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+function criteriaCounts(goal) {
+    let pass = 0;
+    for (const criterion of goal.successCriteria)
+        if (criterion.status === "pass")
+            pass += 1;
+    return { pass, total: goal.successCriteria.length };
+}
+export function printStatus(plan) {
+    let totalCriteria = 0;
+    let passCriteria = 0;
+    const lines = ["ulw-loop status", "", "goals:"];
+    for (const goal of plan.goals) {
+        const counts = criteriaCounts(goal);
+        totalCriteria += counts.total;
+        passCriteria += counts.pass;
+        const marker = goal.id === plan.activeGoalId ? "*" : "-";
+        lines.push(`${marker} ${goal.id} [${goal.status}] ${goal.title} (criteria: ${counts.pass}/${counts.total})`);
+    }
+    lines.push("", "summary:", `total goals: ${plan.goals.length}`, `criteria: ${passCriteria}/${totalCriteria} pass`);
+    process.stdout.write(`${lines.join("\n")}\n`);
+}
+export function blockedDecisionHandoff(plan) {
+    const blocked = plan.goals.find((goal) => goal.status === "needs_user_decision" && goal.nonRetriable);
+    if (blocked === undefined)
+        return "";
+    return [
+        "ulw-loop: blocked on repeated external authorization; no retryable failed goals remain.",
+        `Goal: ${blocked.id} - ${blocked.title}`,
+        `Required external decision: ${blocked.requiredExternalDecision ?? "provide the missing authorization or choose a different unblock path"}.`,
+        "Do not run complete-goals --retry-failed again until external state changes or the user authorizes an unblock path.",
+    ].join("\n");
+}
+export function normalizeCodexGoalMode(value) {
+    if (value === undefined)
+        return "aggregate";
+    if (value === "aggregate" || value === "per_story")
+        return value;
+    throw new UlwLoopError("Invalid --codex-goal-mode; expected aggregate or per_story.", "ULW_LOOP_CODEX_GOAL_MODE_INVALID", { details: { value } });
+}

package/packages/omo-codex/plugin/components/ulw-loop/dist/cli-steering.d.ts

@@ -0,0 +1,12 @@
+import type { SteerUlwLoopResult, UlwLoopSteeringMutationKind, UlwLoopSteeringProposal, UlwLoopSteeringSource, UlwLoopSuccessCriterionUserModel } from "./types.js";
+export type CliSteeringProposal = UlwLoopSteeringProposal & {
+    readonly goalId?: string;
+    readonly scenario?: string;
+    readonly expectedEvidence?: string;
+    readonly userModel?: UlwLoopSuccessCriterionUserModel;
+};
+export declare function parseSteeringKind(argv: readonly string[]): UlwLoopSteeringMutationKind;
+export declare function parseSteeringSource(argv: readonly string[]): UlwLoopSteeringSource;
+export declare function parseSteeringProposal(argv: readonly string[]): Promise<CliSteeringProposal>;
+export declare function normalizeSteeringProposal(proposal: CliSteeringProposal): CliSteeringProposal;
+export declare function printSteerResult(result: SteerUlwLoopResult, json: boolean): void;

package/packages/omo-codex/plugin/components/ulw-loop/dist/cli-steering.js

@@ -0,0 +1,145 @@
+// biome-ignore-all format: keep this module under the mandated pure LOC budget.
+import { parseGoalArg, readJsonInput, readValue } from "./cli-arg-parser.js";
+import { printJson, printStatus } from "./cli-output.js";
+import { ULW_LOOP_STEERING_MUTATION_KINDS, ULW_LOOP_SUCCESS_CRITERION_USER_MODELS, UlwLoopError } from "./types.js";
+const SOURCES = ["user_prompt_submit", "finding", "cli"];
+function isKind(value) { return value !== undefined && ULW_LOOP_STEERING_MUTATION_KINDS.some((kind) => kind === value); }
+function isSource(value) { return value !== undefined && SOURCES.some((source) => source === value); }
+function isModel(value) { return ULW_LOOP_SUCCESS_CRITERION_USER_MODELS.some((model) => model === value); }
+function fail(message, code, details) { throw new UlwLoopError(message, code, { details }); }
+function text(value, field) { if (value === undefined)
+    return undefined; const trimmed = value.trim(); if (trimmed.length > 0)
+    return trimmed; return fail(`Empty ${field}.`, "ULW_LOOP_STEERING_FIELD_EMPTY", { field }); }
+function required(argv, flag) { const value = text(readValue(argv, flag), flag); return value ?? fail(`Missing ${flag}.`, "ULW_LOOP_STEERING_FIELD_REQUIRED", { flag }); }
+function requiredGoal(argv) { const value = text(parseGoalArg(argv), "--goal-id"); return value ?? fail("Missing --goal-id.", "ULW_LOOP_GOAL_ID_REQUIRED", { flag: "--goal-id" }); }
+function readObject(value, key) { return Object.entries(value).find(([name]) => name === key)?.[1]; }
+function isPlain(value) { return typeof value === "object" && value !== null && !Array.isArray(value); }
+function objectText(value, key) { const candidate = readObject(value, key); return typeof candidate === "string" ? candidate : undefined; }
+export function parseSteeringKind(argv) {
+    const value = readValue(argv, "--kind");
+    if (isKind(value))
+        return value;
+    return value === undefined ? fail("Missing --kind.", "ULW_LOOP_STEERING_KIND_REQUIRED", { flag: "--kind" }) : fail(`Invalid --kind: ${value}.`, "ULW_LOOP_STEERING_KIND_INVALID", { value, expected: ULW_LOOP_STEERING_MUTATION_KINDS });
+}
+export function parseSteeringSource(argv) {
+    const value = readValue(argv, "--source");
+    if (value === undefined)
+        return "cli";
+    return isSource(value) ? value : fail(`Invalid --source: ${value}.`, "ULW_LOOP_STEERING_SOURCE_INVALID", { value, expected: SOURCES });
+}
+function child(value) {
+    if (!isPlain(value))
+        return null;
+    const title = text(objectText(value, "title"), "title");
+    const objective = text(objectText(value, "objective"), "objective");
+    if (title === undefined || objective === undefined)
+        return null;
+    return { title, objective };
+}
+async function children(argv, flag, needed) {
+    const input = needed ? required(argv, flag) : text(readValue(argv, flag), flag);
+    if (input === undefined)
+        return [];
+    const raw = await readJsonInput(input);
+    if (!Array.isArray(raw))
+        return fail(`${flag} must be a JSON array.`, "ULW_LOOP_STEERING_JSON_ARRAY_REQUIRED", { flag });
+    const parsed = [];
+    for (const item of raw) {
+        const next = child(item);
+        if (next === null)
+            return fail(`${flag} entries require title/objective.`, "ULW_LOOP_STEERING_CHILD_INVALID", { flag });
+        parsed.push(next);
+    }
+    return parsed;
+}
+async function stringArray(argv, flag) {
+    const raw = await readJsonInput(required(argv, flag));
+    if (!Array.isArray(raw))
+        return fail(`${flag} must be a JSON array.`, "ULW_LOOP_STEERING_JSON_ARRAY_REQUIRED", { flag });
+    const values = [];
+    for (const item of raw) {
+        if (typeof item !== "string")
+            return fail(`${flag} entries must be strings.`, "ULW_LOOP_STEERING_STRING_ARRAY_REQUIRED", { flag });
+        values.push(text(item, flag) ?? "");
+    }
+    return values;
+}
+function model(value) { const trimmed = text(value, "--user-model"); if (trimmed === undefined)
+    return undefined; return isModel(trimmed) ? trimmed : fail(`Invalid --user-model: ${trimmed}.`, "ULW_LOOP_STEERING_USER_MODEL_INVALID", { value: trimmed, expected: ULW_LOOP_SUCCESS_CRITERION_USER_MODELS }); }
+function neverKind(kind) { return fail(`Unsupported steering kind: ${String(kind)}.`, "ULW_LOOP_STEERING_KIND_UNSUPPORTED", { kind }); }
+export async function parseSteeringProposal(argv) {
+    const kind = parseSteeringKind(argv);
+    const source = parseSteeringSource(argv);
+    const base = { kind, source, evidence: required(argv, "--evidence"), rationale: required(argv, "--rationale") };
+    switch (kind) {
+        case "add_subgoal": return normalizeSteeringProposal({ ...base, title: required(argv, "--title"), objective: required(argv, "--objective") });
+        case "split_subgoal": {
+            const goalId = requiredGoal(argv);
+            return normalizeSteeringProposal({ ...base, goalId, targetGoalId: goalId, childGoals: await children(argv, "--children", true) });
+        }
+        case "reorder_pending": return normalizeSteeringProposal({ ...base, pendingOrder: await stringArray(argv, "--order") });
+        case "revise_pending_wording": {
+            const goalId = requiredGoal(argv);
+            const revisedTitle = readValue(argv, "--title");
+            const revisedObjective = readValue(argv, "--objective");
+            if (revisedTitle === undefined && revisedObjective === undefined)
+                return fail("revise_pending_wording requires --title or --objective.", "ULW_LOOP_STEERING_UPDATE_REQUIRED", { kind });
+            return normalizeSteeringProposal({ ...base, goalId, targetGoalId: goalId, ...(revisedTitle === undefined ? {} : { revisedTitle }), ...(revisedObjective === undefined ? {} : { revisedObjective }) });
+        }
+        case "revise_criterion": {
+            const goalId = requiredGoal(argv);
+            const criterionId = required(argv, "--criterion-id");
+            const scenario = readValue(argv, "--scenario");
+            const expectedEvidence = readValue(argv, "--expected-evidence");
+            const userModel = model(readValue(argv, "--user-model"));
+            if (scenario === undefined && expectedEvidence === undefined && userModel === undefined)
+                return fail("revise_criterion requires scenario, expected-evidence, or user-model.", "ULW_LOOP_STEERING_UPDATE_REQUIRED", { kind });
+            return normalizeSteeringProposal({ ...base, goalId, targetGoalId: goalId, criterionId, ...(scenario === undefined ? {} : { scenario }), ...(expectedEvidence === undefined ? {} : { expectedEvidence }), ...(userModel === undefined ? {} : { userModel }) });
+        }
+        case "annotate_ledger": return normalizeSteeringProposal(base);
+        case "mark_blocked_superseded": {
+            const goalId = requiredGoal(argv);
+            const childGoals = await children(argv, "--replacements", false);
+            return normalizeSteeringProposal({ ...base, goalId, targetGoalId: goalId, ...(childGoals.length === 0 ? {} : { childGoals }) });
+        }
+        default: return neverKind(kind);
+    }
+}
+function normalizedChildren(values) { if (values === undefined)
+    return undefined; return values.map((item) => ({ title: text(item.title, "child.title") ?? "", objective: text(item.objective, "child.objective") ?? "" })); }
+function normalizedStrings(values, field) { if (values === undefined)
+    return undefined; return values.map((value) => text(value, field) ?? ""); }
+export function normalizeSteeringProposal(proposal) {
+    const evidence = text(proposal.evidence, "evidence") ?? "";
+    const rationale = text(proposal.rationale, "rationale") ?? "";
+    const goalId = text(proposal.goalId, "goalId");
+    const targetGoalId = text(proposal.targetGoalId, "targetGoalId");
+    const targetGoalIds = normalizedStrings(proposal.targetGoalIds, "targetGoalIds");
+    const criterionId = text(proposal.criterionId, "criterionId");
+    const title = text(proposal.title, "title");
+    const objective = text(proposal.objective, "objective");
+    const revisedTitle = text(proposal.revisedTitle, "revisedTitle");
+    const revisedObjective = text(proposal.revisedObjective, "revisedObjective");
+    const blockedReason = text(proposal.blockedReason, "blockedReason");
+    const directiveText = text(proposal.directiveText, "directiveText");
+    const promptSignature = text(proposal.promptSignature, "promptSignature");
+    const idempotencyKey = text(proposal.idempotencyKey, "idempotencyKey");
+    const scenario = text(proposal.scenario, "scenario");
+    const expectedEvidence = text(proposal.expectedEvidence, "expectedEvidence");
+    const childGoals = normalizedChildren(proposal.childGoals);
+    const pendingOrder = normalizedStrings(proposal.pendingOrder, "pendingOrder");
+    return { kind: proposal.kind, source: proposal.source, evidence, rationale, ...(goalId === undefined ? {} : { goalId }), ...(targetGoalId === undefined ? {} : { targetGoalId }), ...(targetGoalIds === undefined ? {} : { targetGoalIds }), ...(criterionId === undefined ? {} : { criterionId }), ...(title === undefined ? {} : { title }), ...(objective === undefined ? {} : { objective }), ...(childGoals === undefined ? {} : { childGoals }), ...(revisedTitle === undefined ? {} : { revisedTitle }), ...(revisedObjective === undefined ? {} : { revisedObjective }), ...(pendingOrder === undefined ? {} : { pendingOrder }), ...(blockedReason === undefined ? {} : { blockedReason }), ...(proposal.after === undefined ? {} : { after: proposal.after }), ...(directiveText === undefined ? {} : { directiveText }), ...(promptSignature === undefined ? {} : { promptSignature }), ...(idempotencyKey === undefined ? {} : { idempotencyKey }), ...(proposal.now === undefined ? {} : { now: proposal.now }), ...(scenario === undefined ? {} : { scenario }), ...(expectedEvidence === undefined ? {} : { expectedEvidence }), ...(proposal.userModel === undefined ? {} : { userModel: proposal.userModel }) };
+}
+export function printSteerResult(result, json) {
+    if (json) {
+        printJson({ ok: result.accepted, accepted: result.accepted, rejectedReasons: result.rejectedReasons, deduped: result.deduped, audit: result.audit, plan: result.plan });
+        return;
+    }
+    const outcome = result.deduped ? "deduped" : result.accepted ? "accepted" : "rejected";
+    process.stdout.write(`ulw-loop steer: ${outcome} ${result.audit.kind}\n`);
+    if (result.rejectedReasons.length > 0)
+        process.stdout.write(`rejected: ${result.rejectedReasons.join("; ")}\n`);
+    if (result.audit.idempotencyKey !== undefined)
+        process.stdout.write(`idempotency-key: ${result.audit.idempotencyKey}\n`);
+    printStatus(result.plan);
+}

package/packages/omo-codex/plugin/components/ulw-loop/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/packages/omo-codex/plugin/components/ulw-loop/dist/cli.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { ulwLoopCommand } from "./cli-commands.js";
+import { runPreToolUseGoalBudgetGuardCli, runUlwLoopHookCli } from "./codex-hook.js";
+const TOP_LEVEL_HELP = "Usage:\n  omo ulw-loop <subcommand> [args]\n  omo hook user-prompt-submit         (Codex UserPromptSubmit hook)\n  omo help | --help | -h              (this message)\n\nRun `omo ulw-loop help` for ulw-loop subcommands.\n";
+async function main() {
+    const argv = process.argv.slice(2);
+    const command = argv[0];
+    if (command === undefined || command === "help" || command === "--help" || command === "-h") {
+        process.stdout.write(TOP_LEVEL_HELP);
+        return 0;
+    }
+    if (command === "ulw-loop")
+        return ulwLoopCommand(argv.slice(1));
+    if (command === "hook") {
+        const sub = argv[1];
+        if (sub === "user-prompt-submit") {
+            await runUlwLoopHookCli(process.stdin, process.stdout);
+            return 0;
+        }
+        if (sub === "pre-tool-use") {
+            await runPreToolUseGoalBudgetGuardCli(process.stdin, process.stdout);
+            return 0;
+        }
+        process.stderr.write(`[omo] unknown hook subcommand: ${sub ?? "(none)"}\n`);
+        return 1;
+    }
+    process.stderr.write(`[omo] unknown command: ${command}\n${TOP_LEVEL_HELP}`);
+    return 1;
+}
+main()
+    .then((code) => {
+    process.exit(code);
+})
+    .catch((error) => {
+    process.stderr.write(`[omo] ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+});

package/packages/omo-codex/plugin/components/ulw-loop/dist/codex-goal-instruction.d.ts

@@ -0,0 +1,14 @@
+import type { UlwLoopItem, UlwLoopPlan } from "./types.js";
+export interface CodexCreateGoalPayload {
+    readonly objective: string;
+    readonly status: "active";
+}
+export interface UlwLoopGoalInstruction {
+    readonly text: string;
+    readonly json: CodexCreateGoalPayload;
+}
+export declare function buildCodexGoalInstruction(args: {
+    readonly plan: UlwLoopPlan;
+    readonly goal: UlwLoopItem;
+    readonly isFinal?: boolean;
+}): UlwLoopGoalInstruction;

package/packages/omo-codex/plugin/components/ulw-loop/dist/codex-goal-instruction.js

@@ -0,0 +1,100 @@
+import { codexGoalMode, expectedCodexObjective, isFinalRunCompletionCandidate } from "./goal-status.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);
+    return { text: buildText(mode, args.plan, args.goal, createGoal, isFinal), json: createGoal };
+}
+function buildCreateGoalPayload(plan, goal) {
+    return { objective: expectedCodexObjective(plan, goal), status: "active" };
+}
+function buildText(mode, plan, goal, createGoal, isFinal) {
+    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 and status only.",
+        "- Goals are unlimited. Do not add numeric limits.",
+        ...modeConstraintLines(mode, isFinal),
+        finalSection(plan, goal, isFinal, mode === "aggregate"),
+        ...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 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 yet; the aggregate Codex goal must remain active while later OMO stories remain.",
+    ];
+}
+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:" : "";
+    return `-${remainingWork} [${criterion.id}] (${criterion.userModel}) ${criterion.scenario} — expect: ${criterion.expectedEvidence} — status: ${criterion.status}`;
+}
+function finalSection(plan, goal, isFinal, aggregate) {
+    if (!isFinal)
+        return "- This is not the final ulw-loop story; do not run the final ai-slop-cleaner/$code-review gate yet.";
+    const option = sessionOption(plan);
+    const blockerCommand = `omo 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 ulw-loop checkpoint${option} --goal-id ${goal.id} --status complete --evidence "<tests/files/PR evidence>" --codex-goal-json "<fresh complete get_goal JSON or path>" --quality-gate-json "<quality gate JSON or path>"`;
+    return joinLines([
+        "Final story — run mandatory quality gate before update_goal:",
+        "- Run ai-slop-cleaner on changed files even when it is a no-op, rerun verification, then run $code-review.",
+        "- If final $code-review is not APPROVE with architect status CLEAR, do not call update_goal. Record blocker work first:",
+        `  ${blockerCommand}`,
+        aggregate
+            ? '- If final $code-review is clean, call update_goal({status: "complete"}), call get_goal again, then checkpoint the aggregate story:'
+            : '- If final $code-review 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");
+}

package/packages/omo-codex/plugin/components/ulw-loop/dist/codex-goal-snapshot.d.ts

@@ -0,0 +1,26 @@
+export type CodexGoalSnapshotStatus = "active" | "complete" | "cancelled" | "failed" | "unknown";
+export interface CodexGoalSnapshot {
+    available: boolean;
+    objective?: string;
+    status?: CodexGoalSnapshotStatus;
+    raw: unknown;
+}
+export interface CodexGoalReconciliation {
+    ok: boolean;
+    snapshot: CodexGoalSnapshot;
+    warnings: string[];
+    errors: string[];
+}
+export interface ReconcileCodexGoalOptions {
+    expectedObjective: string;
+    acceptedObjectives?: readonly string[];
+    allowedStatuses?: readonly CodexGoalSnapshotStatus[];
+    requireSnapshot?: boolean;
+    requireComplete?: boolean;
+}
+export declare class CodexGoalSnapshotError extends Error {
+}
+export declare function parseCodexGoalSnapshot(value: unknown): CodexGoalSnapshot;
+export declare function readCodexGoalSnapshotInput(raw: string | undefined, cwd?: string): Promise<CodexGoalSnapshot | null>;
+export declare function reconcileCodexGoalSnapshot(snapshot: CodexGoalSnapshot | null | undefined, options: ReconcileCodexGoalOptions): CodexGoalReconciliation;
+export declare function formatCodexGoalReconciliation(reconciliation: CodexGoalReconciliation): string;

package/packages/omo-codex/plugin/components/ulw-loop/dist/codex-goal-snapshot.js

@@ -0,0 +1,97 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+export class CodexGoalSnapshotError extends Error {
+}
+function safeObject(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function safeString(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function normalizeStatus(value) {
+    const status = safeString(value).toLowerCase();
+    if (status === "complete" || status === "completed" || status === "done")
+        return "complete";
+    if (status === "cancelled" || status === "canceled")
+        return "cancelled";
+    if (status === "failed" || status === "failure")
+        return "failed";
+    if (status === "active" || status === "in_progress" || status === "pending" || status === "running")
+        return "active";
+    return "unknown";
+}
+function normalizeObjective(value) {
+    return value.replace(/\s+/g, " ").trim();
+}
+export function parseCodexGoalSnapshot(value) {
+    const root = safeObject(value);
+    const goalValue = Object.hasOwn(root, "goal") ? root["goal"] : value;
+    if (goalValue === null || goalValue === undefined || goalValue === false) {
+        return { available: false, raw: value };
+    }
+    const goal = safeObject(goalValue);
+    const objective = safeString(goal["objective"] ?? goal["goal"] ?? goal["description"] ?? root["objective"]);
+    const status = normalizeStatus(goal["status"] ?? root["status"]);
+    return {
+        available: Boolean(objective || status !== "unknown"),
+        ...(objective ? { objective } : {}),
+        status,
+        raw: value,
+    };
+}
+export async function readCodexGoalSnapshotInput(raw, cwd = process.cwd()) {
+    if (!raw?.trim())
+        return null;
+    const trimmed = raw.trim();
+    try {
+        return parseCodexGoalSnapshot(JSON.parse(trimmed));
+    }
+    catch {
+        const path = resolve(cwd, trimmed);
+        if (!existsSync(path)) {
+            throw new CodexGoalSnapshotError(`Codex goal snapshot is neither valid JSON nor a readable path: ${trimmed}`);
+        }
+        try {
+            return parseCodexGoalSnapshot(JSON.parse(await readFile(path, "utf-8")));
+        }
+        catch (error) {
+            throw new CodexGoalSnapshotError(`Codex goal snapshot path does not contain valid JSON: ${trimmed}${error instanceof Error ? ` (${error.message})` : ""}`);
+        }
+    }
+}
+export function reconcileCodexGoalSnapshot(snapshot, options) {
+    const effectiveSnapshot = snapshot ?? { available: false, raw: null };
+    const errors = [];
+    const warnings = [];
+    if (!effectiveSnapshot.available) {
+        const message = "Codex goal snapshot is absent or reports no active goal; call get_goal and pass its JSON with --codex-goal-json.";
+        if (options.requireSnapshot)
+            errors.push(message);
+        else
+            warnings.push(message);
+        return { ok: errors.length === 0, snapshot: effectiveSnapshot, warnings, errors };
+    }
+    const expected = normalizeObjective(options.expectedObjective);
+    const accepted = new Set([expected, ...(options.acceptedObjectives ?? []).map((objective) => normalizeObjective(objective))].filter(Boolean));
+    const actual = normalizeObjective(effectiveSnapshot.objective ?? "");
+    if (!actual) {
+        errors.push("Codex goal snapshot is missing objective text.");
+    }
+    else if (!accepted.has(actual)) {
+        errors.push(`Codex goal objective mismatch: expected "${expected}", got "${actual}".`);
+    }
+    const allowed = options.allowedStatuses ?? (options.requireComplete ? ["complete"] : ["active", "complete"]);
+    const actualStatus = effectiveSnapshot.status ?? "unknown";
+    if (!allowed.includes(actualStatus)) {
+        errors.push(`Codex goal status mismatch: expected ${allowed.join(" or ")}, got ${actualStatus}.`);
+    }
+    if (options.requireComplete && actualStatus !== "complete") {
+        errors.push('Codex goal is not complete; call update_goal({status: "complete"}) only after the objective is actually complete, then pass the fresh get_goal JSON.');
+    }
+    return { ok: errors.length === 0, snapshot: effectiveSnapshot, warnings, errors };
+}
+export function formatCodexGoalReconciliation(reconciliation) {
+    const parts = [...reconciliation.errors, ...reconciliation.warnings];
+    return parts.join(" ");
+}

package/packages/omo-codex/plugin/components/ulw-loop/dist/codex-hook.d.ts

@@ -0,0 +1,28 @@
+export interface UserPromptSubmitPayload {
+    readonly cwd: string;
+    readonly hook_event_name: "UserPromptSubmit";
+    readonly model?: string;
+    readonly permission_mode?: string;
+    readonly prompt: string;
+    readonly session_id: string;
+    readonly transcript_path?: string;
+    readonly turn_id?: string;
+}
+export interface PreToolUsePayload {
+    readonly cwd: string;
+    readonly hook_event_name: "PreToolUse";
+    readonly model: string;
+    readonly permission_mode: string;
+    readonly session_id: string;
+    readonly tool_input: unknown;
+    readonly tool_name: string;
+    readonly tool_use_id: string;
+    readonly transcript_path: string | null;
+    readonly turn_id: string;
+}
+export declare function parseUserPromptSubmitPayload(raw: string): UserPromptSubmitPayload | null;
+export declare function parsePreToolUsePayload(raw: string): PreToolUsePayload | null;
+export declare function applyUserPromptUlwLoopSteering(payload: UserPromptSubmitPayload): Promise<string>;
+export declare function applyPreToolUseGoalBudgetGuard(payload: PreToolUsePayload): string;
+export declare function runUlwLoopHookCli(stdin: NodeJS.ReadableStream, stdout: NodeJS.WritableStream): Promise<void>;
+export declare function runPreToolUseGoalBudgetGuardCli(stdin: NodeJS.ReadableStream, stdout: NodeJS.WritableStream): Promise<void>;