@andromarces/agent-loops 0.2.1 → 0.3.0

package/src/agents/opencode.mjs

@@ -1,6 +1,7 @@
 import { parseJsonLines } from "../lib/json.mjs";
 import { exec } from "../lib/exec.mjs";
 import { logInfo } from "../lib/log.mjs";
+import { resumeMismatchError } from "./shared.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
@@ -59,13 +60,7 @@ export async function runOpenCode(state, prompt, options = {}) {
   }
 
   if (state.sessionId && state.sessionId !== sessionId) {
-    throw new Error(
-      [
-        `opencode did not resume the expected session.`,
-        `Expected: ${state.sessionId}`,
-        `Received: ${sessionId}`,
-      ].join("\n"),
-    );
+    throw resumeMismatchError("opencode", "session", state.sessionId, sessionId);
   }
 
   state.sessionId = sessionId;

package/src/agents/shared.mjs

@@ -0,0 +1,29 @@
+/**
+ * Sets `state.usage.mainLoop` from one turn's usage, or removes `state.usage` when
+ * the CLI reported none, so a turn that omits usage leaves no stale value behind.
+ * Any truthy value counts as usage; a caller with a narrower rule passes a filtered value.
+ */
+export function setMainLoopUsage(state, usage) {
+  if (usage) {
+    state.usage = { mainLoop: usage };
+  } else {
+    delete state.usage;
+  }
+}
+
+/**
+ * Builds the error for a resumed CLI that returned a different session id.
+ * @param {string} agent display name of the adapter, for example `Codex`
+ * @param {string} idLabel name of the id in that CLI, for example `thread` or `session`
+ * @param {string} expected session id the caller asked the CLI to resume
+ * @param {string} received session id the CLI returned
+ */
+export function resumeMismatchError(agent, idLabel, expected, received) {
+  return new Error(
+    [
+      `${agent} did not resume the expected ${idLabel}.`,
+      `Expected: ${expected}`,
+      `Received: ${received}`,
+    ].join("\n"),
+  );
+}

package/src/cli.mjs

@@ -4,25 +4,34 @@ import { writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { defaultAgents, normalizeAgent, supportedAgents } from "./agents/index.mjs";
 import {
+  DEFAULT_MAX_STEPS,
+  DEFAULT_TIMEOUT,
+  ROLE_KINDS as ROLES,
   assertOpenCodeOptions,
   readArgValue,
   readNonNegativeInt,
   readPositiveInt,
+  roleFlags,
 } from "./lib/args.mjs";
 import { isEntryPoint } from "./lib/entrypoint.mjs";
+import {
+  runHarnessCheckCommand,
+  runInstallCommand,
+  runUninstallCommand,
+} from "./install/commands.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"];
+const ROLE_FLAGS = roleFlags(ROLES);
 
 export function parseArgs(argv) {
   const options = {
     cwd: process.cwd(),
     task: null,
-    maxSteps: 20,
-    timeout: 3600,
+    maxSteps: DEFAULT_MAX_STEPS,
+    timeout: DEFAULT_TIMEOUT,
     transcript: null,
     verbose: false,
   };
@@ -37,21 +46,10 @@ export function parseArgs(argv) {
   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 (Object.hasOwn(ROLE_FLAGS, arg)) {
+      options[ROLE_FLAGS[arg]] = readValue(arg, ++i);
+      continue;
     }
-    if (matched) continue;
 
     switch (arg) {
       case "--cwd":
@@ -133,6 +131,15 @@ 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.
+  agent-loop install            Install harness entry points and parent guards at user
+                                scope. Interactive, or --harness <list> --yes.
+  agent-loop uninstall          Remove the installed entry points and guards. Restores
+                                files that install changed.
+  agent-loop harness-check      Exit 0 only when the nearest harness process above the
+                                shell matches the named harness, 3 when another harness
+                                is nearest, and 1 when the check cannot run or finds no
+                                harness ancestor. Used by the Claude, Codex, and
+                                Antigravity skills.
 
 Role operations:
 
@@ -144,12 +151,16 @@ 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
+  --parent-session <id>         Required on the init call. The harness session id the
+                                parent-edit guard matches; later calls reject a changed
+                                value. The headless form (no subcommand) is the explicit
+                                unguarded path.
+  --task / --mode / --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.
+  --resume-interrupted          Explicitly continue after an uncertain previous turn.
 
 Options:
 
@@ -183,12 +194,7 @@ Environment:
 
 Agents:
 
-  claude
-  codex
-  agy
-  antigravity
-  opencode
-  copilot
+  ${[...supportedAgents].join("\n  ")}
 `.trim(),
   );
 }
@@ -209,6 +215,21 @@ export async function main(argv = process.argv.slice(2), agents = defaultAgents)
     return;
   }
 
+  if (argv[0] === "install") {
+    await runInstallCommand(argv.slice(1));
+    return;
+  }
+
+  if (argv[0] === "uninstall") {
+    await runUninstallCommand(argv.slice(1));
+    return;
+  }
+
+  if (argv[0] === "harness-check") {
+    await runHarnessCheckCommand(argv.slice(1));
+    return;
+  }
+
   let options;
   try {
     options = parseArgs(argv);

package/src/entrypoints/copilot.mjs

@@ -13,13 +13,18 @@ import { isEntryPoint } from "../lib/entrypoint.mjs";
 const INSTRUCTIONS_DIR = fileURLToPath(new URL("../../docs", import.meta.url));
 const INSTRUCTIONS_PATH = join(INSTRUCTIONS_DIR, "orchestrator-instructions.md");
 
+// The prompt is one line. execa rejects CR or LF in an argument on Windows when
+// it spawns a batch shim through cmd.exe, and npm installs the copilot CLI as a
+// .cmd shim on Windows.
 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");
+  ]
+    .join(" ")
+    .replace(/[\r\n]+/g, " ");
 
 export function buildCopilotInvocation(task, sessionId) {
   const normalizedTask = String(task ?? "").trim();

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

@@ -0,0 +1,28 @@
+// Antigravity CLI PreToolUse hook for the parent-edit guard (#88). Antigravity
+// names the session `conversationId` and the tool `toolCall.name`. It blocks a
+// tool call when a hook prints `{}`, prints an empty decision, or exits
+// non-zero, so every allow path here prints nothing and exits 0: the normal
+// permission flow stays intact. One deny object prints only for a guarded tool
+// call from the registered parent while its run is non-terminal. Fail-open by
+// design: an unparseable payload, an absent record, a terminal lifecycle, and a
+// lookup error all deny nothing.
+import { runParentGuard } from "./decision.mjs";
+
+// The guarded tools: every registered file-edit tool, plus the subagent start
+// and message tools. `manage_subagents` stays allowed, so the parent can still
+// list and terminate a child. The `hooks.json` matcher names the same set.
+const ANTIGRAVITY_GUARDED_TOOLS = new Set([
+  "write_to_file",
+  "replace_file_content",
+  "multi_replace_file_content",
+  "sed_file",
+  "notebook_edit",
+  "invoke_subagent",
+  "send_message",
+]);
+
+await runParentGuard((reason) => ({ decision: "deny", reason }), {
+  readSessionId: (input) =>
+    typeof input?.conversationId === "string" ? input.conversationId : null,
+  isGuarded: (input) => ANTIGRAVITY_GUARDED_TOOLS.has(input?.toolCall?.name),
+});

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

@@ -2,34 +2,9 @@
 // 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";
+import { runParentGuard } 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.
-  }
-}
+await runParentGuard((reason) => ({
+  permissionDecision: "deny",
+  permissionDecisionReason: reason,
+}));

package/src/hook/decision.mjs

@@ -1,9 +1,12 @@
-// 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.
+// Decision logic and the shared command-hook flow for the #57 parent guard.
+// `decideParentGuard` 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. `runParentGuard` drives that decision from the stdin payload
+// for the Claude Code, Codex, Copilot, and Antigravity command hooks, each of
+// which supplies its own input mapping and deny shape. 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 =
@@ -25,3 +28,53 @@ export async function decideParentGuard(sessionId, { lookup = readStateForSessio
   }
   return { decision: "deny", reason: GUARD_DENY_REASON };
 }
+
+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;
+  }
+}
+
+/**
+ * Runs the shared command-hook flow: read the hook JSON from stdin, extract the
+ * harness's session id, evaluate the guard, and print one deny payload from
+ * `formatDeny`. Fails open: a missing session id, unparseable input, a tool the
+ * harness does not guard, and a lookup error all exit without output, so the
+ * normal permission flow stays intact.
+ * @param {(reason: string) => object} formatDeny builds the harness's deny payload
+ * @param {{
+ *   readSessionId?: (input: unknown) => string | null,
+ *   isGuarded?: (input: unknown) => boolean,
+ * }} [options] maps the harness input; defaults to the Claude/Codex/Copilot
+ *   `session_id` field and every tool
+ */
+export async function runParentGuard(
+  formatDeny,
+  {
+    readSessionId = (input) => (typeof input?.session_id === "string" ? input.session_id : null),
+    isGuarded = () => true,
+  } = {},
+) {
+  const input = await readHookInput();
+  if (!input || !isGuarded(input)) {
+    return;
+  }
+  const sessionId = readSessionId(input);
+  if (!sessionId) {
+    return;
+  }
+  try {
+    const verdict = await decideParentGuard(sessionId);
+    if (verdict.decision === "deny") {
+      console.log(JSON.stringify(formatDeny(verdict.reason)));
+    }
+  } catch {
+    // A failed lookup denies nothing: the guard never blocks on its own error.
+  }
+}

package/src/hook/opencode-plugin.mjs

@@ -0,0 +1,92 @@
+// OpenCode parent-guard plugin factory (#75, packaged by #139). The shipped
+// entry point is the rendered template at
+// `src/install/templates/opencode/plugins/parent-guard.ts`, which imports this
+// factory and the shared decision logic by absolute URL. Keeping the behavior
+// here lets tests drive the same object the rendered plugin exports.
+//
+// OpenCode ships no session placeholder for Markdown command templates, so the
+// plugin channel supplies the session id: a plugin command reads
+// `CommandInvocation.sessionID` and passes it to the parent, and a permission
+// hook reads `PermissionEvaluation.sessionID` and denies file edits from the
+// registered parent while its run is non-terminal. Both paths reuse
+// `decideParentGuard`, so the OpenCode guard matches it exactly. Fail-open by
+// design: every other session, every terminal lifecycle, and every absent or
+// corrupt record allows the call.
+//
+// The shared Claude and Codex skills set `metadata.opencode/autoinvoke: false`,
+// so OpenCode drops them from the model's skill list and the model cannot
+// auto-invoke one for an /agent-loop request. This command is then the only
+// `/agent-loop` entry point that carries the OpenCode session id (#150).
+//
+// The guard resolves the runs root from this server process's environment, so
+// an out-of-process `AGENT_LOOP_RUNS_ROOT` override (test-only) would desync
+// it from the `agent-loop` CLI that wrote the index.
+
+// The permission actions that carry a file edit. A set, not a single constant,
+// so a further edit tool is one entry. A live probe against OpenCode
+// v0.0.0-dev-19933 showed the built-in `edit`, `write`, and `apply_patch` tools
+// all raise the `edit` action, so the set covers every built-in file-edit tool.
+// `shell` is a different action and stays allowed. A tool served by an MCP
+// server raises its own action name and passes the guard.
+export const EDIT_ACTIONS = new Set(["edit"]);
+
+/**
+ * Builds the OpenCode plugin.
+ * @param {{
+ *   decideParentGuard: (sessionId: string) => Promise<{ decision: string, reason?: string }>,
+ *   instructionsPath: string,
+ * }} deps absolute path to the installed orchestrator instructions
+ */
+export function createParentGuardPlugin({ decideParentGuard, instructionsPath }) {
+  const COMMAND_NAME = "agent-loop";
+
+  const INSTRUCTIONS = (sessionID, task) =>
+    [
+      `Read \`${instructionsPath}\` and follow it for this request.`,
+      "The task and role settings are:",
+      task,
+      `This OpenCode session id is \`${sessionID}\`. Pass it as \`--parent-session\` on the init dispatch call.`,
+    ].join("\n\n");
+
+  return {
+    id: "agent-loop.parent-guard",
+    async setup(ctx) {
+      // Registers the entry point. The stored Markdown template cannot receive
+      // the parent session id, so the plugin command injects it into the
+      // orchestrator prompt instead.
+      await ctx.command.transform((editor) => {
+        editor.add({
+          name: COMMAND_NAME,
+          description:
+            "Run a delegated agent-loop role orchestration through the agent-loop CLI (rules in the installed orchestrator instructions).",
+          execute: async ({ sessionID, prompt, delivery }) => {
+            await ctx.session.prompt({
+              ...prompt,
+              sessionID,
+              text: INSTRUCTIONS(sessionID, prompt.text),
+              delivery,
+            });
+          },
+        });
+      });
+
+      // Denies a file edit from the registered parent while the run is
+      // non-terminal. A failed lookup denies nothing.
+      await ctx.permission.hook("evaluate", async (event) => {
+        if (!EDIT_ACTIONS.has(event.action) || typeof event.sessionID !== "string") {
+          return;
+        }
+        let verdict;
+        try {
+          verdict = await decideParentGuard(event.sessionID);
+        } catch {
+          return;
+        }
+        if (verdict.decision === "deny") {
+          event.effect = "deny";
+          event.message = verdict.reason;
+        }
+      });
+    },
+  };
+}

package/src/hook/parent-guard.mjs

@@ -4,37 +4,12 @@
 // 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";
+import { runParentGuard } 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.
-  }
-}
+await runParentGuard((reason) => ({
+  hookSpecificOutput: {
+    hookEventName: "PreToolUse",
+    permissionDecision: "deny",
+    permissionDecisionReason: reason,
+  },
+}));