@andromarces/agent-loops 0.2.0

package/src/lib/snapshot.mjs

@@ -0,0 +1,231 @@
+import { createHash } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { execa } from "execa";
+import { logDebug, logError } from "./log.mjs";
+
+export class MutationError extends Error {
+  constructor(role, paths) {
+    super(`Mutation detected during ${role} turn: ${paths.join(", ")}`);
+    this.name = "MutationError";
+    this.role = role;
+    this.paths = paths;
+  }
+}
+
+// Snapshot failure: a turn's mutation state could not be determined, so no verdict exists.
+// Precedence note: if the agent turn was canceled (SIGINT) and the post-turn snapshot also fails,
+// SnapshotError wins and the cancellation is not preserved; the caller exits 1, not 130.
+export class SnapshotError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "SnapshotError";
+  }
+}
+
+export async function assertGitWorkTree(cwd) {
+  const result = await execa("git", ["rev-parse", "--is-inside-work-tree"], {
+    cwd,
+    reject: false,
+  });
+
+  if (result.exitCode !== 0 || result.stdout.trim() !== "true") {
+    throw new SnapshotError(`--cwd must be inside a Git work tree: ${cwd}`);
+  }
+}
+
+function sha256(data) {
+  return createHash("sha256").update(data).digest("hex");
+}
+
+// Returns null only for an absent or non-regular file; read errors other than ENOENT propagate.
+export async function sha256File(path) {
+  let s;
+  try {
+    s = await stat(path);
+  } catch (err) {
+    if (err.code === "ENOENT" || err.code === "EISDIR") {
+      return null;
+    }
+    throw err;
+  }
+  if (!s.isFile()) {
+    return null;
+  }
+  try {
+    const content = await readFile(path);
+    return sha256(content);
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      // Raced with deletion between stat and read; treat as absent.
+      return null;
+    }
+    throw err;
+  }
+}
+
+async function gitIn(cwd, args) {
+  const result = await execa("git", args, { cwd, reject: false });
+  if (result.exitCode !== 0) {
+    throw new SnapshotError(
+      `git ${args[0]} failed (exit ${result.exitCode}): ${result.stderr.trim()}`,
+    );
+  }
+  return result;
+}
+
+export async function snapshot(cwd) {
+  // git status/ls-files emit repository-root-relative paths, so run them at the root.
+  const rootResult = await execa("git", ["rev-parse", "--show-toplevel"], {
+    cwd,
+    reject: false,
+  });
+  if (rootResult.exitCode !== 0) {
+    throw new SnapshotError(`--cwd must be inside a Git work tree: ${cwd}`);
+  }
+  const root = rootResult.stdout.trim();
+
+  // 1. Work tree status
+  const statusResult = await gitIn(root, [
+    "status",
+    "--porcelain=v1",
+    "-z",
+    "--untracked-files=all",
+  ]);
+
+  const statusTokens = statusResult.stdout.split("\0");
+  const entries = [];
+
+  for (let i = 0; i < statusTokens.length; i++) {
+    const token = statusTokens[i];
+    if (!token) continue;
+    const status = token.slice(0, 2);
+    const filePath = token.slice(3);
+
+    // If rename/copy (status 'R' or 'C'), -z outputs <new-path>\0<old-path>\0.
+    // filePath is already <new-path>; consume <old-path> in nextToken so it is not processed as a file.
+    if (status.includes("R") || status.includes("C")) {
+      i++;
+    }
+
+    const fullPath = join(root, filePath);
+    let hash;
+    try {
+      hash = await sha256File(fullPath);
+    } catch (err) {
+      throw new SnapshotError(`failed to hash ${filePath}: ${err.message}`, { cause: err });
+    }
+    entries.push({ path: filePath, status, hash });
+  }
+
+  entries.sort((a, b) => a.path.localeCompare(b.path));
+
+  // 2. Index hash (whole repository, not just cwd)
+  const lsResult = await gitIn(root, ["ls-files", "--stage", "-z"]);
+  const indexHash = sha256(lsResult.stdout);
+
+  // 3. HEAD; exit 1 here means a repository without commits, so "unborn" is correct.
+  const headResult = await execa("git", ["rev-parse", "--verify", "-q", "HEAD"], {
+    cwd: root,
+    reject: false,
+  });
+  const head = headResult.exitCode === 0 ? headResult.stdout.trim() : "unborn";
+
+  return {
+    workTree: entries,
+    indexHash,
+    head,
+  };
+}
+
+/**
+ * Diff two snapshots. Returns the sorted changed work-tree paths, plus the
+ * sentinel entries `<index>` and `<HEAD>` when the index or HEAD changed.
+ * @param {ReturnType<typeof snapshot>} before
+ * @param {ReturnType<typeof snapshot>} after
+ * @returns {string[]}
+ */
+export function diffSnapshots(before, after) {
+  const changed = new Set();
+
+  const beforeMap = new Map(before.workTree.map((e) => [e.path, e]));
+  const afterMap = new Map(after.workTree.map((e) => [e.path, e]));
+
+  for (const [path, b] of beforeMap.entries()) {
+    const a = afterMap.get(path);
+    if (!a) {
+      // It was dirty and now it's not (e.g. reverted or staged/committed)
+      changed.add(path);
+    } else if (b.status !== a.status || b.hash !== a.hash) {
+      changed.add(path);
+    }
+  }
+
+  for (const [path] of afterMap.entries()) {
+    if (!beforeMap.has(path)) {
+      changed.add(path);
+    }
+  }
+
+  const result = Array.from(changed).sort();
+
+  if (before.indexHash !== after.indexHash) {
+    result.push("<index>");
+  }
+
+  if (before.head !== after.head) {
+    result.push("<HEAD>");
+  }
+
+  return result;
+}
+
+/**
+ * Run `fn()` and compare Git snapshots taken before and after.
+ * Throws `MutationError` when the diff is non-empty, even when `fn()` already
+ * failed: the mutation error wins over the wrapped error, which is discarded.
+ * @template T
+ * @param {string} cwd
+ * @param {string} role
+ * @param {() => Promise<T>} fn
+ * @returns {Promise<T>}
+ */
+export async function withMutationCheck(cwd, role, fn) {
+  const before = await snapshot(cwd);
+  logDebug(`snapshot before ${role} turn taken (${before.workTree.length} work tree entries)`);
+  let actionError = null;
+  let result;
+
+  try {
+    result = await fn();
+  } catch (err) {
+    actionError = err;
+  }
+
+  let after;
+  try {
+    after = await snapshot(cwd);
+  } catch (snapErr) {
+    // A failed post-turn snapshot wins over the agent error; the agent error rides as cause.
+    if (actionError) {
+      throw new SnapshotError(`post-turn snapshot failed during ${role} turn: ${snapErr.message}`, {
+        cause: actionError,
+      });
+    }
+    throw snapErr;
+  }
+  logDebug(`snapshot after ${role} turn taken (${after.workTree.length} work tree entries)`);
+
+  const diff = diffSnapshots(before, after);
+  if (diff.length > 0) {
+    const mutationError = new MutationError(role, diff);
+    logError(mutationError.message);
+    throw mutationError;
+  }
+
+  if (actionError) {
+    throw actionError;
+  }
+
+  return result;
+}

package/src/orchestrator.mjs

@@ -0,0 +1,54 @@
+import { validateAction } from "./contracts/orchestrator-action.mjs";
+import { logWarn } from "./lib/log.mjs";
+import { extractJsonObject } from "./lib/json.mjs";
+import { repairPrompt } from "./prompts/orchestrator.mjs";
+
+export class OrchestratorError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "OrchestratorError";
+  }
+}
+
+export async function decide({ agent, state, prompt, options = {} }) {
+  const { cwd, timeout, signal } = options;
+
+  async function executeTurn(turnPrompt) {
+    return agent.run(state, turnPrompt, {
+      cwd,
+      readOnly: true,
+      timeout,
+      signal,
+    });
+  }
+
+  function parseAndValidate(rawResponse) {
+    const extracted = extractJsonObject(rawResponse);
+    if (!extracted.ok) {
+      return { ok: false, error: extracted.error };
+    }
+    return validateAction(extracted.value);
+  }
+
+  // Attempt 1
+  const firstResponse = await executeTurn(prompt);
+  const firstValidation = parseAndValidate(firstResponse);
+
+  if (firstValidation.ok) {
+    return firstValidation.value;
+  }
+
+  // Repair turn
+  logWarn(`orchestrator action invalid; taking repair turn: ${firstValidation.error}`);
+  const repair = repairPrompt(firstValidation.error);
+  const repairResponse = await executeTurn(repair);
+  const repairValidation = parseAndValidate(repairResponse);
+
+  if (repairValidation.ok) {
+    return repairValidation.value;
+  }
+
+  throw new OrchestratorError(
+    `Orchestrator returned a malformed action after one repair turn: ${repairValidation.error}`,
+  );
+}

package/src/prompts/orchestrator.mjs

@@ -0,0 +1,73 @@
+// Shared rule source: docs/orchestrator-instructions.md states the role rules
+// for interactive parents (#56); this headless prompt states the same rules in
+// JSON-action form. Keep the two consistent when either changes.
+export function initialPrompt({ task, maxSteps }) {
+  return `
+You are the orchestrator in an automated multi-agent coding loop.
+Your role is to direct the workflow to complete the user task.
+You must NOT edit files, and you must NOT run agent CLIs or background processes directly.
+
+You have two child roles:
+- worker: Implements changes, runs checks and tests, and reports findings and progress.
+- reviewer: Read-only inspector. Inspects and assesses the repository state and verifications. The reviewer must not edit files.
+
+You have a maximum step budget of ${maxSteps} steps.
+A step is consumed only when you dispatch a child role (run_worker or run_reviewer).
+Actions that do NOT consume a step: finish, abort, or repair turns.
+
+Respond with one JSON object and nothing else. A \`\`\`json fence is accepted.
+Supported action formats:
+
+1. Dispatch worker:
+{"action": "run_worker", "prompt": "<instructions for worker>"}
+
+2. Dispatch reviewer:
+{"action": "run_reviewer", "prompt": "<instructions for reviewer>"}
+
+3. Finish when work is complete and verified:
+{"action": "finish", "summary": {"changed": "<summary>", "verified": "<summary>", "deferred": "<summary>", "notDone": "<summary>", "open": "<summary>"}}
+
+4. Abort if the task cannot proceed:
+{"action": "abort", "reason": "<explanation>"}
+
+The finish summary requires non-empty strings for all five keys: changed, verified, deferred, notDone, open.
+
+User Task:
+${task}
+`.trim();
+}
+
+export function resultPrompt({ result, stepsUsed, maxSteps }) {
+  const stepsRemaining = Math.max(0, maxSteps - stepsUsed);
+  const payload = {
+    role: result.role,
+    status: result.status,
+    ...(result.status === "ok" ? { response: result.response } : { error: result.error }),
+    stepsUsed,
+    stepsRemaining,
+  };
+
+  return `
+Role execution result:
+${JSON.stringify(payload, null, 2)}
+
+Choose the next action.
+Respond with one JSON object and nothing else. A \`\`\`json fence is accepted.
+Supported actions: run_worker, run_reviewer, finish, abort.
+`.trim();
+}
+
+export function repairPrompt(error) {
+  return `
+Your previous response could not be accepted due to the following validation error:
+${error}
+
+Respond with one valid JSON object and nothing else. A \`\`\`json fence is accepted.
+Supported action formats:
+
+1. {"action": "run_worker", "prompt": "<string>"}
+2. {"action": "run_reviewer", "prompt": "<string>"}
+3. {"action": "finish", "summary": {"changed": "<string>", "verified": "<string>", "deferred": "<string>", "notDone": "<string>", "open": "<string>"}}
+4. {"action": "abort", "reason": "<string>"}
+`.trim();
+}

package/src/prompts/report.mjs

@@ -0,0 +1,10 @@
+/**
+ * Closing block every child turn must end with. The orchestrator sees only the child's final
+ * response, so the block carries the reasoning and open items it would otherwise re-derive.
+ */
+export const reportBlock = `
+End your response with this block, kept short:
+Conclusion: one or two sentences.
+Why: the decisive evidence behind the conclusion.
+Blockers: anything unresolved that the next turn must know, or "none".
+`.trim();

package/src/prompts/reviewer.mjs

@@ -0,0 +1,17 @@
+import { reportBlock } from "./report.mjs";
+
+// Same closing block as reportBlock, with the verdict line inside it so the
+// model treats it as part of the mandatory block, not an optional extra.
+const reviewerReportBlock = `${reportBlock}
+Verdict: accept or reject. One word, nothing else on the line.`;
+
+export function reviewerPrompt(prompt) {
+  return `
+Do not implement, fix, edit, or change any file. Review, assess, and verify only. Live probes and read-only queries are authorized.
+
+${reviewerReportBlock}
+
+Instructions:
+${prompt}
+`.trim();
+}

package/src/prompts/worker.mjs

@@ -0,0 +1,21 @@
+import { reportBlock } from "./report.mjs";
+
+export function workerPrompt(prompt, firstTurn = false) {
+  if (!firstTurn) {
+    return prompt;
+  }
+
+  return `
+You are the implementation agent (worker) in an automated loop.
+Your role:
+- Implement the requested changes.
+- Run tests, checks, and verifications to confirm correctness.
+- Report what changed, what was verified, and state any disagreements with evidence.
+- You do NOT decide when the loop ends.
+
+${reportBlock}
+
+Instructions:
+${prompt}
+`.trim();
+}