@andromarces/agent-loops 0.2.0

package/src/agents/opencode.mjs

@@ -0,0 +1,152 @@
+import { parseJsonLines } from "../lib/json.mjs";
+import { exec } from "../lib/exec.mjs";
+import { logInfo } from "../lib/log.mjs";
+
+// The built-in plan agent can launch explore and general subagents through the `subagent`
+// action. They inherit the session model, so a read-only turn spends the role model budget
+// invisibly. Deny the action for the read-only turn only; see the README.
+// A global permissions allow can resolve after the plan agent's `edit` deny and cancel it, so
+// deny `edit` here too. Shell stays available for read-only commands such as `git diff`.
+const READONLY_CONFIG =
+  '{"permissions":[{"action":"subagent","resource":"*","effect":"deny"},{"action":"edit","resource":"*","effect":"deny"}]}';
+
+export async function runOpenCode(state, prompt, options = {}) {
+  const { cwd, readOnly, timeout, signal, role } = options;
+  const args = ["run", "--standalone", "--format", "json"];
+  const execOptions = { cwd, input: prompt, timeout, signal, role };
+
+  if (state.sessionId) {
+    args.push("--session", state.sessionId);
+  }
+
+  if (readOnly) {
+    args.push("--agent", "plan");
+    execOptions.env = { OPENCODE_CONFIG_CONTENT: READONLY_CONFIG };
+  }
+
+  // Argument validation rejects an effort without a model; this guards a direct adapter call.
+  if (state.effort && !state.model) {
+    throw new Error(`opencode effort requires ${role ? `--${role}-model` : "an explicit model"}.`);
+  }
+
+  // state holds the requested model and effort, so null means the caller named nothing.
+  if (state.model) {
+    const resolved = state.effort ? `${state.model}#${state.effort}` : state.model;
+    logInfo(`opencode effective model: ${resolved}`);
+    args.push("--model", resolved);
+  } else {
+    // No --model: OpenCode selects its own default, which the JSON stream does not name.
+    logInfo(
+      "opencode model: OpenCode selects its CLI default; the OpenCode session metadata records the model that ran.",
+    );
+  }
+
+  let stdout;
+  try {
+    ({ stdout } = await exec("opencode", args, execOptions));
+  } catch (err) {
+    // A non-zero exit can still carry completed-step usage. Expose it, then rethrow.
+    setUsage(state, parseJsonLines(err?.stdout ?? ""));
+    throw err;
+  }
+
+  const events = parseJsonLines(stdout);
+
+  const sessionId = events.map((event) => event.sessionID).find(Boolean);
+
+  if (!sessionId) {
+    throw new Error("opencode did not return a session ID.");
+  }
+
+  if (state.sessionId && state.sessionId !== sessionId) {
+    throw new Error(
+      [
+        `opencode did not resume the expected session.`,
+        `Expected: ${state.sessionId}`,
+        `Received: ${sessionId}`,
+      ].join("\n"),
+    );
+  }
+
+  state.sessionId = sessionId;
+
+  // Record usage before the error check so a turn that failed after completing steps still reports
+  // what it spent, matching the Claude adapter and the runtime's error invocation event.
+  setUsage(state, events);
+
+  // Defense-in-depth: if the CLI ever exits 0 with an error event, surface its detail instead of
+  // falling through to the missing-text error. The session is recorded first, as it is on any turn.
+  const errorEvent = events.find((event) => event.type === "error");
+
+  if (errorEvent) {
+    throw new Error(`opencode returned an error event: ${describeError(errorEvent.error)}`);
+  }
+
+  const text = events
+    .filter((event) => event.type === "text" && typeof event.part?.text === "string")
+    .map((event) => event.part.text)
+    .join("");
+
+  if (!text.trim()) {
+    throw new Error("opencode did not return response text.");
+  }
+
+  return text.trim();
+}
+
+/**
+ * Sets `state.usage` from the `step_finish` parts of the stream, or removes it when the stream
+ * carries none. Each completed step emits one `step_finish` part with `tokens` and `cost`, so
+ * both fields sum across steps. No event names the model, so `models` is omitted.
+ */
+function setUsage(state, events) {
+  const tokens = { input: 0, output: 0, reasoning: 0, cache: { read: 0, write: 0 } };
+  let cost = 0;
+  let hasTokens = false;
+  let hasCost = false;
+
+  for (const event of events) {
+    if (event.type !== "step_finish") {
+      continue;
+    }
+
+    const part = event.part ?? {};
+
+    if (part.tokens && typeof part.tokens === "object") {
+      hasTokens = true;
+      tokens.input += part.tokens.input ?? 0;
+      tokens.output += part.tokens.output ?? 0;
+      tokens.reasoning += part.tokens.reasoning ?? 0;
+      tokens.cache.read += part.tokens.cache?.read ?? 0;
+      tokens.cache.write += part.tokens.cache?.write ?? 0;
+    }
+
+    if (typeof part.cost === "number") {
+      hasCost = true;
+      cost += part.cost;
+    }
+  }
+
+  const usage = {};
+  if (hasTokens) usage.mainLoop = tokens;
+  if (hasCost) usage.totalCostUsd = cost;
+
+  if (Object.keys(usage).length > 0) {
+    state.usage = usage;
+  } else {
+    delete state.usage;
+  }
+}
+
+/**
+ * Formats an OpenCode error event payload for the thrown message.
+ * The payload carries `{ type, message, status }`; any field can be absent.
+ */
+function describeError(error) {
+  if (!error || typeof error !== "object") {
+    return "unknown error";
+  }
+
+  const detail = [error.type, error.message].filter(Boolean).join(": ") || "unknown error";
+  return error.status == null ? detail : `${detail} (status ${error.status})`;
+}

package/src/cli.mjs

@@ -0,0 +1,338 @@
+#!/usr/bin/env node
+
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { defaultAgents, normalizeAgent, supportedAgents } from "./agents/index.mjs";
+import {
+  assertOpenCodeOptions,
+  readArgValue,
+  readNonNegativeInt,
+  readPositiveInt,
+} from "./lib/args.mjs";
+import { isEntryPoint } from "./lib/entrypoint.mjs";
+import { setVerbose } from "./lib/log.mjs";
+import { assertGitWorkTree } from "./lib/snapshot.mjs";
+import { runLoop } from "./runtime.mjs";
+import { main as runRoleMain } from "./role.mjs";
+
+const ROLES = ["orchestrator", "worker", "reviewer"];
+
+export function parseArgs(argv) {
+  const options = {
+    cwd: process.cwd(),
+    task: null,
+    maxSteps: 20,
+    timeout: 3600,
+    transcript: null,
+    verbose: false,
+  };
+  for (const role of ROLES) {
+    options[role] = null;
+    options[`${role}Model`] = null;
+    options[`${role}Effort`] = null;
+  }
+
+  const readValue = (flag, index) => readArgValue(argv, flag, index);
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+
+    let matched = false;
+    for (const role of ROLES) {
+      if (arg === `--${role}`) {
+        options[role] = readValue(arg, ++i);
+        matched = true;
+      } else if (arg === `--${role}-model`) {
+        options[`${role}Model`] = readValue(arg, ++i);
+        matched = true;
+      } else if (arg === `--${role}-effort`) {
+        options[`${role}Effort`] = readValue(arg, ++i);
+        matched = true;
+      }
+      if (matched) break;
+    }
+    if (matched) continue;
+
+    switch (arg) {
+      case "--cwd":
+        options.cwd = resolve(readValue(arg, ++i));
+        break;
+
+      case "--task":
+        options.task = readValue(arg, ++i);
+        break;
+
+      case "--max-steps":
+        options.maxSteps = readPositiveInt("--max-steps", readValue("--max-steps", ++i));
+        break;
+
+      case "--timeout": {
+        const seconds = readNonNegativeInt("--timeout", readValue("--timeout", ++i));
+        options.timeout = seconds === 0 ? null : seconds;
+        break;
+      }
+
+      case "--transcript":
+        options.transcript = resolve(readValue(arg, ++i));
+        break;
+
+      case "--verbose":
+        options.verbose = true;
+        break;
+
+      case "--help":
+      case "-h":
+        printHelp();
+        process.exit(0);
+        break;
+
+      default:
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  for (const role of ROLES) {
+    if (!options[role]) {
+      throw new Error(`Missing required --${role}.`);
+    }
+    if (!supportedAgents.has(options[role])) {
+      throw new Error(`Unsupported ${role}: ${options[role]}`);
+    }
+  }
+
+  for (const role of ROLES) {
+    assertOpenCodeOptions(role, options[role], options[`${role}Model`], options[`${role}Effort`]);
+  }
+  if (options.task === null || options.task === undefined || String(options.task).trim() === "") {
+    throw new Error(
+      'Missing required --task. Provide the task, for example --task "Implement the change."',
+    );
+  }
+
+  return options;
+}
+
+function printHelp() {
+  console.log(
+    `
+Usage:
+
+  agent-loop \\
+    --orchestrator codex \\
+    --worker claude \\
+    --reviewer agy \\
+    --task "Implement the change."
+
+  agent-loop role dispatch --role worker --prompt-file prompt.txt
+
+The orchestrator selects actions (run_worker, run_reviewer, finish, abort).
+The runtime enforces step limits and mutation boundaries.
+
+Subcommands:
+
+  agent-loop role               Run a single worker or reviewer turn, or finish/abort
+                                a run, from a lifecycle state file (see below). One JSON
+                                object on stdout; logs on stderr.
+
+Role operations:
+
+  dispatch (default)            Run one --role turn for the run state at --cwd.
+  finish                        End the run; the five-key summary arrives as JSON on stdin.
+  abort                         End the run with --reason.
+
+Role flags:
+
+  --role worker|reviewer        Role to dispatch. Required for dispatch.
+  --cwd <directory>             Target work tree. Defaults to the current directory.
+  --task / --mode / --parent-session / --worker* / --reviewer* / --max-steps / --timeout
+                                First (init) call only. Later calls read these from the
+                                state file and reject any attempt to change them.
+  --prompt-file <path>          Prompt source. Default is stdin.
+  --transcript <file>           Append invocation and result events (JSON lines).
+  --resume-interrupted           Explicitly continue after an uncertain previous turn.
+
+Options:
+
+  --orchestrator <agent>        Agent that directs the loop. Required.
+  --worker <agent>              Agent that implements changes. Required.
+  --reviewer <agent>            Agent that reviews the repository (read-only). Required.
+  --orchestrator-model <model>  Model passed to the orchestrator CLI. Optional.
+  --orchestrator-effort <level> Thinking effort passed to the orchestrator CLI. Optional.
+  --worker-model <model>        Model passed to the worker CLI. Optional.
+  --worker-effort <level>       Thinking effort passed to the worker CLI. Optional.
+  --reviewer-model <model>      Model passed to the reviewer CLI. Optional.
+  --reviewer-effort <level>     Thinking effort passed to the reviewer CLI. Optional.
+
+  Model and effort flags record what the caller requested. With opencode and no
+  --<role>-model, the adapter passes no --model and OpenCode selects its own
+  default, which varies by machine. An explicit --<role>-model passes through,
+  and --<role>-effort applies to it as <model>#<effort>. An effort without a
+  model is rejected.
+
+  --cwd <directory>             Working directory for the agents. Must be inside a Git work tree. Defaults to current directory.
+  --task <text>                 Task description. Required.
+  --max-steps <count>           Maximum child steps. Defaults to 20.
+  --timeout <seconds>           Timeout per agent invocation. Defaults to 3600. 0 disables the bound.
+  --transcript <file>           Record execution transcript to a JSON file.
+  --verbose                     Enable debug-level lifecycle logging, including snapshot activity.
+  -h, --help                    Show help.
+
+Environment:
+
+  The loop spawns each agent CLI directly, without a shell. Agents inherit the environment of the process that launched the loop. Start the loop from a shell where direnv or a similar tool already exported the required variables.
+
+Agents:
+
+  claude
+  codex
+  agy
+  antigravity
+  opencode
+  copilot
+`.trim(),
+  );
+}
+
+function formatSummary(summary) {
+  return [
+    `Changed: ${summary.changed}`,
+    `Verified: ${summary.verified}`,
+    `Deferred: ${summary.deferred}`,
+    `Not done: ${summary.notDone}`,
+    `Open: ${summary.open}`,
+  ].join("\n");
+}
+
+export async function main(argv = process.argv.slice(2), agents = defaultAgents) {
+  if (argv[0] === "role") {
+    await runRoleMain(argv.slice(1), { agents });
+    return;
+  }
+
+  let options;
+  try {
+    options = parseArgs(argv);
+  } catch (err) {
+    console.error(`\n${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  setVerbose(options.verbose);
+
+  const events = [];
+  const roles = {};
+  for (const role of ROLES) {
+    roles[role] = {
+      kind: normalizeAgent(options[role]),
+      model: options[`${role}Model`],
+      effort: options[`${role}Effort`],
+      sessionId: null,
+    };
+  }
+  const transcriptData = {
+    task: options.task,
+    cwd: options.cwd,
+    options: {
+      maxSteps: options.maxSteps,
+      timeout: options.timeout,
+    },
+    roles,
+    events,
+    exitCode: 1,
+    error: null,
+  };
+
+  const writeTranscript = async () => {
+    if (!options.transcript) return;
+    try {
+      await writeFile(options.transcript, JSON.stringify(transcriptData, null, 2), "utf8");
+    } catch (err) {
+      console.error(`Warning: Failed to write transcript to ${options.transcript}: ${err.message}`);
+    }
+  };
+
+  const finish = async ({ exitCode, error }) => {
+    transcriptData.exitCode = exitCode;
+    transcriptData.error = error ? (error.message ?? String(error)) : null;
+    await writeTranscript();
+    if (error) {
+      console.error(`\n${error.message ?? error}`);
+    }
+    process.exitCode = exitCode;
+  };
+
+  const controller = new AbortController();
+  const onSigInt = () => {
+    controller.abort();
+  };
+  process.once("SIGINT", onSigInt);
+
+  try {
+    try {
+      await assertGitWorkTree(options.cwd);
+    } catch (err) {
+      await finish({ exitCode: 1, error: err });
+      return;
+    }
+
+    const onEvent = (event) => {
+      if (options.transcript) {
+        events.push({
+          ...event,
+          at: new Date().toISOString(),
+        });
+      }
+
+      if (event.type === "action") {
+        console.log("\n===== ORCHESTRATOR =====\n");
+        console.log(JSON.stringify(event.action, null, 2));
+      } else if (event.type === "result") {
+        const banner =
+          event.role === "worker" ? `WORKER ${event.stepsUsed}` : `REVIEWER ${event.stepsUsed}`;
+        console.log(`\n===== ${banner} =====\n`);
+        if (event.result.status === "ok") {
+          console.log(event.result.response);
+        } else {
+          console.log(`Error: ${event.result.error}`);
+        }
+      }
+    };
+
+    try {
+      const result = await runLoop({
+        task: options.task,
+        cwd: options.cwd,
+        maxSteps: options.maxSteps,
+        timeout: options.timeout,
+        signal: controller.signal,
+        roles: transcriptData.roles,
+        agents,
+        onEvent,
+      });
+
+      if (result.exitCode === 0) {
+        console.log("\n===== SUMMARY =====\n");
+        console.log(formatSummary(result.summary));
+        await finish({ exitCode: 0, error: null });
+      } else {
+        await finish({ exitCode: result.exitCode, error: new Error(result.reason) });
+      }
+    } catch (err) {
+      if (err?.isCanceled) {
+        await finish({ exitCode: 130, error: new Error("Interrupted by SIGINT") });
+      } else {
+        await finish({ exitCode: 1, error: err });
+      }
+    }
+  } finally {
+    process.removeListener("SIGINT", onSigInt);
+  }
+}
+
+if (isEntryPoint(import.meta.filename)) {
+  main().catch((error) => {
+    console.error(`\n${error.stack ?? error.message ?? error}`);
+    process.exitCode = 1;
+  });
+}

package/src/contracts/orchestrator-action.mjs

@@ -0,0 +1,74 @@
+const SUMMARY_KEYS = ["changed", "verified", "deferred", "notDone", "open"];
+
+export function validateAction(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return { ok: false, error: "Action must be an object." };
+  }
+
+  const { action } = value;
+
+  // The case labels are the single source of truth for the supported action set:
+  // any action without a branch falls to `default` and is rejected, so the
+  // repair turn in decide() runs instead of a TypeError on an undefined result.
+  switch (action) {
+    case "run_worker":
+    case "run_reviewer": {
+      if (typeof value.prompt !== "string" || value.prompt.trim() === "") {
+        return { ok: false, error: `${action} requires a non-empty string prompt.` };
+      }
+      return {
+        ok: true,
+        value: {
+          action,
+          prompt: value.prompt.trim(),
+        },
+      };
+    }
+
+    case "finish": {
+      if (
+        value.summary === null ||
+        typeof value.summary !== "object" ||
+        Array.isArray(value.summary)
+      ) {
+        return { ok: false, error: "finish requires a summary object." };
+      }
+
+      const summary = {};
+      for (const key of SUMMARY_KEYS) {
+        const fieldVal = value.summary[key];
+        if (typeof fieldVal !== "string" || fieldVal.trim() === "") {
+          return {
+            ok: false,
+            error: `finish summary requires a non-empty string for ${key}.`,
+          };
+        }
+        summary[key] = fieldVal.trim();
+      }
+
+      return {
+        ok: true,
+        value: {
+          action: "finish",
+          summary,
+        },
+      };
+    }
+
+    case "abort": {
+      if (typeof value.reason !== "string" || value.reason.trim() === "") {
+        return { ok: false, error: "abort requires a non-empty string reason." };
+      }
+      return {
+        ok: true,
+        value: {
+          action: "abort",
+          reason: value.reason.trim(),
+        },
+      };
+    }
+
+    default:
+      return { ok: false, error: `Unsupported action: ${action}` };
+  }
+}

package/src/entrypoints/copilot.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execa } from "execa";
+import { isEntryPoint } from "../lib/entrypoint.mjs";
+
+// Resolve the shipped instructions relative to this file, so the launcher works
+// from any directory, not only from a clone of this repository. The file lives
+// outside the session workspace, so the invocation grants Copilot access to its
+// directory with --add-dir.
+const INSTRUCTIONS_DIR = fileURLToPath(new URL("../../docs", import.meta.url));
+const INSTRUCTIONS_PATH = join(INSTRUCTIONS_DIR, "orchestrator-instructions.md");
+
+const INSTRUCTIONS = (sessionId, task) =>
+  [
+    `Read \`${INSTRUCTIONS_PATH}\` and follow it for this request.`,
+    "The task and role settings are:",
+    task,
+    `This Copilot CLI session id is \`${sessionId}\`. Pass it as \`--parent-session\` on the init dispatch call.`,
+  ].join("\n\n");
+
+export function buildCopilotInvocation(task, sessionId) {
+  const normalizedTask = String(task ?? "").trim();
+  if (!normalizedTask) {
+    throw new Error("A task and role settings prompt is required.");
+  }
+  if (typeof sessionId !== "string" || sessionId.trim() === "") {
+    throw new Error("A Copilot CLI session id is required.");
+  }
+  return {
+    command: "copilot",
+    args: [
+      "--session-id",
+      sessionId,
+      "--add-dir",
+      INSTRUCTIONS_DIR,
+      "--interactive",
+      INSTRUCTIONS(sessionId, normalizedTask),
+    ],
+  };
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const task = argv.join(" ").trim();
+  const invocation = buildCopilotInvocation(task, randomUUID());
+  await execa(invocation.command, invocation.args, { stdio: "inherit" });
+}
+
+if (isEntryPoint(import.meta.filename)) {
+  main().catch((error) => {
+    const message = String(error?.shortMessage ?? error?.message ?? error).split("\n", 1)[0];
+    console.error(`agent-loop-copilot: ${message}`);
+    process.exitCode = 1;
+  });
+}

package/src/hook/copilot-parent-guard.mjs

@@ -0,0 +1,35 @@
+// GitHub Copilot CLI PreToolUse hook for the parent-edit guard. Copilot's
+// PascalCase event payload uses `session_id`, and its command-hook decision is
+// a flat permissionDecision object rather than Claude's hookSpecificOutput.
+// Fail-open by design: malformed input and lookup failures deny nothing.
+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({
+          permissionDecision: "deny",
+          permissionDecisionReason: verdict.reason,
+        }),
+      );
+    }
+  } catch {
+    // A failed lookup denies nothing: the guard never blocks on its own error.
+  }
+}

package/src/hook/decision.mjs

@@ -0,0 +1,27 @@
+// Decision logic for the #57 parent guard. The Claude Code PreToolUse hook
+// denies file-edit tools only when the hook session id matches `parentSession`
+// in the state file registered for that session; every other session, every
+// terminal lifecycle, and every absent or corrupt record allows the call.
+// Fail-open by design: the guard is optional defense for the prompt-only
+// parent rule, so unknown records never block a tool call.
+import { TERMINAL_LIFECYCLES, readStateForSession } from "../lib/runstate.mjs";
+
+export const GUARD_DENY_REASON =
+  "agent-loop orchestrator mode: this parent session has an active run. " +
+  "The parent never edits files. Delegate edits to the worker through " +
+  "'agent-loop role dispatch'; run 'agent-loop role finish' or 'abort' to " +
+  "release the guard.";
+
+/**
+ * Decides whether one tool call from one session is denied.
+ * @param {string} sessionId session id from the hook input
+ * @param {{ lookup?: typeof readStateForSession }} deps
+ * @returns {Promise<{ decision: "deny", reason: string } | { decision: "allow" }>}
+ */
+export async function decideParentGuard(sessionId, { lookup = readStateForSession } = {}) {
+  const state = await lookup(sessionId);
+  if (!state || state.parentSession !== sessionId || TERMINAL_LIFECYCLES.has(state.lifecycle)) {
+    return { decision: "allow" };
+  }
+  return { decision: "deny", reason: GUARD_DENY_REASON };
+}