@andromarces/agent-loops 0.2.0

package/src/hook/parent-guard.mjs

@@ -0,0 +1,40 @@
+// Claude Code PreToolUse hook (#57), registered in .claude/settings.json for
+// Edit|Write|MultiEdit|NotebookEdit. Reads the hook JSON from stdin and prints
+// a deny decision on stdout only while the hook session is the parent of a
+// non-terminal run. Every other outcome exits 0 with no output — unparseable
+// input, a malformed session id, or an unexpected lookup error all leave the
+// normal permission flow intact; the hook never leaks an error to the session.
+import { decideParentGuard } from "./decision.mjs";
+
+async function readHookInput() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch {
+    return null;
+  }
+}
+
+const input = await readHookInput();
+const sessionId = typeof input?.session_id === "string" ? input.session_id : null;
+if (sessionId) {
+  try {
+    const verdict = await decideParentGuard(sessionId);
+    if (verdict.decision === "deny") {
+      console.log(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "deny",
+            permissionDecisionReason: verdict.reason,
+          },
+        }),
+      );
+    }
+  } catch {
+    // A failed lookup denies nothing: the guard never blocks on its own error.
+  }
+}

package/src/lib/args.mjs

@@ -0,0 +1,43 @@
+// Shared CLI argument readers and agent option validation, used by both the
+// headless loop (src/cli.mjs) and the role subcommand (src/role.mjs).
+import { normalizeAgent } from "../agents/index.mjs";
+
+export function readArgValue(argv, flag, index) {
+  const value = argv[index];
+  if (!value || value.startsWith("-")) {
+    throw new Error(`Missing value for ${flag}.`);
+  }
+  return value;
+}
+
+export function readPositiveInt(flag, value) {
+  const val = Number(value);
+  if (!Number.isInteger(val) || val < 1) {
+    throw new Error(`${flag} must be a positive integer.`);
+  }
+  return val;
+}
+
+export function readNonNegativeInt(flag, value) {
+  const val = Number(value);
+  if (!Number.isInteger(val) || val < 0) {
+    throw new Error(`${flag} must be a non-negative integer.`);
+  }
+  return val;
+}
+
+export function assertOpenCodeOptions(role, kind, model, effort) {
+  if (kind && normalizeAgent(kind) !== "opencode") {
+    return;
+  }
+
+  if (effort && !model) {
+    throw new Error(`--${role}-effort requires --${role}-model for opencode.`);
+  }
+
+  if (effort && model?.includes("#")) {
+    throw new Error(
+      `--${role}-model "${model}" already contains a variant and cannot be combined with --${role}-effort.`,
+    );
+  }
+}

package/src/lib/entrypoint.mjs

@@ -0,0 +1,17 @@
+import { realpathSync } from "node:fs";
+
+/**
+ * Reports whether the module at modulePath is the process entry point.
+ *
+ * Compares real paths, so a bin shim that reaches the file through a symlinked
+ * package directory (pnpm, npm on POSIX) still matches. A plain path compare
+ * fails there, and the CLI exits without running.
+ */
+export function isEntryPoint(modulePath) {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(modulePath);
+  } catch {
+    return false;
+  }
+}

package/src/lib/exec.mjs

@@ -0,0 +1,100 @@
+import { execa } from "execa";
+import { logDebug, logInfo } from "./log.mjs";
+
+export class ExecError extends Error {
+  constructor(
+    message,
+    { command, exitCode, stdout, stderr, timedOut, isCanceled, isTerminated } = {},
+  ) {
+    super(message);
+    this.name = "ExecError";
+    this.command = command;
+    this.exitCode = exitCode;
+    this.stdout = stdout ?? "";
+    this.stderr = stderr ?? "";
+    this.timedOut = Boolean(timedOut);
+    this.isCanceled = Boolean(isCanceled);
+    this.isTerminated = Boolean(isTerminated);
+  }
+}
+
+export async function exec(command, args = [], options = {}) {
+  const { cwd, input, timeout, signal, role, env } = options;
+
+  const label = role ? `${role}: ${command}` : command;
+  const startedAt = Date.now();
+  logInfo(`${label} started`);
+
+  const execaOptions = {
+    cwd,
+    reject: false,
+    input,
+    stdin: input === undefined ? "ignore" : undefined,
+    killDescendants: true,
+  };
+
+  // execa merges env with process.env; the child still inherits the launcher environment.
+  if (env) {
+    execaOptions.env = env;
+  }
+
+  if (typeof timeout === "number" && timeout > 0) {
+    execaOptions.timeout = timeout * 1000;
+  }
+
+  if (signal) {
+    execaOptions.cancelSignal = signal;
+  }
+
+  const result = await execa(command, args, execaOptions);
+
+  const timedOut = Boolean(result.timedOut);
+  const isCanceled = Boolean(result.isCanceled);
+  const isTerminated = Boolean(result.isTerminated);
+
+  if (result.exitCode !== 0 || timedOut || isCanceled || isTerminated) {
+    let cause;
+    if (timedOut) {
+      cause = `${command} timed out after ${timeout} seconds.`;
+    } else if (isCanceled) {
+      cause = `${command} was canceled.`;
+    } else if (isTerminated) {
+      // POSIX-only: execa cannot detect signal termination on Windows.
+      const description = result.signalDescription ?? result.signal ?? "a signal";
+      cause = `${command} was killed by ${description}.`;
+    } else if (result.exitCode === undefined) {
+      // POSIX-only: execa leaves exitCode undefined when the subprocess
+      // could not be spawned (Windows reports exit code 1 instead).
+      cause = `${command} failed to start.`;
+    } else {
+      cause = `${command} exited with code ${result.exitCode}.`;
+    }
+
+    const message = [cause, result.stderr?.trim(), result.stdout?.trim()]
+      .filter(Boolean)
+      .join("\n\n");
+
+    // The caller owns the failure level (it knows whether the runtime recovers); this
+    // debug line terminates the invocation trace when the caller does not log one.
+    logDebug(`${label} failed in ${Date.now() - startedAt}ms: ${cause}`);
+
+    throw new ExecError(message, {
+      command,
+      exitCode: result.exitCode,
+      stdout: result.stdout,
+      stderr: result.stderr,
+      timedOut,
+      isCanceled,
+      isTerminated,
+    });
+  }
+
+  const durationMs = Date.now() - startedAt;
+  logInfo(`${label} finished in ${durationMs}ms (exit 0)`);
+
+  return {
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    durationMs,
+  };
+}

package/src/lib/json.mjs

@@ -0,0 +1,53 @@
+export function parseJson(text, description) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`Invalid JSON from ${description}:\n${text.slice(0, 2000)}`);
+  }
+}
+
+export function parseJsonLines(text) {
+  const events = [];
+
+  for (const line of text.split(/\r?\n/)) {
+    const trimmed = line.trim();
+
+    if (!trimmed) {
+      continue;
+    }
+
+    try {
+      events.push(JSON.parse(trimmed));
+    } catch {
+      // Ignore non-JSON diagnostic lines.
+    }
+  }
+
+  return events;
+}
+
+export function extractJsonObject(text) {
+  let trimmed = text.trim();
+
+  if (trimmed.startsWith("```")) {
+    const lines = trimmed.split(/\r?\n/);
+    lines.shift();
+    if (lines.length > 0 && lines[lines.length - 1].trim().startsWith("```")) {
+      lines.pop();
+    }
+    trimmed = lines.join("\n").trim();
+  }
+
+  let value;
+  try {
+    value = JSON.parse(trimmed);
+  } catch {
+    return { ok: false, error: "Response is not valid JSON." };
+  }
+
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return { ok: false, error: "Response is not a JSON object." };
+  }
+
+  return { ok: true, value };
+}

package/src/lib/log.mjs

@@ -0,0 +1,44 @@
+// Lifecycle logging at operational boundaries (AGENTS.md logging guideline).
+// Every line is tagged with its level: "[agent-loop] <level>: <message>".
+// info and debug go to stdout, warn and error to stderr; debug is shown only when
+// the --verbose gate is on. Warn and error lines are length-bounded so untrusted
+// content (for example a model echo in a validation error) cannot flood a line.
+const MAX_LENGTH = 300;
+
+let verbose = false;
+let stderrOnly = false;
+
+export function setVerbose(value) {
+  verbose = Boolean(value);
+}
+
+/**
+ * Routes info and debug lines to stderr as well. The role subcommand must keep
+ * stdout reserved for its single JSON envelope, so it turns this on for its
+ * whole lifetime.
+ */
+export function setLogsToStderr(value) {
+  stderrOnly = Boolean(value);
+}
+
+function truncate(message) {
+  return message.length > MAX_LENGTH ? `${message.slice(0, MAX_LENGTH)}...` : message;
+}
+
+export function logDebug(message) {
+  if (verbose) {
+    (stderrOnly ? console.error : console.log)(`[agent-loop] debug: ${truncate(message)}`);
+  }
+}
+
+export function logInfo(message) {
+  (stderrOnly ? console.error : console.log)(`[agent-loop] info: ${truncate(message)}`);
+}
+
+export function logWarn(message) {
+  console.error(`[agent-loop] warn: ${truncate(message)}`);
+}
+
+export function logError(message) {
+  console.error(`[agent-loop] error: ${truncate(message)}`);
+}

package/src/lib/report.mjs

@@ -0,0 +1,89 @@
+// Parses the closing block that reportBlock (src/prompts/report.mjs) requires
+// from every child turn, plus the reviewer Verdict line. Both parse only the
+// final block, which starts at the last `Conclusion:` line, so labels or
+// verdicts in earlier prose can never produce a verdict.
+
+const REPORT_LABELS = [
+  ["conclusion", "Conclusion"],
+  ["why", "Why"],
+  ["blockers", "Blockers"],
+];
+
+/**
+ * The closing block: the lines from the last `Conclusion:` line to the end of
+ * the response, or null when the response has no `Conclusion:` line at all.
+ * @param {string} response
+ * @returns {string[] | null}
+ */
+function closingBlock(response) {
+  const lines = response.split(/\r?\n/);
+  let start = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^Conclusion:\s*/i.test(lines[i])) {
+      start = i;
+    }
+  }
+  return start === -1 ? null : lines.slice(start);
+}
+
+/**
+ * Extracts the closing block as `{ conclusion, why, blockers }`. Each label is
+ * matched case-insensitively at line start inside the closing block only; the
+ * last occurrence in that range wins. Returns null when the block or any of
+ * the three labels is missing.
+ * @param {string} response
+ * @returns {{ conclusion: string, why: string, blockers: string } | null}
+ */
+export function parseReportBlock(response) {
+  const block = closingBlock(response);
+  if (!block) {
+    return null;
+  }
+  const report = {};
+  for (const [key, label] of REPORT_LABELS) {
+    const match = lastLabeledLine(block, label);
+    if (!match) {
+      return null;
+    }
+    report[key] = match;
+  }
+  return report;
+}
+
+/**
+ * Extracts the reviewer verdict from a `Verdict:` line inside the closing
+ * block. The verdict word alone, the word closed by an optional sentence
+ * period, or the word followed by a punctuation separator, whitespace, and a
+ * clause, maps to that word. A clause that names either verdict as a whole word
+ * (for example `accept, reject`) maps to `unknown`, because it does not state
+ * one verdict. A verdict outside the block, or any other value (including a
+ * missing or malformed line), also maps to `unknown`; process success never
+ * implies acceptance.
+ * @param {string} response
+ * @returns {"accept" | "reject" | "unknown"}
+ */
+export function parseVerdict(response) {
+  const block = closingBlock(response);
+  const line = block ? lastLabeledLine(block, "Verdict") : null;
+  const value = line ? line.replace(/\.$/, "") : null;
+  const match = value ? value.match(/^(accept|reject)(?:\s*[—–:,.-]\s+(.*))?$/i) : null;
+  if (!match) {
+    return "unknown";
+  }
+  if (match[2] && /\b(accept|reject)\b/i.test(match[2])) {
+    return "unknown";
+  }
+  return match[1].toLowerCase();
+}
+
+function lastLabeledLine(lines, label) {
+  const pattern = new RegExp(`^${label}:\\s*(.*)$`, "i");
+  let last = null;
+  for (const line of lines) {
+    const match = line.match(pattern);
+    if (match) {
+      last = match[1].trim();
+    }
+  }
+  return last;
+}

package/src/lib/runstate.mjs

@@ -0,0 +1,207 @@
+// Lifecycle state file shared by the role subcommand (#55) and the parent
+// guard hook (#57). The state file lives at a fixed path derived from the
+// resolved work tree cwd, never passed as a flag; tests override the runs
+// root with AGENT_LOOP_RUNS_ROOT.
+import { createHash } from "node:crypto";
+import { mkdir, open, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { logWarn } from "./log.mjs";
+
+export const TERMINAL_LIFECYCLES = new Set(["halted", "finished", "aborted"]);
+
+/**
+ * Resolve the state paths for one run. `cwd` derives the per-work-tree state
+ * directory; `parentSession` derives the session index entry that the #57 hook
+ * reads back. Both are optional so a caller with only one of them still
+ * resolves the half it needs.
+ * @param {{ cwd?: string, parentSession?: string }} args
+ * @returns {{ root: string, stateDir?: string, stateFile?: string, lockFile?: string, sessionIndexFile?: string }}
+ */
+export function statePaths({ cwd, parentSession } = {}) {
+  const root = stateRoot();
+  const paths = { root };
+
+  if (cwd !== undefined) {
+    const stateDir = join(root, cwdHash(cwd));
+    paths.stateDir = stateDir;
+    paths.stateFile = join(stateDir, "state.json");
+    paths.lockFile = join(stateDir, "state.lock");
+  }
+
+  if (parentSession !== undefined) {
+    assertSessionId(parentSession);
+    paths.sessionIndexFile = join(root, "sessions", parentSession);
+  }
+
+  return paths;
+}
+
+function stateRoot() {
+  const override = process.env.AGENT_LOOP_RUNS_ROOT;
+  return override ? resolve(override) : join(tmpdir(), "agent-loops", "runs");
+}
+
+function cwdHash(cwd) {
+  return createHash("sha256").update(canonicalCwd(cwd)).digest("hex").slice(0, 12);
+}
+
+function canonicalCwd(cwd) {
+  const resolved = resolve(cwd);
+  // Windows drive letters compare case-insensitively in the filesystem but
+  // not in the hash; normalize the letter so `c:\repo` and `C:\repo` share one
+  // state directory.
+  return resolved.replace(/^[A-Za-z]:/, (drive) => drive.toLowerCase());
+}
+
+function assertSessionId(sessionId) {
+  if (!sessionId || /[\\/\0]/.test(sessionId) || sessionId === "." || sessionId === "..") {
+    throw new Error(`Invalid session id: ${JSON.stringify(sessionId ?? null)}`);
+  }
+}
+
+/**
+ * Reads the state file that the init call registered for a parent session id.
+ * Returns null when the session has no index entry or the file is unreadable
+ * as JSON; never throws on absence, so the #57 hook can treat it as unguarded.
+ */
+export async function readStateForSession(parentSession) {
+  const indexFile = statePaths({ parentSession }).sessionIndexFile;
+  let stateFile;
+  try {
+    stateFile = (await readFile(indexFile, "utf8")).trim();
+  } catch {
+    return null;
+  }
+  try {
+    return JSON.parse(await readFile(stateFile, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Exclusive access around one state-file operation. Creates `state.lock` with
+ * O_EXCL, treats an existing lock with a live owner pid as busy and a dead one
+ * as stale (removed with a warning, then retried). Returns a release function.
+ */
+export async function withStateLock(lockFile, fn) {
+  await mkdir(dirname(lockFile), { recursive: true });
+  await acquireLock(lockFile);
+  try {
+    return await fn();
+  } finally {
+    await rm(lockFile, { force: true });
+  }
+}
+
+async function acquireLock(lockFile, retry = true) {
+  try {
+    const handle = await open(lockFile, "wx");
+    try {
+      await handle.writeFile(
+        JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() }),
+        "utf8",
+      );
+    } finally {
+      await handle.close();
+    }
+    // The O_EXCL create above is the lock; the content write closes the
+    // reader-visible window. Contenders finding an unparseable lock fail
+    // closed below and never remove it while it is fresh.
+    return;
+  } catch (err) {
+    if (err.code !== "EEXIST") {
+      throw err;
+    }
+  }
+
+  const owner = await readLockOwner(lockFile);
+  if (owner && pidAlive(owner.pid)) {
+    throw new Error(
+      `State is locked by a live process (pid ${owner.pid}, started ${owner.startedAt ?? "unknown"}).`,
+    );
+  }
+
+  if (!owner && (await lockAgeMs(lockFile)) < STALE_LOCK_GRACE_MS) {
+    // Unparseable and fresh: the creator may still be between create and
+    // content write, so it is never treated as stale here.
+    throw new Error("State is locked (the lock file is not readable yet; retry shortly).");
+  }
+
+  if (!retry) {
+    throw new Error("State lock could not be acquired after stale removal.");
+  }
+
+  logWarn(`removing stale state lock (dead pid ${owner?.pid ?? "unknown"})`);
+  await rm(lockFile, { force: true });
+  return acquireLock(lockFile, false);
+}
+
+export function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+
+async function readLockOwner(lockFile) {
+  try {
+    const value = JSON.parse(await readFile(lockFile, "utf8"));
+    if (value === null || typeof value !== "object" || !Number.isInteger(value.pid)) {
+      return null;
+    }
+    return value;
+  } catch {
+    return null;
+  }
+}
+
+// An unparseable lock younger than this is assumed to be a contender still
+// between create and content write; only an older one is stale.
+export const STALE_LOCK_GRACE_MS = 60_000;
+
+async function lockAgeMs(lockFile) {
+  try {
+    const stats = await stat(lockFile);
+    return Date.now() - stats.mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Reads and parses the state file. Returns null when absent; a corrupt file
+ * throws so the caller exits instead of guessing the lifecycle.
+ */
+export async function readState(stateFile) {
+  let text;
+  try {
+    text = await readFile(stateFile, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return null;
+    }
+    throw err;
+  }
+  const value = JSON.parse(text);
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`State file is not a JSON object: ${stateFile}`);
+  }
+  return value;
+}
+
+export async function writeState(stateFile, state) {
+  const temp = `${stateFile}.${process.pid}.tmp`;
+  await writeFile(temp, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+  // Node rename replaces an existing destination on Windows and POSIX.
+  await rename(temp, stateFile);
+}
+
+export async function appendSessionIndex(sessionIndexFile, stateFile) {
+  // The index entry is overwritten by the next init call from the same session.
+  await mkdir(dirname(sessionIndexFile), { recursive: true });
+  return writeFile(sessionIndexFile, `${stateFile}\n`, "utf8");
+}