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
import { mkdirSync } from "node:fs";
import { join } from "node:path";
import { parsePreToolUsePayload } from "./codex-hook.js";
import { isFinalRunCompletionCandidate } from "./goal-status.js";
import { ulwLoopAttemptEvidenceDir, ulwLoopDir, ulwLoopStateLockPath } from "./paths.js";
import { readUlwLoopPlanSync } from "./plan-io.js";
import { registeredAgentRoles } from "./registered-agent-roles.js";
import { atomicWriteJson, isNonEmptyFile, readAdmissionBreaker, readCount, readCounts } from "./spawn-budget-io.js";
import { spawnRoleDenial } from "./spawn-role-guard.js";
import { isStateLockTimeout, withStateLockSync } from "./state-lock.js";
import { canonicalReviewerAgentName, GATE_REVIEWER_AGENT_NAMES, LEGACY_REVIEWER_AGENT_ALIASES, REVIEWER_ROLES_BY_SURFACE, resolveToolkitSurface, reviewerRolesFor, } from "./surface.js";
// spawn_agent = v1; collaborationspawn_agent = the delimiter-free flattened v2
// hook token from codex-rs hook_names.rs; collaboration.spawn_agent = the
// dotted token observed live in the task-1 probe (hook-tool-tokens.txt).
const SPAWN_TOOL_TOKENS = new Set([
"spawn_agent",
"multi_agent_v1.spawn_agent",
"collaborationspawn_agent",
"collaboration.spawn_agent",
]);
export const DEFAULT_FANOUT_LIMIT = 24;
const DEFAULT_REVIEW_SPAWN_LIMIT = 3;
const GATE_MESSAGE_PATTERN = /lazycodex-gate-reviewer|omo-native-gate-reviewer|omo-senpi-gate-reviewer|final gate review/i;
const REVIEW_AGENT_TYPES = [
...Object.values(REVIEWER_ROLES_BY_SURFACE).map((roles) => roles.gateReview),
...Object.values(REVIEWER_ROLES_BY_SURFACE).map((roles) => roles.codeReview),
...Object.values(REVIEWER_ROLES_BY_SURFACE).map((roles) => roles.manualQa),
...Object.keys(LEGACY_REVIEWER_AGENT_ALIASES),
];
const REVIEW_AGENT_TYPE_SET = new Set(REVIEW_AGENT_TYPES);
export function applySpawnGuards(payload, options = {}) {
if (payload.hook_event_name !== "PreToolUse" || !SPAWN_TOOL_TOKENS.has(payload.tool_name))
return "";
if (resolveToolkitSurface() === "lazycodex") {
const reason = spawnRoleDenial(payload.tool_input, () => registeredAgentRoles(payload.cwd));
if (reason !== null)
return deny(reason);
}
return applySpawnBudgetGuards(payload, options);
}
export function applySpawnBudgetGuards(payload, options = {}) {
if (payload.hook_event_name !== "PreToolUse" || !SPAWN_TOOL_TOKENS.has(payload.tool_name))
return "";
const breaker = readAdmissionBreaker(payload.session_id);
if (breaker !== null)
return deny(`Subagent admission failed earlier in this session (${breaker}). Do not spawn more workers or reviewers; report the capacity block and wait for the user.`);
const scope = { sessionId: payload.session_id };
const stateDir = ulwLoopDir(payload.cwd, scope);
const plan = readPlan(payload.cwd, payload.session_id);
if (plan === null)
return "";
const lockOptions = options.lockTimeoutMs === undefined ? {} : { timeoutMs: options.lockTimeoutMs };
try {
return withStateLockSync(ulwLoopStateLockPath(payload.cwd, scope), () => evaluateGuards(payload, plan, stateDir), lockOptions);
}
catch (error) {
if (isStateLockTimeout(error))
return deny(`ulw-loop spawn guard could not take the session state lock: ${error.message}`);
throw error;
}
}
function evaluateGuards(payload, plan, stateDir) {
const fanOutPeek = peekFanOutBudget(stateDir);
if (fanOutPeek !== null)
return deny(fanOutPeek);
const missingArtifact = missingGateArtifact(payload, plan);
if (missingArtifact !== null)
return deny(`record manual QA first; gate audits its artifacts: missing ${missingArtifact}`);
const reviewDenial = consumeReviewSpawnBudget(payload, plan, stateDir);
if (reviewDenial !== null)
return deny(reviewDenial);
const fanOutDenial = consumeFanOutBudget(stateDir);
if (fanOutDenial !== null)
return deny(fanOutDenial);
return "";
}
export async function runSpawnAdmissionRecorderCli(stdin, stdout) {
const chunks = [];
for await (const chunk of stdin)
chunks.push(Buffer.from(chunk));
try {
const payload = JSON.parse(Buffer.concat(chunks).toString("utf8"));
const response = typeof payload["tool_response"] === "string"
? payload["tool_response"]
: JSON.stringify(payload["tool_response"] ?? "");
if (!/too many active cells|AgentLimitReached|max_threads|max_concurrent_threads_per_session/i.test(response))
return;
const dataDir = process.env["PLUGIN_DATA"];
if (typeof dataDir !== "string" || typeof payload["session_id"] !== "string")
return;
const markerDir = join(dataDir, "spawn-breaker");
try {
mkdirSync(markerDir, { recursive: true });
atomicWriteJson(join(markerDir, `${payload["session_id"]}.json`), {
reason: response,
at: new Date().toISOString(),
});
}
catch (error) {
const message = error instanceof Error ? error.message : String(error);
process.stderr.write(`[ulw-loop] spawn-guard: could not persist admission failure: ${message}\n`);
}
}
catch {
/* malformed hook input is ignored */
}
void stdout;
}
export async function runSpawnGuardCli(stdin, stdout) {
try {
const chunks = [];
for await (const chunk of stdin)
chunks.push(Buffer.from(chunk));
const payload = parsePreToolUsePayload(Buffer.concat(chunks).toString("utf8"));
if (payload === null) {
stdout.write(deny("LazyCodex spawn guard received an invalid hook payload; role routing was not verified."));
return;
}
const output = applySpawnGuards(payload);
if (output.length > 0)
stdout.write(output);
}
catch (error) {
stdout.write(deny(`LazyCodex spawn guard failed: ${error instanceof Error ? error.message : String(error)}`));
}
}
// Read-only fan-out eligibility check. Returns a denial reason when the next
// spawn would exceed the limit, without incrementing the counter. Call this
// before charging any per-reviewer quota so a saturated global cap cannot
// silently consume reviewer allowances for spawns that will never run.
function peekFanOutBudget(stateDir) {
const counterPath = join(stateDir, "spawn-count.json");
const count = readCount(counterPath) + 1;
const limit = fanOutLimit();
if (count <= limit)
return null;
return `ulw-loop spawn fan-out cap reached (${count}/${limit}). Consolidate work into the agents already running, or raise OMO_SPAWN_FANOUT_LIMIT if this volume is intentional.`;
}
// Hook budget counters are exempt from plan/audit commits.
// Per-session spawn counter; depth/lineage tracking is descoped — this is a
// total-volume backstop against fan-out explosions, not a recursion tracker.
function consumeFanOutBudget(stateDir) {
const counterPath = join(stateDir, "spawn-count.json");
const count = readCount(counterPath) + 1;
atomicWriteJson(counterPath, { count });
const limit = fanOutLimit();
if (count <= limit)
return null;
return `ulw-loop spawn fan-out cap reached (${count}/${limit}). Consolidate work into the agents already running, or raise OMO_SPAWN_FANOUT_LIMIT if this volume is intentional.`;
}
function consumeReviewSpawnBudget(payload, plan, stateDir) {
const agentType = reviewAgentType(payload.tool_input);
if (agentType === null)
return null;
const goal = plan.goals.find((candidate) => candidate.id === plan.activeGoalId) ??
plan.goals.find((candidate) => isFinalRunCompletionCandidate(plan, candidate));
if (goal === undefined)
return null;
const counterPath = join(stateDir, "review-spawn-counts.json");
const limit = reviewSpawnLimit();
const counts = readCounts(counterPath);
const key = `${agentType}:${goal.id}:a${goal.attempt}`;
const count = (counts[key] ?? 0) + 1;
if (count > limit)
return `ulw-loop reviewer no-progress cap reached (${agentType} ${count}/${limit}) for ${goal.id} attempt ${goal.attempt}. Consolidate existing review findings, or checkpoint and start a new attempt after concrete progress.`;
counts[key] = count;
atomicWriteJson(counterPath, counts);
return null;
}
function missingGateArtifact(payload, plan) {
if (!isGateReviewerSpawn(payload.tool_input))
return null;
const goal = plan.goals.find((candidate) => isFinalRunCompletionCandidate(plan, candidate));
if (goal === undefined || goal.status === "complete")
return null;
if (!goal.successCriteria.every((criterion) => criterion.status === "pass"))
return null;
const scope = { sessionId: payload.session_id };
const requiredArtifacts = [`${goal.id}-manual-qa.md`];
if (plan.evidenceLayoutVersion === 2) {
const attemptDir = ulwLoopAttemptEvidenceDir(goal.id, goal.attempt, scope);
for (const name of requiredArtifacts) {
const relative = `${attemptDir}/${name}`;
if (!isNonEmptyFile(join(payload.cwd, relative)))
return relative;
}
return null;
}
const manualQa = `.omo/evidence/${goal.id}-manual-qa.md`;
return isNonEmptyFile(join(payload.cwd, manualQa)) ? null : manualQa;
}
function isGateReviewerSpawn(toolInput) {
const agentType = reviewAgentType(toolInput);
return agentType !== null && GATE_REVIEWER_AGENT_NAMES.has(agentType);
}
function reviewAgentType(toolInput) {
if (typeof toolInput !== "object" || toolInput === null)
return null;
const record = toolInput;
const agentType = record["agent_type"];
if (typeof agentType === "string") {
// V1: agent_type is present — only reviewer types proceed; any other type is not a review spawn.
if (!REVIEW_AGENT_TYPE_SET.has(agentType))
return null;
return activeSurfaceReviewerAlias(agentType);
}
const message = record["message"];
if (typeof message !== "string")
return null;
const normalizedMessage = message.toLowerCase();
// Explicit "act as <role>" assignment takes priority. If the assigned role is not a reviewer,
// treat the spawn as non-review so a message that merely mentions a reviewer name does not
// accidentally charge that reviewer's quota.
const allRoleNames = [...REVIEW_AGENT_TYPES];
const explicitAssignment = allRoleNames
.map((name) => ({
name,
index: normalizedMessage.search(new RegExp(`\\bact as (?:an? )?${name}\\b`)),
}))
.filter(({ index }) => index >= 0)
.sort((left, right) => left.index - right.index)[0];
if (explicitAssignment !== undefined)
return activeSurfaceReviewerAlias(explicitAssignment.name);
// Check for an explicit "act as <non-reviewer-role>" assignment. If found, the spawn is not a
// review spawn even if the message body mentions a reviewer name.
const nonReviewerActAs = /\bact as (?:an? )?\S+/.test(normalizedMessage);
if (nonReviewerActAs)
return null;
const namedReviewer = REVIEW_AGENT_TYPES.find((name) => normalizedMessage.includes(name));
if (namedReviewer !== undefined)
return activeSurfaceReviewerAlias(namedReviewer);
return GATE_MESSAGE_PATTERN.test(message) ? reviewerRolesFor(resolveToolkitSurface()).gateReview : null;
}
function activeSurfaceReviewerAlias(reviewer) {
const canonical = canonicalReviewerAgentName(reviewer);
const activeRoles = reviewerRolesFor(resolveToolkitSurface());
for (const roles of Object.values(REVIEWER_ROLES_BY_SURFACE)) {
if (canonical === roles.codeReview)
return activeRoles.codeReview;
if (canonical === roles.manualQa)
return activeRoles.manualQa;
if (canonical === roles.gateReview)
return activeRoles.gateReview;
}
return canonical;
}
function deny(reason) {
return `${JSON.stringify({
hookSpecificOutput: {
hookEventName: "PreToolUse",
permissionDecision: "deny",
permissionDecisionReason: reason,
additionalContext: reason,
},
})}\n`;
}
function fanOutLimit() {
const raw = process.env["OMO_SPAWN_FANOUT_LIMIT"];
if (raw === undefined)
return DEFAULT_FANOUT_LIMIT;
const parsed = Number.parseInt(raw, 10);
return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_FANOUT_LIMIT;
}
function reviewSpawnLimit() {
const raw = process.env["OMO_ULW_LOOP_REVIEW_SPAWN_LIMIT"];
if (raw === undefined)
return DEFAULT_REVIEW_SPAWN_LIMIT;
const parsed = Number.parseInt(raw, 10);
return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_REVIEW_SPAWN_LIMIT;
}
function readPlan(repoRoot, sessionId) {
try {
return readUlwLoopPlanSync(repoRoot, { sessionId });
}
catch (error) {
if (error instanceof Error)
return null;
throw error;
}
}