Skip to content

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

9.5 KB
Raw Blame
import { existsSync, readFileSync, writeFileSync } from "node:fs";
import { isAbsolute, join, resolve, sep } from "node:path";
import { readLedgerAt } from "./ledger.js";
import { normalizeUlwLoopSessionId, ulwLoopDir, ulwLoopStateLockPath } from "./paths.js";
import { readUlwLoopPlanSync } from "./plan-io.js";
import { isStateLockTimeout, withStateLockSync } from "./state-lock.js";
// Turn-death recovery only: Codex emits Stop when a turn ends, so a run that
// dies mid-turn (crash, kill, context blowup before any Stop) never reaches
// this handler. Mid-turn stalls are out of scope by design.
const RESUME_CAP = 2;
// Mirrors ulw-execute-continuation's context-pressure bail-out: injecting a
// resume directive into an already-overflowing context makes things worse.
const CONTEXT_PRESSURE_MARKERS = [
    "context compacted",
    "context_length_exceeded",
    "skill descriptions were shortened",
    "context_too_large",
    "codex ran out of room in the model's context window",
    "your input exceeds the context window",
    "long threads and multiple compactions",
];
export function runStopResumeHook(input) {
    const payload = parseStopPayload(input);
    if (payload === null || payload.stop_hook_active)
        return "";
    if (transcriptShowsContextPressure(payload.transcript_path))
        return "";
    if (boulderContinuationWillFire(payload.cwd, payload.session_id))
        return "";
    const scope = { sessionId: payload.session_id };
    const stateDir = ulwLoopDir(payload.cwd, scope);
    const plan = readPlan(payload.cwd, payload.session_id);
    if (plan === null || plan.aggregateCompletion?.status === "complete")
        return "";
    const goal = resumableGoal(plan);
    if (goal === undefined)
        return "";
    if (!consumeResumeBudgetLocked(ulwLoopStateLockPath(payload.cwd, scope), stateDir, goal.id))
        return "";
    const output = {
        decision: "block",
        reason: renderResumeDirective(plan, goal, payload.session_id),
    };
    return JSON.stringify(output);
}
export async function runStopResumeHookCli(stdin, stdout) {
    try {
        const chunks = [];
        for await (const chunk of stdin)
            chunks.push(Buffer.from(chunk));
        const output = runStopResumeHook(JSON.parse(Buffer.concat(chunks).toString("utf8")));
        if (output.length > 0)
            stdout.write(output);
    }
    catch (error) {
        if (error instanceof Error)
            return;
    }
}
function resumableGoal(plan) {
    const active = plan.goals.find((goal) => goal.id === plan.activeGoalId);
    if (active !== undefined && isResumableStatus(active.status))
        return active;
    return plan.goals.find((goal) => isResumableStatus(goal.status));
}
function isResumableStatus(status) {
    return status === "pending" || status === "in_progress";
}
// A resume is a budgeted side effect; when the session lock cannot be taken the
// hook stays silent (fail closed) instead of charging the counter unlocked.
function consumeResumeBudgetLocked(lockPath, stateDir, goalId) {
    try {
        return withStateLockSync(lockPath, () => consumeResumeBudget(stateDir, goalId));
    }
    catch (error) {
        if (isStateLockTimeout(error))
            return false;
        throw error;
    }
}
// Hook budget counters are exempt from plan/audit commits. Count reconciled
// entries, not cache lines: a writer dying after link still made progress.
function consumeResumeBudget(stateDir, goalId) {
    const ledgerLineCount = readLedgerAt(stateDir).length;
    const counterPath = resolve(stateDir, `auto-resume-${goalId}.json`);
    const stuckPath = resolve(stateDir, `auto-resume-${goalId}.stuck`);
    // goals.json is untrusted input: a crafted goal id (e.g. `../../x`) must
    // never drive a write outside the session state dir. Deny the resume.
    if (!isInsideDir(stateDir, counterPath) || !isInsideDir(stateDir, stuckPath))
        return false;
    const previous = readCounter(counterPath);
    const count = previous !== null && previous.ledgerLineCount === ledgerLineCount ? previous.count : 0;
    if (count >= RESUME_CAP) {
        writeFileSync(stuckPath, `no ledger progress after ${count} resumes\n`);
        return false;
    }
    writeFileSync(counterPath, JSON.stringify({ count: count + 1, ledgerLineCount }));
    return true;
}
function isInsideDir(dir, candidate) {
    return candidate.startsWith(resolve(dir) + sep);
}
function renderResumeDirective(plan, goal, sessionId) {
    const normalized = normalizeUlwLoopSessionId(sessionId);
    const option = normalized !== null && plan.goalsPath.includes(`/${normalized}/`) ? ` --session-id ${normalized}` : "";
    return [
        `The ulw-loop run in this session still has unfinished goals (next: ${goal.id} - ${goal.title}).`,
        "The turn ended before the loop completed. Resume it now:",
        `1. Run \`omo-agent-toolkit ulw-loop status${option} --json\` to reload the plan, the active goal, and currentAttemptDir.`,
        "2. Continue the active goal's remaining success criteria, recording evidence with record-evidence.",
        `3. Checkpoint through \`omo-agent-toolkit ulw-loop checkpoint${option}\` when the goal's criteria are proven; a complete checkpoint prints the next goal instruction.`,
        "If the loop is genuinely blocked on the user, checkpoint the goal as blocked with the reason instead.",
    ].join("\n");
}
function readPlan(repoRoot, sessionId) {
    try {
        return readUlwLoopPlanSync(repoRoot, { sessionId });
    }
    catch (error) {
        if (error instanceof Error)
            return null;
        throw error;
    }
}
function readCounter(counterPath) {
    try {
        if (!existsSync(counterPath))
            return null;
        const parsed = JSON.parse(readFileSync(counterPath, "utf8"));
        if (typeof parsed["count"] !== "number" || typeof parsed["ledgerLineCount"] !== "number")
            return null;
        return { count: parsed["count"], ledgerLineCount: parsed["ledgerLineCount"] };
    }
    catch (error) {
        if (error instanceof Error)
            return null;
        throw error;
    }
}
// Local ~10-LOC approximation of ulw-execute-continuation's boulder check (no
// cross-component import allowed): any continuable work for this session means
// that hook owns the Stop event, so this one stays silent.
function boulderContinuationWillFire(cwd, sessionId) {
    try {
        const raw = JSON.parse(readFileSync(join(cwd, ".omo", "boulder.json"), "utf8"));
        const works = raw["works"];
        // The flat legacy shape has no works map: the top level is the single work.
        const entries = typeof works === "object" && works !== null ? Object.values(works) : [raw];
        return entries.some((work) => {
            if (typeof work !== "object" || work === null)
                return false;
            const entry = work;
            const sessionIds = Array.isArray(entry["session_ids"]) ? entry["session_ids"] : [];
            const continuable = entry["status"] === "active" || entry["status"] === "paused";
            return continuable && sessionIds.includes(`codex:${sessionId}`) && boulderPlanHasChecklist(cwd, entry);
        });
    }
    catch (error) {
        if (error instanceof Error)
            return false;
        throw error;
    }
}
function transcriptShowsContextPressure(transcriptPath) {
    try {
        const transcript = readFileSync(transcriptPath, "utf8").toLowerCase();
        return CONTEXT_PRESSURE_MARKERS.some((marker) => transcript.includes(marker));
    }
    catch (error) {
        if (error instanceof Error)
            return false;
        throw error;
    }
}
// ulw-execute-continuation owns an active Boulder plan until its final gate marks
// the work complete, including the zero-remaining checklist state.
function boulderPlanHasChecklist(cwd, entry) {
    const activePlan = entry["active_plan"];
    if (typeof activePlan !== "string" || activePlan.trim().length === 0)
        return false;
    const planPath = isAbsolute(activePlan) ? activePlan : join(cwd, activePlan);
    const worktree = entry["worktree_path"];
    const candidates = typeof worktree === "string" && worktree.trim().length > 0 && !isAbsolute(activePlan)
        ? [join(isAbsolute(worktree) ? worktree : join(cwd, worktree), activePlan), planPath]
        : [planPath];
    for (const candidate of candidates) {
        try {
            return readFileSync(candidate, "utf8")
                .split(/\r?\n/)
                .some((line) => line.startsWith("- [ ] ") || line.startsWith("- [x] ") || line.startsWith("- [X] "));
        }
        catch (error) {
            if (!(error instanceof Error))
                throw error;
        }
    }
    return false;
}
function parseStopPayload(value) {
    if (typeof value !== "object" || value === null || Array.isArray(value))
        return null;
    const record = value;
    const optionalMessage = record["last_assistant_message"];
    const valid = record["hook_event_name"] === "Stop" &&
        typeof record["session_id"] === "string" &&
        typeof record["turn_id"] === "string" &&
        typeof record["transcript_path"] === "string" &&
        typeof record["cwd"] === "string" &&
        typeof record["model"] === "string" &&
        typeof record["permission_mode"] === "string" &&
        typeof record["stop_hook_active"] === "boolean" &&
        (optionalMessage === undefined || typeof optionalMessage === "string");
    if (!valid)
        return null;
    return {
        session_id: record["session_id"],
        cwd: record["cwd"],
        transcript_path: record["transcript_path"],
        stop_hook_active: record["stop_hook_active"],
    };
}