@bpinternal/overwatch 0.1.0

package/dist/agents.js

@@ -0,0 +1,107 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var agents_exports = {};
+__export(agents_exports, {
+  Agent: () => Agent,
+  Claude: () => Claude,
+  Codex: () => Codex
+});
+module.exports = __toCommonJS(agents_exports);
+class Agent {
+  /**
+   * Called once per run, before any {@link executeAgent} call. Install the agent's CLI
+   * here if the sandbox image doesn't already have it.
+   */
+  async prepare(_ctx) {
+  }
+}
+const PROMPT_FILE = ".control-loop/prompt.txt";
+async function stagePrompt(instructions, ctx) {
+  await ctx.writeFile(PROMPT_FILE, instructions);
+  return `"$(cat ${PROMPT_FILE})"`;
+}
+class Claude extends Agent {
+  constructor(props) {
+    super();
+    this.props = props;
+  }
+  async prepare(ctx) {
+    const check = await ctx.exec("command -v claude");
+    if (check.exitCode === 0) return;
+    const install = await ctx.exec("npm install -g @anthropic-ai/claude-code", { timeoutSec: 600 });
+    if (install.exitCode !== 0) {
+      throw new Error(`failed to install claude CLI: ${install.output}`);
+    }
+  }
+  async executeAgent(instructions, ctx) {
+    const prompt = await stagePrompt(instructions, ctx);
+    const model = this.props.model ? ` --model ${this.props.model}` : "";
+    const result = await ctx.exec(`claude -p ${prompt}${model} --dangerously-skip-permissions`, {
+      env: { ANTHROPIC_API_KEY: this.props.apiKey },
+      timeoutSec: this.props.timeoutSec ?? 900
+    });
+    if (result.exitCode !== 0) {
+      throw new Error(`claude exited ${result.exitCode}: ${result.output}`);
+    }
+  }
+}
+class Codex extends Agent {
+  constructor(props) {
+    super();
+    this.props = props;
+  }
+  async prepare(ctx) {
+    const check = await ctx.exec("command -v codex");
+    if (check.exitCode !== 0) {
+      const install = await ctx.exec("npm install -g @openai/codex", { timeoutSec: 600 });
+      if (install.exitCode !== 0) {
+        throw new Error(`failed to install codex CLI: ${install.output}`);
+      }
+    }
+    const env = { OPENAI_API_KEY: this.props.apiKey };
+    const login = await ctx.exec(`printenv OPENAI_API_KEY | codex login --with-api-key`, { env });
+    if (login.exitCode !== 0) {
+      const legacy = await ctx.exec(`codex login --api-key "$OPENAI_API_KEY"`, { env });
+      if (legacy.exitCode !== 0) {
+        throw new Error(`codex login failed: ${login.output} ${legacy.output}`);
+      }
+    }
+  }
+  async executeAgent(instructions, ctx) {
+    const prompt = await stagePrompt(instructions, ctx);
+    const model = this.props.model ? ` --model ${this.props.model}` : "";
+    const result = await ctx.exec(
+      `codex exec ${prompt}${model} --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check </dev/null`,
+      {
+        env: { OPENAI_API_KEY: this.props.apiKey },
+        timeoutSec: this.props.timeoutSec ?? 900
+      }
+    );
+    if (result.exitCode !== 0) {
+      throw new Error(`codex exited ${result.exitCode}: ${result.output}`);
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Agent,
+  Claude,
+  Codex
+});
+//# sourceMappingURL=agents.js.map

package/dist/agents.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/agents.ts"],
+  "sourcesContent": ["/**\n * The slice of the sandbox an agent is allowed to touch. Commands run with the repo\n * root as cwd; file paths are relative to the repo root.\n */\nexport interface AgentContext {\n  exec: (command: string, options?: { env?: Record<string, string>; timeoutSec?: number }) => Promise<{\n    exitCode: number;\n    output: string;\n  }>;\n  writeFile: (path: string, content: string) => Promise<void>;\n}\n\n/**\n * A coding agent that can be driven headlessly inside the sandbox. Implementations\n * know how to install their own CLI and how to invoke it with a prompt.\n */\nexport abstract class Agent {\n  /**\n   * Called once per run, before any {@link executeAgent} call. Install the agent's CLI\n   * here if the sandbox image doesn't already have it.\n   */\n  async prepare(_ctx: AgentContext): Promise<void> {}\n\n  /** Runs the agent against the repo with the given instructions, applying edits in place. */\n  abstract executeAgent(instructions: string, ctx: AgentContext): Promise<void>;\n}\n\nconst PROMPT_FILE = \".control-loop/prompt.txt\";\n\n/**\n * Writes the prompt to a scratch file and returns a shell fragment that expands to its\n * content. Instructions contain sensor/user text; going through a file avoids re-parsing\n * shell metacharacters inside them.\n */\nasync function stagePrompt(instructions: string, ctx: AgentContext): Promise<string> {\n  await ctx.writeFile(PROMPT_FILE, instructions);\n  return `\"$(cat ${PROMPT_FILE})\"`;\n}\n\nexport type ClaudeProps = {\n  apiKey: string;\n  /** e.g. \"claude-sonnet-5\". Defaults to the CLI's default model. */\n  model?: string;\n  /** Max seconds for one agent invocation. Default 900. */\n  timeoutSec?: number;\n};\n\nexport class Claude extends Agent {\n  constructor(private readonly props: ClaudeProps) {\n    super();\n  }\n\n  override async prepare(ctx: AgentContext): Promise<void> {\n    const check = await ctx.exec(\"command -v claude\");\n    if (check.exitCode === 0) return;\n    const install = await ctx.exec(\"npm install -g @anthropic-ai/claude-code\", { timeoutSec: 600 });\n    if (install.exitCode !== 0) {\n      throw new Error(`failed to install claude CLI: ${install.output}`);\n    }\n  }\n\n  override async executeAgent(instructions: string, ctx: AgentContext): Promise<void> {\n    const prompt = await stagePrompt(instructions, ctx);\n    const model = this.props.model ? ` --model ${this.props.model}` : \"\";\n    const result = await ctx.exec(`claude -p ${prompt}${model} --dangerously-skip-permissions`, {\n      env: { ANTHROPIC_API_KEY: this.props.apiKey },\n      timeoutSec: this.props.timeoutSec ?? 900,\n    });\n    if (result.exitCode !== 0) {\n      throw new Error(`claude exited ${result.exitCode}: ${result.output}`);\n    }\n  }\n}\n\nexport type CodexProps = {\n  apiKey: string;\n  /** e.g. \"gpt-5.1-codex\". Defaults to the CLI's default model. */\n  model?: string;\n  /** Max seconds for one agent invocation. Default 900. */\n  timeoutSec?: number;\n};\n\nexport class Codex extends Agent {\n  constructor(private readonly props: CodexProps) {\n    super();\n  }\n\n  override async prepare(ctx: AgentContext): Promise<void> {\n    const check = await ctx.exec(\"command -v codex\");\n    if (check.exitCode !== 0) {\n      const install = await ctx.exec(\"npm install -g @openai/codex\", { timeoutSec: 600 });\n      if (install.exitCode !== 0) {\n        throw new Error(`failed to install codex CLI: ${install.output}`);\n      }\n    }\n\n    // Recent Codex CLI versions ignore OPENAI_API_KEY in the environment and require\n    // an auth file created by `codex login` (\"Missing bearer or basic authentication\n    // in header\" otherwise). Piping through printenv keeps the key out of the command\n    // line; older CLIs without --with-api-key fall back to the deprecated flag.\n    const env = { OPENAI_API_KEY: this.props.apiKey };\n    const login = await ctx.exec(`printenv OPENAI_API_KEY | codex login --with-api-key`, { env });\n    if (login.exitCode !== 0) {\n      const legacy = await ctx.exec(`codex login --api-key \"$OPENAI_API_KEY\"`, { env });\n      if (legacy.exitCode !== 0) {\n        throw new Error(`codex login failed: ${login.output} ${legacy.output}`);\n      }\n    }\n  }\n\n  override async executeAgent(instructions: string, ctx: AgentContext): Promise<void> {\n    const prompt = await stagePrompt(instructions, ctx);\n    const model = this.props.model ? ` --model ${this.props.model}` : \"\";\n    // Codex's own sandbox (--sandbox workspace-write) relies on Landlock/seccomp, which\n    // fails inside containers \u2014 and the Daytona sandbox already isolates everything, so\n    // bypassing it is what Codex documents for CI/container use. </dev/null stops\n    // `codex exec` from waiting on extra stdin input.\n    const result = await ctx.exec(\n      `codex exec ${prompt}${model} --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check </dev/null`,\n      {\n        env: { OPENAI_API_KEY: this.props.apiKey },\n        timeoutSec: this.props.timeoutSec ?? 900,\n      },\n    );\n    if (result.exitCode !== 0) {\n      throw new Error(`codex exited ${result.exitCode}: ${result.output}`);\n    }\n  }\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAgBO,MAAe,MAAM;AAAA;AAAA;AAAA;AAAA;AAAA,EAK1B,MAAM,QAAQ,MAAmC;AAAA,EAAC;AAIpD;AAEA,MAAM,cAAc;AAOpB,eAAe,YAAY,cAAsB,KAAoC;AACnF,QAAM,IAAI,UAAU,aAAa,YAAY;AAC7C,SAAO,UAAU,WAAW;AAC9B;AAUO,MAAM,eAAe,MAAM;AAAA,EAChC,YAA6B,OAAoB;AAC/C,UAAM;AADqB;AAAA,EAE7B;AAAA,EAEA,MAAe,QAAQ,KAAkC;AACvD,UAAM,QAAQ,MAAM,IAAI,KAAK,mBAAmB;AAChD,QAAI,MAAM,aAAa,EAAG;AAC1B,UAAM,UAAU,MAAM,IAAI,KAAK,4CAA4C,EAAE,YAAY,IAAI,CAAC;AAC9F,QAAI,QAAQ,aAAa,GAAG;AAC1B,YAAM,IAAI,MAAM,iCAAiC,QAAQ,MAAM,EAAE;AAAA,IACnE;AAAA,EACF;AAAA,EAEA,MAAe,aAAa,cAAsB,KAAkC;AAClF,UAAM,SAAS,MAAM,YAAY,cAAc,GAAG;AAClD,UAAM,QAAQ,KAAK,MAAM,QAAQ,YAAY,KAAK,MAAM,KAAK,KAAK;AAClE,UAAM,SAAS,MAAM,IAAI,KAAK,aAAa,MAAM,GAAG,KAAK,mCAAmC;AAAA,MAC1F,KAAK,EAAE,mBAAmB,KAAK,MAAM,OAAO;AAAA,MAC5C,YAAY,KAAK,MAAM,cAAc;AAAA,IACvC,CAAC;AACD,QAAI,OAAO,aAAa,GAAG;AACzB,YAAM,IAAI,MAAM,iBAAiB,OAAO,QAAQ,KAAK,OAAO,MAAM,EAAE;AAAA,IACtE;AAAA,EACF;AACF;AAUO,MAAM,cAAc,MAAM;AAAA,EAC/B,YAA6B,OAAmB;AAC9C,UAAM;AADqB;AAAA,EAE7B;AAAA,EAEA,MAAe,QAAQ,KAAkC;AACvD,UAAM,QAAQ,MAAM,IAAI,KAAK,kBAAkB;AAC/C,QAAI,MAAM,aAAa,GAAG;AACxB,YAAM,UAAU,MAAM,IAAI,KAAK,gCAAgC,EAAE,YAAY,IAAI,CAAC;AAClF,UAAI,QAAQ,aAAa,GAAG;AAC1B,cAAM,IAAI,MAAM,gCAAgC,QAAQ,MAAM,EAAE;AAAA,MAClE;AAAA,IACF;AAMA,UAAM,MAAM,EAAE,gBAAgB,KAAK,MAAM,OAAO;AAChD,UAAM,QAAQ,MAAM,IAAI,KAAK,wDAAwD,EAAE,IAAI,CAAC;AAC5F,QAAI,MAAM,aAAa,GAAG;AACxB,YAAM,SAAS,MAAM,IAAI,KAAK,2CAA2C,EAAE,IAAI,CAAC;AAChF,UAAI,OAAO,aAAa,GAAG;AACzB,cAAM,IAAI,MAAM,uBAAuB,MAAM,MAAM,IAAI,OAAO,MAAM,EAAE;AAAA,MACxE;AAAA,IACF;AAAA,EACF;AAAA,EAEA,MAAe,aAAa,cAAsB,KAAkC;AAClF,UAAM,SAAS,MAAM,YAAY,cAAc,GAAG;AAClD,UAAM,QAAQ,KAAK,MAAM,QAAQ,YAAY,KAAK,MAAM,KAAK,KAAK;AAKlE,UAAM,SAAS,MAAM,IAAI;AAAA,MACvB,cAAc,MAAM,GAAG,KAAK;AAAA,MAC5B;AAAA,QACE,KAAK,EAAE,gBAAgB,KAAK,MAAM,OAAO;AAAA,QACzC,YAAY,KAAK,MAAM,cAAc;AAAA,MACvC;AAAA,IACF;AACA,QAAI,OAAO,aAAa,GAAG;AACzB,YAAM,IAAI,MAAM,gBAAgB,OAAO,QAAQ,KAAK,OAAO,MAAM,EAAE;AAAA,IACrE;AAAA,EACF;AACF;",
+  "names": []
+}

package/dist/claims.d.ts

@@ -0,0 +1,16 @@
+import type { Signal } from "./types";
+/** Signals are matched across sensor runs by file + message; line numbers shift after edits. */
+export declare function signalKey(signal: Signal): string;
+/**
+ * Open PRs "claim" the signals they fix via an invisible marker in their body, so
+ * concurrent runs (maxOpenPrCount > 1) don't fix the same signals twice while earlier
+ * PRs are still unmerged. A merged PR removes the signals at the source (the sensor
+ * stops reporting them); a closed-unmerged PR releases its claims automatically.
+ *
+ * The write half (`claimMarker`) lives with the PR-opening actuator; the read half
+ * (`parseClaimedKeys`) is used by the loop when filtering sensed signals — both share
+ * the marker string, so they stay in this one file.
+ */
+export declare const CLAIM_MARKER = "control-loop:claimed-signals";
+export declare function claimMarker(signals: Signal[]): string;
+export declare function parseClaimedKeys(body: string): string[];

package/dist/claims.js

@@ -0,0 +1,51 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var claims_exports = {};
+__export(claims_exports, {
+  CLAIM_MARKER: () => CLAIM_MARKER,
+  claimMarker: () => claimMarker,
+  parseClaimedKeys: () => parseClaimedKeys,
+  signalKey: () => signalKey
+});
+module.exports = __toCommonJS(claims_exports);
+function signalKey(signal) {
+  return `${signal.location?.file ?? ""} ${signal.message}`;
+}
+const CLAIM_MARKER = "control-loop:claimed-signals";
+function claimMarker(signals) {
+  return `<!-- ${CLAIM_MARKER} ${JSON.stringify(signals.map(signalKey))} -->`;
+}
+function parseClaimedKeys(body) {
+  const match = body.match(new RegExp(`<!-- ${CLAIM_MARKER} (\\[.*?\\]) -->`, "s"));
+  if (!match) return [];
+  try {
+    const parsed = JSON.parse(match[1]);
+    return Array.isArray(parsed) ? parsed.filter((key) => typeof key === "string") : [];
+  } catch {
+    return [];
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CLAIM_MARKER,
+  claimMarker,
+  parseClaimedKeys,
+  signalKey
+});
+//# sourceMappingURL=claims.js.map

package/dist/claims.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/claims.ts"],
+  "sourcesContent": ["import type { Signal } from \"./types\";\n\n/** Signals are matched across sensor runs by file + message; line numbers shift after edits. */\nexport function signalKey(signal: Signal): string {\n  return `${signal.location?.file ?? \"\"} ${signal.message}`;\n}\n\n/**\n * Open PRs \"claim\" the signals they fix via an invisible marker in their body, so\n * concurrent runs (maxOpenPrCount > 1) don't fix the same signals twice while earlier\n * PRs are still unmerged. A merged PR removes the signals at the source (the sensor\n * stops reporting them); a closed-unmerged PR releases its claims automatically.\n *\n * The write half (`claimMarker`) lives with the PR-opening actuator; the read half\n * (`parseClaimedKeys`) is used by the loop when filtering sensed signals \u2014 both share\n * the marker string, so they stay in this one file.\n */\nexport const CLAIM_MARKER = \"control-loop:claimed-signals\";\n\nexport function claimMarker(signals: Signal[]): string {\n  return `<!-- ${CLAIM_MARKER} ${JSON.stringify(signals.map(signalKey))} -->`;\n}\n\nexport function parseClaimedKeys(body: string): string[] {\n  const match = body.match(new RegExp(`<!-- ${CLAIM_MARKER} (\\\\[.*?\\\\]) -->`, \"s\"));\n  if (!match) return [];\n  try {\n    const parsed = JSON.parse(match[1]!) as unknown;\n    return Array.isArray(parsed) ? parsed.filter((key): key is string => typeof key === \"string\") : [];\n  } catch {\n    return [];\n  }\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAGO,SAAS,UAAU,QAAwB;AAChD,SAAO,GAAG,OAAO,UAAU,QAAQ,EAAE,IAAI,OAAO,OAAO;AACzD;AAYO,MAAM,eAAe;AAErB,SAAS,YAAY,SAA2B;AACrD,SAAO,QAAQ,YAAY,IAAI,KAAK,UAAU,QAAQ,IAAI,SAAS,CAAC,CAAC;AACvE;AAEO,SAAS,iBAAiB,MAAwB;AACvD,QAAM,QAAQ,KAAK,MAAM,IAAI,OAAO,QAAQ,YAAY,oBAAoB,GAAG,CAAC;AAChF,MAAI,CAAC,MAAO,QAAO,CAAC;AACpB,MAAI;AACF,UAAM,SAAS,KAAK,MAAM,MAAM,CAAC,CAAE;AACnC,WAAO,MAAM,QAAQ,MAAM,IAAI,OAAO,OAAO,CAAC,QAAuB,OAAO,QAAQ,QAAQ,IAAI,CAAC;AAAA,EACnG,QAAQ;AACN,WAAO,CAAC;AAAA,EACV;AACF;",
+  "names": []
+}

package/dist/cli.d.ts

@@ -0,0 +1,13 @@
+import type { ControlLoop } from "./control-loop";
+/**
+ * Builds and runs the loop's built-in CLI. Exposed as `loop.cli()` — see that method for
+ * the intended usage. Kept in its own module so `control-loop.ts` doesn't carry the
+ * command-parsing and output-formatting weight.
+ *
+ * The `run` command exits non-zero when a fix couldn't be verified (`fix-failed`), so a CI
+ * job surfaces it; any thrown error also exits non-zero. Every other outcome exits zero.
+ */
+export declare function runCli<TData>(loop: ControlLoop<TData>, meta: {
+    name: string;
+    description: string;
+}, argv?: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,94 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var cli_exports = {};
+__export(cli_exports, {
+  runCli: () => runCli
+});
+module.exports = __toCommonJS(cli_exports);
+var import_commander = require("commander");
+async function runCli(loop, meta, argv = process.argv) {
+  const program = new import_commander.Command();
+  program.name(meta.name).description(meta.description).showHelpAfterError();
+  program.command("run").description("Run one full cycle: sense \u2192 pick \u2192 actuate (the default actuator opens a PR).").action(async () => {
+    const result = await loop.run();
+    printRunResult(result);
+    if (result.status === "fix-failed") process.exitCode = 1;
+  });
+  program.command("apply-comments").description("Apply new review comments on a PR to its branch and push the fix in place.").argument("<pr>", "number of the pull request to read new comments from").action(async (pr) => {
+    const prNumber = Number(pr);
+    if (!Number.isInteger(prNumber) || prNumber <= 0) {
+      throw new Error(`expected a positive PR number, got "${pr}"`);
+    }
+    printApplyResult(await loop.applyPrComments(prNumber));
+  });
+  program.addHelpText(
+    "after",
+    `
+Examples:
+  $ ${meta.name} run
+  $ ${meta.name} apply-comments 1234
+`
+  );
+  if (argv.slice(2).length === 0) {
+    program.outputHelp();
+    return;
+  }
+  try {
+    await program.parseAsync(argv);
+  } catch (error) {
+    console.error(`error: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+  }
+}
+function printRunResult(result) {
+  switch (result.status) {
+    case "skipped":
+      console.log(`skipped: ${result.reason}`);
+      break;
+    case "clean":
+      console.log("clean \u2014 no signals to act on");
+      break;
+    case "fix-failed":
+      console.log(
+        `fix failed \u2014 ${result.unresolved.length} signal(s) still present after all attempts`
+      );
+      break;
+    case "pr-opened":
+      console.log(`PR opened: ${result.prUrl} (${result.fixed.length} signal(s) fixed)`);
+      break;
+  }
+}
+function printApplyResult(result) {
+  switch (result.status) {
+    case "no-new-comments":
+      console.log("no comments newer than the PR head \u2014 nothing to apply");
+      break;
+    case "no-changes":
+      console.log(`applied ${result.comments.length} comment(s) \u2014 the agent left the tree untouched`);
+      break;
+    case "comments-applied":
+      console.log(`applied ${result.comments.length} comment(s) \u2192 pushed to ${result.branch}`);
+      break;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  runCli
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/cli.ts"],
+  "sourcesContent": ["import { Command } from \"commander\";\nimport type { ControlLoop } from \"./control-loop\";\nimport type { ApplyCommentsResult, ControlLoopRunResult } from \"./types\";\n\n/**\n * Builds and runs the loop's built-in CLI. Exposed as `loop.cli()` \u2014 see that method for\n * the intended usage. Kept in its own module so `control-loop.ts` doesn't carry the\n * command-parsing and output-formatting weight.\n *\n * The `run` command exits non-zero when a fix couldn't be verified (`fix-failed`), so a CI\n * job surfaces it; any thrown error also exits non-zero. Every other outcome exits zero.\n */\nexport async function runCli<TData>(\n  loop: ControlLoop<TData>,\n  meta: { name: string; description: string },\n  argv: string[] = process.argv,\n): Promise<void> {\n  const program = new Command();\n  program.name(meta.name).description(meta.description).showHelpAfterError();\n\n  program\n    .command(\"run\")\n    .description(\"Run one full cycle: sense \u2192 pick \u2192 actuate (the default actuator opens a PR).\")\n    .action(async () => {\n      const result = await loop.run();\n      printRunResult(result);\n      if (result.status === \"fix-failed\") process.exitCode = 1;\n    });\n\n  program\n    .command(\"apply-comments\")\n    .description(\"Apply new review comments on a PR to its branch and push the fix in place.\")\n    .argument(\"<pr>\", \"number of the pull request to read new comments from\")\n    .action(async (pr: string) => {\n      const prNumber = Number(pr);\n      if (!Number.isInteger(prNumber) || prNumber <= 0) {\n        throw new Error(`expected a positive PR number, got \"${pr}\"`);\n      }\n      printApplyResult(await loop.applyPrComments(prNumber));\n    });\n\n  program.addHelpText(\n    \"after\",\n    `\\nExamples:\\n  $ ${meta.name} run\\n  $ ${meta.name} apply-comments 1234\\n`,\n  );\n\n  // No subcommand \u2192 show help rather than silently doing nothing.\n  if (argv.slice(2).length === 0) {\n    program.outputHelp();\n    return;\n  }\n\n  try {\n    await program.parseAsync(argv);\n  } catch (error) {\n    console.error(`error: ${error instanceof Error ? error.message : String(error)}`);\n    process.exitCode = 1;\n  }\n}\n\nfunction printRunResult(result: ControlLoopRunResult): void {\n  switch (result.status) {\n    case \"skipped\":\n      console.log(`skipped: ${result.reason}`);\n      break;\n    case \"clean\":\n      console.log(\"clean \u2014 no signals to act on\");\n      break;\n    case \"fix-failed\":\n      console.log(\n        `fix failed \u2014 ${result.unresolved.length} signal(s) still present after all attempts`,\n      );\n      break;\n    case \"pr-opened\":\n      console.log(`PR opened: ${result.prUrl} (${result.fixed.length} signal(s) fixed)`);\n      break;\n  }\n}\n\nfunction printApplyResult(result: ApplyCommentsResult): void {\n  switch (result.status) {\n    case \"no-new-comments\":\n      console.log(\"no comments newer than the PR head \u2014 nothing to apply\");\n      break;\n    case \"no-changes\":\n      console.log(`applied ${result.comments.length} comment(s) \u2014 the agent left the tree untouched`);\n      break;\n    case \"comments-applied\":\n      console.log(`applied ${result.comments.length} comment(s) \u2192 pushed to ${result.branch}`);\n      break;\n  }\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,uBAAwB;AAYxB,eAAsB,OACpB,MACA,MACA,OAAiB,QAAQ,MACV;AACf,QAAM,UAAU,IAAI,yBAAQ;AAC5B,UAAQ,KAAK,KAAK,IAAI,EAAE,YAAY,KAAK,WAAW,EAAE,mBAAmB;AAEzE,UACG,QAAQ,KAAK,EACb,YAAY,yFAA+E,EAC3F,OAAO,YAAY;AAClB,UAAM,SAAS,MAAM,KAAK,IAAI;AAC9B,mBAAe,MAAM;AACrB,QAAI,OAAO,WAAW,aAAc,SAAQ,WAAW;AAAA,EACzD,CAAC;AAEH,UACG,QAAQ,gBAAgB,EACxB,YAAY,4EAA4E,EACxF,SAAS,QAAQ,sDAAsD,EACvE,OAAO,OAAO,OAAe;AAC5B,UAAM,WAAW,OAAO,EAAE;AAC1B,QAAI,CAAC,OAAO,UAAU,QAAQ,KAAK,YAAY,GAAG;AAChD,YAAM,IAAI,MAAM,uCAAuC,EAAE,GAAG;AAAA,IAC9D;AACA,qBAAiB,MAAM,KAAK,gBAAgB,QAAQ,CAAC;AAAA,EACvD,CAAC;AAEH,UAAQ;AAAA,IACN;AAAA,IACA;AAAA;AAAA,MAAoB,KAAK,IAAI;AAAA,MAAa,KAAK,IAAI;AAAA;AAAA,EACrD;AAGA,MAAI,KAAK,MAAM,CAAC,EAAE,WAAW,GAAG;AAC9B,YAAQ,WAAW;AACnB;AAAA,EACF;AAEA,MAAI;AACF,UAAM,QAAQ,WAAW,IAAI;AAAA,EAC/B,SAAS,OAAO;AACd,YAAQ,MAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,CAAC,EAAE;AAChF,YAAQ,WAAW;AAAA,EACrB;AACF;AAEA,SAAS,eAAe,QAAoC;AAC1D,UAAQ,OAAO,QAAQ;AAAA,IACrB,KAAK;AACH,cAAQ,IAAI,YAAY,OAAO,MAAM,EAAE;AACvC;AAAA,IACF,KAAK;AACH,cAAQ,IAAI,mCAA8B;AAC1C;AAAA,IACF,KAAK;AACH,cAAQ;AAAA,QACN,qBAAgB,OAAO,WAAW,MAAM;AAAA,MAC1C;AACA;AAAA,IACF,KAAK;AACH,cAAQ,IAAI,cAAc,OAAO,KAAK,KAAK,OAAO,MAAM,MAAM,mBAAmB;AACjF;AAAA,EACJ;AACF;AAEA,SAAS,iBAAiB,QAAmC;AAC3D,UAAQ,OAAO,QAAQ;AAAA,IACrB,KAAK;AACH,cAAQ,IAAI,4DAAuD;AACnE;AAAA,IACF,KAAK;AACH,cAAQ,IAAI,WAAW,OAAO,SAAS,MAAM,sDAAiD;AAC9F;AAAA,IACF,KAAK;AACH,cAAQ,IAAI,WAAW,OAAO,SAAS,MAAM,gCAA2B,OAAO,MAAM,EAAE;AACvF;AAAA,EACJ;AACF;",
+  "names": []
+}

package/dist/control-loop.d.ts

@@ -0,0 +1,50 @@
+import type { ApplyCommentsResult, ControlLoopOptions, ControlLoopRunResult } from "./types";
+export declare class ControlLoop<TData = unknown> {
+    private readonly options;
+    constructor(options: ControlLoopOptions<TData>);
+    /**
+     * Executes one full cycle: sense -> pick -> run actuator -> verify -> PR.
+     * Invoke this from whatever scheduler you use (cron, CI); the loop itself
+     * does not stay resident.
+     */
+    run(): Promise<ControlLoopRunResult<TData>>;
+    /**
+     * Creates a sandbox, clones `branch` (default: the base branch), configures git, and
+     * runs the `setup` hook — the provisioning every entry point shares — then invokes `fn`
+     * with the ready sandbox and its {@link AgentContext}. The sandbox is always torn down
+     * afterward, including when provisioning or `fn` throws.
+     */
+    private withProvisionedSandbox;
+    /**
+     * Provisions a sandbox the way {@link run} does up through the `setup` hook — clone,
+     * configure git, run `config.hooks.setup` — then captures its filesystem as a Daytona
+     * snapshot named `name` and returns, without sensing, touching the agent, or opening a
+     * PR. Pass the same `name` as `config.sandbox.snapshot` on later runs so they start from
+     * the baked-in toolchain instead of re-running `setup` every time.
+     *
+     * Call this instead of `run` (e.g. as a one-off provisioning step); `name` is required.
+     */
+    saveSnapshot(name: string): Promise<void>;
+    /**
+     * Handler for PR comment events: reads the comments left on the PR since its last
+     * commit, has the agent apply them on the PR's branch, and pushes — updating the PR
+     * in place. Wire this to your webhook (or poller) for PR comment activity.
+     *
+     * Comments older than the PR's head commit are treated as already addressed, which
+     * makes repeated triggers for the same comment thread safe.
+     */
+    applyPrComments(prNumber: number): Promise<ApplyCommentsResult>;
+    /**
+     * Ready-made CLI for driving this loop from CI (or a shell). Declare the loop, then call
+     * this once at the end of the file:
+     *
+     *     const loop = new ControlLoop({ ... });
+     *     loop.cli();
+     *
+     * Two subcommands: `run` (one full cycle → {@link run}) and `apply-comments <pr>`
+     * (apply new PR review comments → {@link applyPrComments}). Run with `--help` for usage.
+     * Parses `process.argv` by default; the process exits non-zero on error or an unresolved
+     * fix, so CI can gate on it.
+     */
+    cli(argv?: string[]): Promise<void>;
+}