@andromarces/agent-loops 0.2.0

package/docs/orchestrator-instructions.md

@@ -0,0 +1,166 @@
+# Orchestrator instructions (harness-neutral)
+
+You are the parent orchestrator for an `agent-loop role` run. Per-harness entry
+points (the Claude Code and Codex CLI skills, the OpenCode plugin command)
+include this file instead of copying it. The headless prompt in
+`src/prompts/orchestrator.mjs` states the same role rules in JSON-action form;
+this file is the source for shared rules.
+
+## Role
+
+- Delegate the task, track results, handle blockers, and report completion.
+- Never implement changes, never review code yourself, never run tests, never
+  open child transcripts.
+- Read only the JSON envelope the subcommand prints on stdout. Child stderr
+  logs and child response text beyond the envelope are not input.
+
+## Inputs to collect from the invocation
+
+Collect these before the first dispatch:
+
+- the task
+- worker CLI, model, and effort (`--worker`, `--worker-model`, `--worker-effort`)
+- reviewer CLI, model, and effort (`--reviewer`, `--reviewer-model`, `--reviewer-effort`)
+- mode: `work-first`, `review-first`, or `review-only` (`--mode`)
+- maximum steps (`--max-steps`)
+
+## Resolving the CLI
+
+The command blocks below call `agent-loop` directly. Install the CLI globally:
+
+```bash
+npm install -g @andromarces/agent-loops
+```
+
+From a clone, register the `bin` field globally instead. Add the pnpm global
+bin directory to PATH first:
+
+```bash
+pnpm setup   # restart the shell afterwards
+pnpm add -g .
+```
+
+pnpm v11 removed `pnpm link --global` and keeps global bins under `PNPM_HOME`;
+`pnpm add -g .` fails with `ERR_PNPM_GLOBAL_BIN_DIR_NOT_IN_PATH` until
+`pnpm setup` puts that directory on PATH. Without a global install, replace
+`agent-loop` with `node "<repo>/src/cli.mjs"` and quote the repository path so
+a path with spaces works, or run `pnpm agent-loop` from the repository root.
+
+## Starting a run
+
+The first dispatch carries the init flags, including `--parent-session` when
+the harness provides a session id:
+
+```bash
+printf '%s' "<first child prompt>" | agent-loop role dispatch \
+  --role <first role> \
+  --cwd "<work tree>" \
+  --task "<task>" \
+  --mode "<mode>" \
+  --parent-session "<parent session id>" \
+  --worker <cli> --worker-model <model> --worker-effort <level> \
+  --reviewer <cli> --reviewer-model <model> --reviewer-effort <level> \
+  --max-steps <count>
+```
+
+- The first role matches the mode: `worker` in `work-first` and `review-first`,
+  `reviewer` in `review-only`.
+- `--worker` is required in `work-first` and `review-first` and optional in
+  `review-only`, which never dispatches the worker. `--worker-model` and
+  `--worker-effort` are always optional, and require `--worker`. An OpenCode
+  `--<role>-effort` also requires an explicit `--<role>-model`.
+- Always pass `--cwd`. It defaults to the current directory, which for an
+  interactive parent is normally not the target work tree.
+- Pass the child prompt on stdin. No prompt files.
+- A second task in the same session starts a new run with a new init call, and
+  only after the previous run is terminal. The subcommand archives the previous
+  state file and rejects init over a non-terminal run.
+- Later dispatches read the configuration from the state file. Do not repeat
+  `--task` on a later dispatch: `--task` keys init detection, so a dispatch
+  that carries it while a run is active fails instead of continuing the run.
+  Repeating any other init flag with its current value is accepted; changing
+  one is rejected, so omit changed flags and never invent new values.
+
+## Dispatch
+
+```bash
+printf '%s' "<prompt>" | agent-loop role dispatch --role worker --cwd "<work tree>"
+printf '%s' "<prompt>" | agent-loop role dispatch --role reviewer --cwd "<work tree>"
+```
+
+Read the JSON envelope on stdout. Example reviewer envelope:
+
+```json
+{
+  "role": "reviewer",
+  "status": "ok",
+  "report": { "conclusion": "...", "why": "...", "blockers": "..." },
+  "verdict": "accept"
+}
+```
+
+- `status: "error"` carries `error`. Treat it as not accepted.
+- A reviewer envelope carries `verdict`: `accept`, `reject`, or `unknown` when
+  the required `Verdict:` line is missing or malformed. Treat `unknown` as not
+  accepted. Process success never implies acceptance.
+- When the closing block cannot be parsed, `report` is null and `raw` carries
+  the tail of the response. Treat a missing report as not accepted.
+
+## Loop policy
+
+- `work-first`: worker, reviewer, worker corrections, reviewer, until
+  `verdict: accept`.
+- `review-first`: reviewer first, then worker corrections and another review
+  if needed.
+- `review-only`: reviewer, then report. Findings alone never authorize edits;
+  the subcommand rejects worker dispatch in this mode.
+
+## Completion
+
+Completion is completion of the requested work, not code acceptance.
+
+- `work-first` and `review-first`: call `finish` after the reviewer returns
+  `verdict: accept` on the latest changed state and the report names the
+  checks that passed.
+- `review-only`: call `finish` after the reviewer report, whatever the
+  verdict. The summary records the verdict in `verified` and the findings in
+  `open`.
+
+## Finish output
+
+`finish` reads the summary as JSON on stdin and is accepted only from the
+`active` lifecycle. All five keys are required and carry the same keys as the
+orchestrator action contract (`validateAction`):
+
+```bash
+printf '%s' '{"changed":"...","verified":"...","deferred":"...","notDone":"...","open":"..."}' \
+  | agent-loop role finish --cwd "<work tree>"
+```
+
+## Blockers and terminal states
+
+- Blocker, `interrupted` lifecycle, or step limit with work remaining: call
+  `agent-loop role abort --cwd "<work tree>" --reason "<explanation>"` and
+  report the unresolved condition. Never repeat an uncertain turn without a
+  maintainer decision.
+- `halted` lifecycle (reviewer mutation or snapshot error): the run is already
+  terminal and the subcommand rejects further operations, including `abort`.
+  Report the failure and the modified paths from the envelope, then stop.
+- Every run ends in exactly one terminal lifecycle: `finished`, `aborted`, or
+  `halted`. The parent-edit guard (#57, Claude Code, Codex CLI, and OpenCode)
+  releases on any of them; any run without `--parent-session` keeps its parent
+  unguarded.
+
+## Recovery after compaction or restart
+
+Read the state file at
+`<runs root>/<sha256 of the --cwd, shortened>/state.json`, where the runs root
+is `<os tmpdir>/agent-loops/runs` by default and the `AGENT_LOOP_RUNS_ROOT`
+environment variable overrides it. The directory name is the first 12 hex
+characters of the sha256 of the resolved `--cwd`, with the Windows drive letter
+lowercased before hashing, so `c:\repo` and `C:\repo` share one directory.
+This state-file read is the one exception to the stdout-envelope rule. Honor
+the state file's `mode` and `lifecycle`, and continue from `stepsUsed` and
+`lastResult`. A resumed review-only task keeps its prohibition on worker
+dispatch. From `interrupted`, the parent aborts; only a maintainer may decide
+to resume with `dispatch --resume-interrupted`.

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@andromarces/agent-loops",
+  "version": "0.2.0",
+  "private": false,
+  "description": "Run a task loop across several CLI coding agents.",
+  "homepage": "https://github.com/andromarces/agent-loops#readme",
+  "bugs": {
+    "url": "https://github.com/andromarces/agent-loops/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andromarces/agent-loops.git"
+  },
+  "bin": {
+    "agent-loop": "./src/cli.mjs",
+    "agent-loop-copilot": "./src/entrypoints/copilot.mjs",
+    "agent-loops": "./src/cli.mjs"
+  },
+  "files": [
+    "src",
+    "docs/orchestrator-instructions.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "agent-loop": "node ./src/cli.mjs",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "lint": "oxlint",
+    "test": "vitest run",
+    "prepare": "node .husky/install.mjs",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "execa": "^10.0.1"
+  },
+  "devDependencies": {
+    "husky": "^9.1.7",
+    "lint-staged": "^17.5.1",
+    "oxfmt": "^0.70.0",
+    "oxlint": "^1.85.0",
+    "vitest": "^5.0.1"
+  },
+  "lint-staged": {
+    "*.{js,mjs,cjs,ts,mts,cts,jsx,tsx}": "oxfmt"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@12.4.1"
+}

package/src/agents/agy.mjs

@@ -0,0 +1,46 @@
+import { parseJson } from "../lib/json.mjs";
+import { exec } from "../lib/exec.mjs";
+
+export async function runAgy(state, prompt, options = {}) {
+  const { cwd, readOnly, timeout, signal, role } = options;
+  // --input-format text reads the prompt from stdin; -p is omitted because it consumes the next arg as the prompt value.
+  const args = ["--input-format", "text", "--output-format", "json"];
+
+  if (readOnly) {
+    args.push("--mode", "plan");
+  }
+
+  if (state.model) {
+    args.push("--model", state.model);
+  }
+
+  if (state.effort) {
+    args.push("--effort", state.effort);
+  }
+
+  if (state.sessionId) {
+    args.push("--conversation", state.sessionId);
+  }
+
+  const { stdout } = await exec("agy", args, { cwd, input: prompt, timeout, signal, role });
+  const result = parseJson(stdout, "Antigravity CLI");
+
+  if (!result.conversation_id) {
+    throw new Error("Antigravity did not return a conversation_id.");
+  }
+
+  state.sessionId = result.conversation_id;
+  setUsage(state, result);
+
+  return String(result.response ?? "").trim();
+}
+
+function setUsage(state, result) {
+  const usage = {};
+  if (result?.usage) usage.mainLoop = result.usage;
+  if (Object.keys(usage).length > 0) {
+    state.usage = usage;
+  } else {
+    delete state.usage;
+  }
+}

package/src/agents/claude.mjs

@@ -0,0 +1,85 @@
+import { parseJson } from "../lib/json.mjs";
+import { exec } from "../lib/exec.mjs";
+
+export async function runClaude(state, prompt, options = {}) {
+  const { cwd, readOnly, timeout, signal, role } = options;
+  const args = ["-p"];
+  const execOptions = { cwd, input: prompt, timeout, signal, role };
+
+  if (state.sessionId) {
+    args.push("--resume", state.sessionId);
+  }
+
+  if (readOnly) {
+    args.push("--permission-mode", "plan");
+    // Plan mode is a write guard here, not a planning workflow. Without this variable it
+    // delegates research to the built-in Explore and Plan subagents, which inherit the role
+    // model (Explore capped at Opus on the Claude API). Requires Claude Code v2.1.198+.
+    execOptions.env = { CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS: "1" };
+  }
+
+  if (state.model) {
+    args.push("--model", state.model);
+  }
+
+  if (state.effort) {
+    args.push("--effort", state.effort);
+  }
+
+  args.push("--output-format", "json");
+
+  let stdout;
+  try {
+    ({ stdout } = await exec("claude", args, execOptions));
+  } catch (err) {
+    // A non-zero exit can still carry a result event with usage. Expose it, then rethrow.
+    let failed;
+    try {
+      failed = JSON.parse(err?.stdout ?? "");
+    } catch {
+      failed = undefined;
+    }
+    setUsage(state, findResultEvent(failed));
+    throw err;
+  }
+  const parsed = parseJson(stdout, "Claude Code");
+
+  const sessionId = Array.isArray(parsed)
+    ? parsed.map((event) => event?.session_id).find(Boolean)
+    : parsed.session_id;
+
+  if (!sessionId) {
+    throw new Error("Claude Code did not return a session_id.");
+  }
+
+  state.sessionId = sessionId;
+  const resultEvent = findResultEvent(parsed);
+  setUsage(state, resultEvent);
+
+  return String(resultEvent?.result ?? "").trim();
+}
+
+function findResultEvent(parsed) {
+  if (Array.isArray(parsed)) {
+    return parsed.find((event) => event?.type === "result");
+  }
+  return parsed && typeof parsed === "object" ? parsed : undefined;
+}
+
+/**
+ * Sets `state.usage` from a result event, or removes it when the event carries no usage.
+ * `usage` covers the top-level loop only; `modelUsage` and `total_cost_usd` include subagents.
+ */
+function setUsage(state, resultEvent) {
+  const usage = {};
+  if (resultEvent?.modelUsage) usage.models = resultEvent.modelUsage;
+  if (resultEvent?.usage) usage.mainLoop = resultEvent.usage;
+  if (typeof resultEvent?.total_cost_usd === "number") {
+    usage.totalCostUsd = resultEvent.total_cost_usd;
+  }
+  if (Object.keys(usage).length > 0) {
+    state.usage = usage;
+  } else {
+    delete state.usage;
+  }
+}

package/src/agents/codex.mjs

@@ -0,0 +1,73 @@
+import { parseJsonLines } from "../lib/json.mjs";
+import { exec } from "../lib/exec.mjs";
+
+export async function runCodex(state, prompt, options = {}) {
+  const { cwd, readOnly, timeout, signal, role } = options;
+  const configArgs = [];
+
+  if (readOnly) {
+    configArgs.push("-c", 'sandbox_mode="read-only"');
+  }
+
+  const modelArgs = [];
+  if (state.model) {
+    modelArgs.push("-m", state.model);
+  }
+
+  if (state.effort) {
+    modelArgs.push("-c", `model_reasoning_effort=${state.effort}`);
+  }
+
+  let args;
+  if (state.sessionId) {
+    args = ["exec", "resume", state.sessionId, ...configArgs, "--json", ...modelArgs, "-"];
+  } else {
+    args = ["exec", ...configArgs, "--json", ...modelArgs];
+  }
+
+  const { stdout } = await exec("codex", args, { cwd, input: prompt, timeout, signal, role });
+  const events = parseJsonLines(stdout);
+
+  const started = events.find((event) => event.type === "thread.started");
+  const returnedId = started?.thread_id;
+
+  if (!returnedId) {
+    throw new Error("Codex did not return a thread ID.");
+  }
+
+  if (state.sessionId && returnedId !== state.sessionId) {
+    throw new Error(
+      [
+        "Codex did not resume the expected thread.",
+        `Expected: ${state.sessionId}`,
+        `Received: ${returnedId}`,
+      ].join("\n"),
+    );
+  }
+
+  state.sessionId = returnedId;
+  setUsage(
+    state,
+    events.find((event) => event.type === "turn.completed"),
+  );
+
+  const messages = events
+    .filter((event) => event.type === "item.completed" && event.item?.type === "agent_message")
+    .map((event) => event.item.text)
+    .filter(Boolean);
+
+  if (messages.length === 0) {
+    throw new Error("Codex did not return an agent message.");
+  }
+
+  return String(messages.at(-1)).trim();
+}
+
+/** Sets top-level turn usage, or removes stale usage when Codex omits it. */
+function setUsage(state, completedTurn) {
+  if (completedTurn?.usage) {
+    state.usage = { mainLoop: completedTurn.usage };
+  } else {
+    delete state.usage;
+  }
+}

package/src/agents/copilot.mjs

@@ -0,0 +1,86 @@
+import { randomUUID } from "node:crypto";
+import { parseJsonLines } from "../lib/json.mjs";
+import { exec } from "../lib/exec.mjs";
+
+export async function runCopilot(state, prompt, options = {}) {
+  const { cwd, readOnly, timeout, signal, role } = options;
+  const requestedSessionId = state.sessionId;
+
+  if (!state.sessionId) {
+    state.sessionId = randomUUID();
+  }
+
+  const args = ["--session-id", state.sessionId, "-s", "--no-ask-user", "--output-format", "json"];
+
+  if (readOnly) {
+    args.push("--deny-tool", "write");
+  }
+
+  if (state.model) {
+    args.push("--model", state.model);
+  }
+
+  if (state.effort) {
+    args.push("--reasoning-effort", state.effort);
+  }
+
+  let stdout;
+  try {
+    ({ stdout } = await exec("copilot", args, { cwd, input: prompt, timeout, signal, role }));
+  } catch (error) {
+    const failed = parseJsonLines(error?.stdout ?? "");
+    setUsage(state, findResultEvent(failed));
+    throw error;
+  }
+
+  const events = parseJsonLines(stdout);
+  const resultEvent = findResultEvent(events);
+  setUsage(state, resultEvent);
+
+  const returnedId = resultEvent?.sessionId ?? resultEvent?.session_id;
+  if (!returnedId) {
+    throw new Error("Copilot did not return a session ID.");
+  }
+
+  if (requestedSessionId && requestedSessionId !== returnedId) {
+    throw new Error(
+      [
+        "Copilot did not resume the expected session.",
+        `Expected: ${requestedSessionId}`,
+        `Received: ${returnedId}`,
+      ].join("\n"),
+    );
+  }
+
+  state.sessionId = returnedId;
+
+  const message = events
+    .filter((event) => event.type === "assistant.message")
+    .map((event) => readAssistantMessage(event))
+    .filter(Boolean)
+    .at(-1);
+
+  if (!message) {
+    throw new Error("Copilot did not return response text.");
+  }
+
+  return String(message).trim();
+}
+
+function findResultEvent(events) {
+  return events.filter((event) => event?.type === "result").at(-1);
+}
+
+function readAssistantMessage(event) {
+  const content = event?.data?.content;
+  return typeof content === "string" ? content : "";
+}
+
+function setUsage(state, resultEvent) {
+  if (resultEvent && resultEvent.usage && typeof resultEvent.usage === "object") {
+    state.usage = { mainLoop: resultEvent.usage };
+    return;
+  }
+
+  delete state.usage;
+}

package/src/agents/index.mjs

@@ -0,0 +1,37 @@
+import { runClaude } from "./claude.mjs";
+import { runCodex } from "./codex.mjs";
+import { runAgy } from "./agy.mjs";
+import { runOpenCode } from "./opencode.mjs";
+import { runCopilot } from "./copilot.mjs";
+
+export function normalizeAgent(kind) {
+  return kind === "antigravity" ? "agy" : kind;
+}
+
+/**
+ * Adapter registry. Each adapter implements `run(state, prompt, options) -> string`:
+ * it runs one turn of the CLI and returns the response text, and it mutates
+ * `state.sessionId` to hold the persistent session id used for resume.
+ * An adapter may set `state.usage` for the turn it just completed; the runtime
+ * consumes and removes it after every call. Adapters that expose no usage leave it unset.
+ */
+export const defaultAgents = {
+  claude: { run: runClaude },
+  codex: { run: runCodex },
+  agy: { run: runAgy },
+  opencode: { run: runOpenCode },
+  copilot: { run: runCopilot },
+};
+
+export const supportedAgents = new Set([...Object.keys(defaultAgents), "antigravity"]);
+
+export async function runAgent(state, prompt, options = {}, agents = defaultAgents) {
+  const kind = normalizeAgent(state.kind);
+  const adapter = agents[kind];
+
+  if (!adapter || typeof adapter.run !== "function") {
+    throw new Error(`Unsupported agent: ${state.kind}`);
+  }
+
+  return adapter.run(state, prompt, options);
+}