@bpinternal/overwatch 0.1.0

package/dist/actuators/agent-pr.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/actuators/agent-pr.ts"],
+  "sourcesContent": ["import type { AgentContext } from \"../agents\";\nimport type { RunLog } from \"../log\";\nimport type { ControlLoopConfig, ControlLoopRunResult, Signal } from \"../types\";\nimport { claimMarker, signalKey } from \"../claims\";\nimport {\n  REPO_PATH,\n  SCRATCH_DIR,\n  commitAll,\n  memoryNote,\n  readMemory,\n  runConfiguredCommand,\n} from \"../sandbox\";\nimport { Actuator } from \"./actuator\";\nimport type { ActuatorInput, InstructionBuilder } from \"./index\";\nimport { fromSignal } from \"./instructions\";\n\nexport interface AgentPrActuatorProps {\n  /** Builds the agent's instructions per signal. Defaults to {@link fromSignal}. */\n  instructions?: InstructionBuilder;\n}\n\n/**\n * The default actuator: for each picked signal it runs the configured coding agent, then\n * re-senses to verify the signal is gone (retrying up to `config.maxFixAttempts`), and\n * finally commits every fix to a fresh branch and opens one PR \u2014 claiming the signals it\n * fixed in the PR body so concurrent runs don't duplicate the work.\n *\n * This is the behavior the loop used to hard-code; it's now a swappable actuator.\n */\nexport class AgentPrActuator<TData = unknown> extends Actuator<TData> {\n  private readonly instructions: InstructionBuilder;\n\n  constructor(props: AgentPrActuatorProps = {}) {\n    super();\n    this.instructions = props.instructions ?? fromSignal();\n  }\n\n  async act(input: ActuatorInput<TData>): Promise<ControlLoopRunResult<TData>> {\n    const { signals: picked, sandbox, ctx, sense, config, log, label, displayLabel } = input;\n\n    const prefix = (config.branchPrefix ?? \"control-loop\").replace(/\\/+$/, \"\");\n    const branch = `${prefix}/${label}-${Date.now().toString(36)}`;\n    await log.step(`checking out branch ${branch}`, async () => {\n      await sandbox.git.createBranch(REPO_PATH, branch);\n      await sandbox.git.checkoutBranch(REPO_PATH, branch);\n    });\n\n    await log.step(\"preparing agent\", () => config.agent.prepare(ctx));\n\n    const memory = await readMemory(ctx, label);\n    const unresolved = await this.runFixLoop(picked, ctx, sense, memory, log, config);\n    if (unresolved.length > 0) {\n      log.finish(`fix failed \u2014 ${unresolved.length} signal(s) still present`);\n      return { status: \"fix-failed\", unresolved };\n    }\n\n    // The scratch dir holds prompts and sensor scripts; it must not end up in the PR.\n    await ctx.exec(`rm -rf ${SCRATCH_DIR}`);\n    await runConfiguredCommand(\"preCommit\", config, ctx, log);\n    await log.step(\"committing & pushing\", async () => {\n      await commitAll(ctx, prTitle(displayLabel, picked));\n      await config.git.push(sandbox, REPO_PATH, branch);\n    });\n\n    const prUrl = await log.step(\"opening pull request\", () =>\n      config.git.openPr({\n        branch,\n        label,\n        title: prTitle(displayLabel, picked),\n        body: prBody(displayLabel, picked),\n      }),\n    );\n    log.finish(`PR opened \u2192 ${prUrl}`);\n    return { status: \"pr-opened\", prUrl, fixed: picked };\n  }\n\n  /**\n   * Runs the agent on each signal, then re-senses to verify. Signals still reported\n   * by the sensor get retried (with a nudge appended) up to maxFixAttempts times.\n   */\n  private async runFixLoop(\n    picked: Signal<TData>[],\n    ctx: AgentContext,\n    sense: () => Promise<Signal<TData>[]>,\n    memory: string | undefined,\n    log: RunLog,\n    config: ControlLoopConfig,\n  ): Promise<Signal<TData>[]> {\n    const maxAttempts = config.maxFixAttempts ?? 3;\n    let remaining = picked;\n    let iteration = 0;\n\n    for (let attempt = 1; attempt <= maxAttempts && remaining.length > 0; attempt++) {\n      for (const signal of remaining) {\n        const { instructions } = await this.instructions(signal);\n        const retryNote =\n          attempt === 1\n            ? \"\"\n            : \"\\n\\nA previous attempt did not resolve this issue \u2014 the sensor still reports it. Look again and try a different approach.\";\n        const where = signalWhere(signal) || signal.message;\n        iteration++;\n        await log.step(`agent fixing ${where} (iteration ${iteration})`, () =>\n          config.agent.executeAgent(instructions + retryNote + memoryNote(memory), ctx),\n        );\n      }\n\n      const stillPresent = new Set((await log.step(\"re-sensing to verify\", sense)).map(signalKey));\n      remaining = remaining.filter((signal) => stillPresent.has(signalKey(signal)));\n    }\n\n    return remaining;\n  }\n}\n\n/** \"file:line\", \"file\", or \"\" \u2014 the human-readable location of a signal, if it has one. */\nfunction signalWhere(signal: Signal): string {\n  const { location } = signal;\n  if (!location) return \"\";\n  return `${location.file}${location.line ? `:${location.line}` : \"\"}`;\n}\n\nfunction prTitle(label: string, fixed: Signal[]): string {\n  return fixed.length === 1 ? `fix: ${fixed[0]!.message}` : `fix: ${label}: ${fixed.length} issues`;\n}\n\nfunction prBody(label: string, fixed: Signal[]): string {\n  const lines = fixed.map((signal) => {\n    const where = signalWhere(signal);\n    const priority = signal.priority ? ` (${signal.priority})` : \"\";\n    return `- ${where ? `\\`${where}\\` \u2014 ` : \"\"}${signal.message}${priority}`;\n  });\n  return [\n    `Automated fix opened by the **${label}** control loop.`,\n    \"\",\n    \"Signals resolved (verified by re-running the sensor):\",\n    ...lines,\n    \"\",\n    claimMarker(fixed),\n  ].join(\"\\n\");\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/actuators/comments.d.ts

@@ -0,0 +1,3 @@
+import type { CommentActuator } from "./index";
+/** Default comment actuator used by `applyPrComments` when none is configured. */
+export declare const prComments: CommentActuator;

package/dist/actuators/comments.js

@@ -0,0 +1,42 @@
+"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 comments_exports = {};
+__export(comments_exports, {
+  prComments: () => prComments
+});
+module.exports = __toCommonJS(comments_exports);
+const prComments = (comments) => {
+  const lines = comments.map(
+    (comment) => comment.file ? `- ${comment.author} on \`${comment.file}${comment.line ? `:${comment.line}` : ""}\`: ${comment.body}` : `- ${comment.author} (PR-level): ${comment.body}`
+  );
+  return {
+    instructions: [
+      "You are addressing review comments left on a pull request. Apply each comment's feedback to the code.",
+      "Keep changes minimal and scoped to what the comments ask \u2014 do not refactor or fix anything else.",
+      "",
+      "Comments to address:",
+      ...lines
+    ].join("\n")
+  };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  prComments
+});
+//# sourceMappingURL=comments.js.map

package/dist/actuators/comments.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/actuators/comments.ts"],
+  "sourcesContent": ["import type { PrComment } from \"../github\";\nimport type { CommentActuator } from \"./index\";\n\n/** Default comment actuator used by `applyPrComments` when none is configured. */\nexport const prComments: CommentActuator = (comments: PrComment[]) => {\n  const lines = comments.map((comment) =>\n    comment.file\n      ? `- ${comment.author} on \\`${comment.file}${comment.line ? `:${comment.line}` : \"\"}\\`: ${comment.body}`\n      : `- ${comment.author} (PR-level): ${comment.body}`,\n  );\n  return {\n    instructions: [\n      \"You are addressing review comments left on a pull request. Apply each comment's feedback to the code.\",\n      \"Keep changes minimal and scoped to what the comments ask \u2014 do not refactor or fix anything else.\",\n      \"\",\n      \"Comments to address:\",\n      ...lines,\n    ].join(\"\\n\"),\n  };\n};\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAIO,MAAM,aAA8B,CAAC,aAA0B;AACpE,QAAM,QAAQ,SAAS;AAAA,IAAI,CAAC,YAC1B,QAAQ,OACJ,KAAK,QAAQ,MAAM,SAAS,QAAQ,IAAI,GAAG,QAAQ,OAAO,IAAI,QAAQ,IAAI,KAAK,EAAE,OAAO,QAAQ,IAAI,KACpG,KAAK,QAAQ,MAAM,gBAAgB,QAAQ,IAAI;AAAA,EACrD;AACA,SAAO;AAAA,IACL,cAAc;AAAA,MACZ;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA,GAAG;AAAA,IACL,EAAE,KAAK,IAAI;AAAA,EACb;AACF;",
+  "names": []
+}

package/dist/actuators/index.d.ts

@@ -0,0 +1,54 @@
+import type { Sandbox } from "@daytona/sdk";
+import type { AgentContext } from "../agents";
+import type { PrComment } from "../github";
+import type { RunLog } from "../log";
+import type { ControlLoopConfig, Signal } from "../types";
+/**
+ * Builds the instructions handed to the agent for one signal. Feeds the default
+ * {@link Actuator} (`actuators.AgentPrActuator`) — the actuator calls it once per signal
+ * to produce the prompt the coding agent runs with. Create one with `actuators.fromFile`
+ * or `actuators.fromSignal`.
+ */
+export type InstructionBuilder<TData = unknown> = (signal: Signal<TData>) => Promise<{
+    instructions: string;
+}> | {
+    instructions: string;
+};
+/**
+ * Builds the instructions handed to the agent when applying PR review comments.
+ * Optional — the loop has a sensible default.
+ */
+export type CommentActuator = (comments: PrComment[]) => Promise<{
+    instructions: string;
+}> | {
+    instructions: string;
+};
+/**
+ * Everything an actuator needs to act on the run's picked signals. The sandbox is fully
+ * provisioned (repo cloned, git configured, `config.hooks.setup` already run).
+ *
+ * Note `sandbox` is exposed directly — unlike agents, which only ever see {@link AgentContext} —
+ * because an actuator is the layer allowed to drive git (branch, push) and open PRs.
+ */
+export interface ActuatorInput<TData = unknown> {
+    /** The signals the picker selected to act on this run. */
+    signals: Signal<TData>[];
+    /** The provisioned sandbox. */
+    sandbox: Sandbox;
+    /** Narrow exec/writeFile surface into the sandbox, with the repo root as cwd. */
+    ctx: AgentContext;
+    /** Re-runs the sensor — actuators that fix-then-verify use this to confirm resolution. */
+    sense: () => Promise<Signal<TData>[]>;
+    /** The loop's static configuration. */
+    config: ControlLoopConfig;
+    /** Slugified loop label — used for the branch, PR label, and memory file. */
+    label: string;
+    /** Human-readable loop label — used in PR titles and bodies. */
+    displayLabel: string;
+    /** The run's logger. */
+    log: RunLog;
+}
+export { Actuator } from "./actuator";
+export { AgentPrActuator, type AgentPrActuatorProps } from "./agent-pr";
+export { fromFile, fromSignal } from "./instructions";
+export { prComments } from "./comments";

package/dist/actuators/index.js

@@ -0,0 +1,40 @@
+"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 actuators_exports = {};
+__export(actuators_exports, {
+  Actuator: () => import_actuator.Actuator,
+  AgentPrActuator: () => import_agent_pr.AgentPrActuator,
+  fromFile: () => import_instructions.fromFile,
+  fromSignal: () => import_instructions.fromSignal,
+  prComments: () => import_comments.prComments
+});
+module.exports = __toCommonJS(actuators_exports);
+var import_actuator = require("./actuator");
+var import_agent_pr = require("./agent-pr");
+var import_instructions = require("./instructions");
+var import_comments = require("./comments");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Actuator,
+  AgentPrActuator,
+  fromFile,
+  fromSignal,
+  prComments
+});
+//# sourceMappingURL=index.js.map

package/dist/actuators/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/actuators/index.ts"],
+  "sourcesContent": ["import type { Sandbox } from \"@daytona/sdk\";\nimport type { AgentContext } from \"../agents\";\nimport type { PrComment } from \"../github\";\nimport type { RunLog } from \"../log\";\nimport type { ControlLoopConfig, Signal } from \"../types\";\n\n/**\n * Builds the instructions handed to the agent for one signal. Feeds the default\n * {@link Actuator} (`actuators.AgentPrActuator`) \u2014 the actuator calls it once per signal\n * to produce the prompt the coding agent runs with. Create one with `actuators.fromFile`\n * or `actuators.fromSignal`.\n */\nexport type InstructionBuilder<TData = unknown> = (\n  signal: Signal<TData>,\n) => Promise<{ instructions: string }> | { instructions: string };\n\n/**\n * Builds the instructions handed to the agent when applying PR review comments.\n * Optional \u2014 the loop has a sensible default.\n */\nexport type CommentActuator = (\n  comments: PrComment[],\n) => Promise<{ instructions: string }> | { instructions: string };\n\n/**\n * Everything an actuator needs to act on the run's picked signals. The sandbox is fully\n * provisioned (repo cloned, git configured, `config.hooks.setup` already run).\n *\n * Note `sandbox` is exposed directly \u2014 unlike agents, which only ever see {@link AgentContext} \u2014\n * because an actuator is the layer allowed to drive git (branch, push) and open PRs.\n */\nexport interface ActuatorInput<TData = unknown> {\n  /** The signals the picker selected to act on this run. */\n  signals: Signal<TData>[];\n  /** The provisioned sandbox. */\n  sandbox: Sandbox;\n  /** Narrow exec/writeFile surface into the sandbox, with the repo root as cwd. */\n  ctx: AgentContext;\n  /** Re-runs the sensor \u2014 actuators that fix-then-verify use this to confirm resolution. */\n  sense: () => Promise<Signal<TData>[]>;\n  /** The loop's static configuration. */\n  config: ControlLoopConfig;\n  /** Slugified loop label \u2014 used for the branch, PR label, and memory file. */\n  label: string;\n  /** Human-readable loop label \u2014 used in PR titles and bodies. */\n  displayLabel: string;\n  /** The run's logger. */\n  log: RunLog;\n}\n\n// The abstract base lives in its own module (not inline here) so the sibling default\n// implementations can `extends Actuator` without forming a require-cycle with this\n// barrel \u2014 under the CommonJS build a subclass that imported its base from the barrel,\n// which in turn re-exports the subclass, would hit the base in its temporal dead zone.\nexport { Actuator } from \"./actuator\";\nexport { AgentPrActuator, type AgentPrActuatorProps } from \"./agent-pr\";\nexport { fromFile, fromSignal } from \"./instructions\";\nexport { prComments } from \"./comments\";\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAsDA,sBAAyB;AACzB,sBAA2D;AAC3D,0BAAqC;AACrC,sBAA2B;",
+  "names": []
+}

package/dist/actuators/instructions.d.ts

@@ -0,0 +1,9 @@
+import type { InstructionBuilder } from "./index";
+/**
+ * Instruction builder that reads a local file (markdown, plain text, ...) and uses its
+ * contents as the instructions for every signal, with the signal's details appended. The
+ * file is read once per process and cached.
+ */
+export declare const fromFile: (localPath: string) => InstructionBuilder;
+/** Minimal instruction builder: instructions built from the signal itself, nothing else. */
+export declare const fromSignal: () => InstructionBuilder;

package/dist/actuators/instructions.js

@@ -0,0 +1,62 @@
+"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 instructions_exports = {};
+__export(instructions_exports, {
+  fromFile: () => fromFile,
+  fromSignal: () => fromSignal
+});
+module.exports = __toCommonJS(instructions_exports);
+var import_promises = require("node:fs/promises");
+const fromFile = (localPath) => {
+  let cached;
+  return async (signal) => {
+    cached ??= await (0, import_promises.readFile)(localPath, "utf-8");
+    const where = signal.location ? `In ${signal.location.file}${signal.location.line ? ` around line ${signal.location.line}` : ""}: 
+` : "";
+    return {
+      instructions: `${where}${cached.trimEnd()}
+
+${signalContext(signal)}`
+    };
+  };
+};
+const fromSignal = () => (signal) => ({
+  instructions: [
+    "Fix the following issue detected in this codebase. Make the smallest change that resolves it;",
+    "do not fix unrelated issues or refactor unrelated code.",
+    "",
+    signalContext(signal)
+  ].join("\n")
+});
+function signalContext(signal) {
+  const lines = ["Issue to fix:"];
+  if (signal.location) {
+    const { file, line } = signal.location;
+    lines.push(`- Location: ${line ? `${file}:${line}` : file}`);
+  }
+  lines.push(`- Description: ${signal.message}`);
+  if (signal.priority) lines.push(`- Priority: ${signal.priority}`);
+  return lines.join("\n");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  fromFile,
+  fromSignal
+});
+//# sourceMappingURL=instructions.js.map

package/dist/actuators/instructions.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/actuators/instructions.ts"],
+  "sourcesContent": ["import { readFile } from \"node:fs/promises\";\nimport type { Signal } from \"../types\";\nimport type { InstructionBuilder } from \"./index\";\n\n/**\n * Instruction builder that reads a local file (markdown, plain text, ...) and uses its\n * contents as the instructions for every signal, with the signal's details appended. The\n * file is read once per process and cached.\n */\nexport const fromFile = (localPath: string): InstructionBuilder => {\n  let cached: string | undefined;\n  return async (signal) => {\n    cached ??= await readFile(localPath, \"utf-8\");\n    const where = signal.location\n      ? `In ${signal.location.file}${signal.location.line ? ` around line ${signal.location.line}` : \"\"}: \\n`\n      : \"\";\n    return {\n      instructions: `${where}${cached.trimEnd()}\\n\\n${signalContext(signal)}`,\n    };\n  };\n};\n\n/** Minimal instruction builder: instructions built from the signal itself, nothing else. */\nexport const fromSignal = (): InstructionBuilder => (signal) => ({\n  instructions: [\n    \"Fix the following issue detected in this codebase. Make the smallest change that resolves it;\",\n    \"do not fix unrelated issues or refactor unrelated code.\",\n    \"\",\n    signalContext(signal),\n  ].join(\"\\n\"),\n});\n\nfunction signalContext(signal: Signal): string {\n  const lines = [\"Issue to fix:\"];\n  if (signal.location) {\n    const { file, line } = signal.location;\n    lines.push(`- Location: ${line ? `${file}:${line}` : file}`);\n  }\n  lines.push(`- Description: ${signal.message}`);\n  if (signal.priority) lines.push(`- Priority: ${signal.priority}`);\n  return lines.join(\"\\n\");\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,sBAAyB;AASlB,MAAM,WAAW,CAAC,cAA0C;AACjE,MAAI;AACJ,SAAO,OAAO,WAAW;AACvB,eAAW,UAAM,0BAAS,WAAW,OAAO;AAC5C,UAAM,QAAQ,OAAO,WACjB,MAAM,OAAO,SAAS,IAAI,GAAG,OAAO,SAAS,OAAO,gBAAgB,OAAO,SAAS,IAAI,KAAK,EAAE;AAAA,IAC/F;AACJ,WAAO;AAAA,MACL,cAAc,GAAG,KAAK,GAAG,OAAO,QAAQ,CAAC;AAAA;AAAA,EAAO,cAAc,MAAM,CAAC;AAAA,IACvE;AAAA,EACF;AACF;AAGO,MAAM,aAAa,MAA0B,CAAC,YAAY;AAAA,EAC/D,cAAc;AAAA,IACZ;AAAA,IACA;AAAA,IACA;AAAA,IACA,cAAc,MAAM;AAAA,EACtB,EAAE,KAAK,IAAI;AACb;AAEA,SAAS,cAAc,QAAwB;AAC7C,QAAM,QAAQ,CAAC,eAAe;AAC9B,MAAI,OAAO,UAAU;AACnB,UAAM,EAAE,MAAM,KAAK,IAAI,OAAO;AAC9B,UAAM,KAAK,eAAe,OAAO,GAAG,IAAI,IAAI,IAAI,KAAK,IAAI,EAAE;AAAA,EAC7D;AACA,QAAM,KAAK,kBAAkB,OAAO,OAAO,EAAE;AAC7C,MAAI,OAAO,SAAU,OAAM,KAAK,eAAe,OAAO,QAAQ,EAAE;AAChE,SAAO,MAAM,KAAK,IAAI;AACxB;",
+  "names": []
+}

package/dist/actuators.d.ts

@@ -0,0 +1,72 @@
+import type { Sandbox } from "@daytona/sdk";
+import type { AgentContext } from "./agents";
+import type { RunLog } from "./log";
+import type { CommentActuator, ControlLoopConfig, ControlLoopRunResult, InstructionBuilder, Signal } from "./types";
+/**
+ * Actuator that reads a local file (markdown, plain text, ...) and uses its contents
+ * as the instructions for every signal, with the signal's details appended. The file
+ * is read once per process and cached.
+ */
+export declare const fromFile: (localPath: string) => InstructionBuilder;
+/** Minimal instruction builder: instructions built from the signal itself, nothing else. */
+export declare const fromSignal: () => InstructionBuilder;
+/** Default comment actuator used by `applyPrComments` when none is configured. */
+export declare const prComments: CommentActuator;
+/**
+ * Everything an actuator needs to act on the run's picked signals. The sandbox is fully
+ * provisioned (repo cloned, git configured, `config.hooks.setup` already run).
+ *
+ * Note `sandbox` is exposed directly — unlike agents, which only ever see {@link AgentContext} —
+ * because an actuator is the layer allowed to drive git (branch, push) and open PRs.
+ */
+export interface ActuatorInput<TData = unknown> {
+    /** The signals the picker selected to act on this run. */
+    signals: Signal<TData>[];
+    /** The provisioned sandbox. */
+    sandbox: Sandbox;
+    /** Narrow exec/writeFile surface into the sandbox, with the repo root as cwd. */
+    ctx: AgentContext;
+    /** Re-runs the sensor — actuators that fix-then-verify use this to confirm resolution. */
+    sense: () => Promise<Signal<TData>[]>;
+    /** The loop's static configuration. */
+    config: ControlLoopConfig;
+    /** Slugified loop label — used for the branch, PR label, and memory file. */
+    label: string;
+    /** Human-readable loop label — used in PR titles and bodies. */
+    displayLabel: string;
+    /** The run's logger. */
+    log: RunLog;
+}
+/**
+ * Owns the "act on the picked signals" step of a run and reports the outcome. The loop
+ * senses, filters, and picks; the actuator decides what actually happens next.
+ *
+ * The default {@link AgentPrActuator} runs a coding agent per signal, verifies via
+ * re-sensing, and opens a PR — but an actuator is free to do anything (post a message,
+ * write a report, call an API) and need not touch an agent or open a PR at all.
+ */
+export declare abstract class Actuator<TData = unknown> {
+    abstract act(input: ActuatorInput<TData>): Promise<ControlLoopRunResult<TData>>;
+}
+export interface AgentPrActuatorProps {
+    /** Builds the agent's instructions per signal. Defaults to {@link fromSignal}. */
+    instructions?: InstructionBuilder;
+}
+/**
+ * The default actuator: for each picked signal it runs the configured coding agent, then
+ * re-senses to verify the signal is gone (retrying up to `config.maxFixAttempts`), and
+ * finally commits every fix to a fresh branch and opens one PR — claiming the signals it
+ * fixed in the PR body so concurrent runs don't duplicate the work.
+ *
+ * This is the behavior the loop used to hard-code; it's now a swappable actuator.
+ */
+export declare class AgentPrActuator<TData = unknown> extends Actuator<TData> {
+    private readonly instructions;
+    constructor(props?: AgentPrActuatorProps);
+    act(input: ActuatorInput<TData>): Promise<ControlLoopRunResult<TData>>;
+    /**
+     * Runs the agent on each signal, then re-senses to verify. Signals still reported
+     * by the sensor get retried (with a nudge appended) up to maxFixAttempts times.
+     */
+    private runFixLoop;
+}

package/dist/actuators.js

@@ -0,0 +1,173 @@
+"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 actuators_exports = {};
+__export(actuators_exports, {
+  Actuator: () => Actuator,
+  AgentPrActuator: () => AgentPrActuator,
+  fromFile: () => fromFile,
+  fromSignal: () => fromSignal,
+  prComments: () => prComments
+});
+module.exports = __toCommonJS(actuators_exports);
+var import_promises = require("node:fs/promises");
+var import_claims = require("./claims");
+var import_sandbox = require("./sandbox");
+const fromFile = (localPath) => {
+  let cached;
+  return async (signal) => {
+    cached ??= await (0, import_promises.readFile)(localPath, "utf-8");
+    const where = signal.location ? `In ${signal.location.file}${signal.location.line ? ` around line ${signal.location.line}` : ""}: 
+` : "";
+    return {
+      instructions: `${where}${cached.trimEnd()}
+
+${signalContext(signal)}`
+    };
+  };
+};
+const fromSignal = () => (signal) => ({
+  instructions: [
+    "Fix the following issue detected in this codebase. Make the smallest change that resolves it;",
+    "do not fix unrelated issues or refactor unrelated code.",
+    "",
+    signalContext(signal)
+  ].join("\n")
+});
+function signalContext(signal) {
+  const lines = ["Issue to fix:"];
+  if (signal.location) {
+    const { file, line } = signal.location;
+    lines.push(`- Location: ${line ? `${file}:${line}` : file}`);
+  }
+  lines.push(`- Description: ${signal.message}`);
+  if (signal.priority) lines.push(`- Priority: ${signal.priority}`);
+  return lines.join("\n");
+}
+const prComments = (comments) => {
+  const lines = comments.map(
+    (comment) => comment.file ? `- ${comment.author} on \`${comment.file}${comment.line ? `:${comment.line}` : ""}\`: ${comment.body}` : `- ${comment.author} (PR-level): ${comment.body}`
+  );
+  return {
+    instructions: [
+      "You are addressing review comments left on a pull request. Apply each comment's feedback to the code.",
+      "Keep changes minimal and scoped to what the comments ask \u2014 do not refactor or fix anything else.",
+      "",
+      "Comments to address:",
+      ...lines
+    ].join("\n")
+  };
+};
+class Actuator {
+}
+class AgentPrActuator extends Actuator {
+  instructions;
+  constructor(props = {}) {
+    super();
+    this.instructions = props.instructions ?? fromSignal();
+  }
+  async act(input) {
+    const { signals: picked, sandbox, ctx, sense, config, log, label, displayLabel } = input;
+    const prefix = (config.branchPrefix ?? "control-loop").replace(/\/+$/, "");
+    const branch = `${prefix}/${label}-${Date.now().toString(36)}`;
+    await log.step(`checking out branch ${branch}`, async () => {
+      await sandbox.git.createBranch(import_sandbox.REPO_PATH, branch);
+      await sandbox.git.checkoutBranch(import_sandbox.REPO_PATH, branch);
+    });
+    await log.step("preparing agent", () => config.agent.prepare(ctx));
+    const memory = await (0, import_sandbox.readMemory)(ctx, label);
+    const unresolved = await this.runFixLoop(picked, ctx, sense, memory, log, config);
+    if (unresolved.length > 0) {
+      log.finish(`fix failed \u2014 ${unresolved.length} signal(s) still present`);
+      return { status: "fix-failed", unresolved };
+    }
+    await ctx.exec(`rm -rf ${import_sandbox.SCRATCH_DIR}`);
+    await (0, import_sandbox.runConfiguredCommand)("preCommit", config, ctx, log);
+    await log.step("committing & pushing", async () => {
+      await (0, import_sandbox.commitAll)(ctx, prTitle(displayLabel, picked));
+      await config.git.push(sandbox, import_sandbox.REPO_PATH, branch);
+    });
+    const prUrl = await log.step(
+      "opening pull request",
+      () => config.git.openPr({
+        branch,
+        label,
+        title: prTitle(displayLabel, picked),
+        body: prBody(displayLabel, picked)
+      })
+    );
+    log.finish(`PR opened \u2192 ${prUrl}`);
+    return { status: "pr-opened", prUrl, fixed: picked };
+  }
+  /**
+   * Runs the agent on each signal, then re-senses to verify. Signals still reported
+   * by the sensor get retried (with a nudge appended) up to maxFixAttempts times.
+   */
+  async runFixLoop(picked, ctx, sense, memory, log, config) {
+    const maxAttempts = config.maxFixAttempts ?? 3;
+    let remaining = picked;
+    let iteration = 0;
+    for (let attempt = 1; attempt <= maxAttempts && remaining.length > 0; attempt++) {
+      for (const signal of remaining) {
+        const { instructions } = await this.instructions(signal);
+        const retryNote = attempt === 1 ? "" : "\n\nA previous attempt did not resolve this issue \u2014 the sensor still reports it. Look again and try a different approach.";
+        const where = signalWhere(signal) || signal.message;
+        iteration++;
+        await log.step(
+          `agent fixing ${where} (iteration ${iteration})`,
+          () => config.agent.executeAgent(instructions + retryNote + (0, import_sandbox.memoryNote)(memory), ctx)
+        );
+      }
+      const stillPresent = new Set((await log.step("re-sensing to verify", sense)).map(import_claims.signalKey));
+      remaining = remaining.filter((signal) => stillPresent.has((0, import_claims.signalKey)(signal)));
+    }
+    return remaining;
+  }
+}
+function signalWhere(signal) {
+  const { location } = signal;
+  if (!location) return "";
+  return `${location.file}${location.line ? `:${location.line}` : ""}`;
+}
+function prTitle(label, fixed) {
+  return fixed.length === 1 ? `fix: ${fixed[0].message}` : `fix: ${label}: ${fixed.length} issues`;
+}
+function prBody(label, fixed) {
+  const lines = fixed.map((signal) => {
+    const where = signalWhere(signal);
+    const priority = signal.priority ? ` (${signal.priority})` : "";
+    return `- ${where ? `\`${where}\` \u2014 ` : ""}${signal.message}${priority}`;
+  });
+  return [
+    `Automated fix opened by the **${label}** control loop.`,
+    "",
+    "Signals resolved (verified by re-running the sensor):",
+    ...lines,
+    "",
+    (0, import_claims.claimMarker)(fixed)
+  ].join("\n");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Actuator,
+  AgentPrActuator,
+  fromFile,
+  fromSignal,
+  prComments
+});
+//# sourceMappingURL=actuators.js.map

package/dist/actuators.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/actuators.ts"],
+  "sourcesContent": ["import { readFile } from \"node:fs/promises\";\nimport type { Sandbox } from \"@daytona/sdk\";\nimport type { AgentContext } from \"./agents\";\nimport type { PrComment } from \"./github\";\nimport type { RunLog } from \"./log\";\nimport type {\n  CommentActuator,\n  ControlLoopConfig,\n  ControlLoopRunResult,\n  InstructionBuilder,\n  Signal,\n} from \"./types\";\nimport { claimMarker, signalKey } from \"./claims\";\nimport {\n  REPO_PATH,\n  SCRATCH_DIR,\n  commitAll,\n  memoryNote,\n  readMemory,\n  runConfiguredCommand,\n} from \"./sandbox\";\n\n/**\n * Actuator that reads a local file (markdown, plain text, ...) and uses its contents\n * as the instructions for every signal, with the signal's details appended. The file\n * is read once per process and cached.\n */\nexport const fromFile = (localPath: string): InstructionBuilder => {\n  let cached: string | undefined;\n  return async (signal) => {\n    cached ??= await readFile(localPath, \"utf-8\");\n    const where = signal.location\n      ? `In ${signal.location.file}${signal.location.line ? ` around line ${signal.location.line}` : \"\"}: \\n`\n      : \"\";\n    return {\n      instructions: `${where}${cached.trimEnd()}\\n\\n${signalContext(signal)}`,\n    };\n  };\n};\n\n/** Minimal instruction builder: instructions built from the signal itself, nothing else. */\nexport const fromSignal = (): InstructionBuilder => (signal) => ({\n  instructions: [\n    \"Fix the following issue detected in this codebase. Make the smallest change that resolves it;\",\n    \"do not fix unrelated issues or refactor unrelated code.\",\n    \"\",\n    signalContext(signal),\n  ].join(\"\\n\"),\n});\n\nfunction signalContext(signal: Signal): string {\n  const lines = [\"Issue to fix:\"];\n  if (signal.location) {\n    const { file, line } = signal.location;\n    lines.push(`- Location: ${line ? `${file}:${line}` : file}`);\n  }\n  lines.push(`- Description: ${signal.message}`);\n  if (signal.priority) lines.push(`- Priority: ${signal.priority}`);\n  return lines.join(\"\\n\");\n}\n\n/** Default comment actuator used by `applyPrComments` when none is configured. */\nexport const prComments: CommentActuator = (comments: PrComment[]) => {\n  const lines = comments.map((comment) =>\n    comment.file\n      ? `- ${comment.author} on \\`${comment.file}${comment.line ? `:${comment.line}` : \"\"}\\`: ${comment.body}`\n      : `- ${comment.author} (PR-level): ${comment.body}`,\n  );\n  return {\n    instructions: [\n      \"You are addressing review comments left on a pull request. Apply each comment's feedback to the code.\",\n      \"Keep changes minimal and scoped to what the comments ask \u2014 do not refactor or fix anything else.\",\n      \"\",\n      \"Comments to address:\",\n      ...lines,\n    ].join(\"\\n\"),\n  };\n};\n\n/**\n * Everything an actuator needs to act on the run's picked signals. The sandbox is fully\n * provisioned (repo cloned, git configured, `config.hooks.setup` already run).\n *\n * Note `sandbox` is exposed directly \u2014 unlike agents, which only ever see {@link AgentContext} \u2014\n * because an actuator is the layer allowed to drive git (branch, push) and open PRs.\n */\nexport interface ActuatorInput<TData = unknown> {\n  /** The signals the picker selected to act on this run. */\n  signals: Signal<TData>[];\n  /** The provisioned sandbox. */\n  sandbox: Sandbox;\n  /** Narrow exec/writeFile surface into the sandbox, with the repo root as cwd. */\n  ctx: AgentContext;\n  /** Re-runs the sensor \u2014 actuators that fix-then-verify use this to confirm resolution. */\n  sense: () => Promise<Signal<TData>[]>;\n  /** The loop's static configuration. */\n  config: ControlLoopConfig;\n  /** Slugified loop label \u2014 used for the branch, PR label, and memory file. */\n  label: string;\n  /** Human-readable loop label \u2014 used in PR titles and bodies. */\n  displayLabel: string;\n  /** The run's logger. */\n  log: RunLog;\n}\n\n/**\n * Owns the \"act on the picked signals\" step of a run and reports the outcome. The loop\n * senses, filters, and picks; the actuator decides what actually happens next.\n *\n * The default {@link AgentPrActuator} runs a coding agent per signal, verifies via\n * re-sensing, and opens a PR \u2014 but an actuator is free to do anything (post a message,\n * write a report, call an API) and need not touch an agent or open a PR at all.\n */\nexport abstract class Actuator<TData = unknown> {\n  abstract act(input: ActuatorInput<TData>): Promise<ControlLoopRunResult<TData>>;\n}\n\nexport interface AgentPrActuatorProps {\n  /** Builds the agent's instructions per signal. Defaults to {@link fromSignal}. */\n  instructions?: InstructionBuilder;\n}\n\n/**\n * The default actuator: for each picked signal it runs the configured coding agent, then\n * re-senses to verify the signal is gone (retrying up to `config.maxFixAttempts`), and\n * finally commits every fix to a fresh branch and opens one PR \u2014 claiming the signals it\n * fixed in the PR body so concurrent runs don't duplicate the work.\n *\n * This is the behavior the loop used to hard-code; it's now a swappable actuator.\n */\nexport class AgentPrActuator<TData = unknown> extends Actuator<TData> {\n  private readonly instructions: InstructionBuilder;\n\n  constructor(props: AgentPrActuatorProps = {}) {\n    super();\n    this.instructions = props.instructions ?? fromSignal();\n  }\n\n  async act(input: ActuatorInput<TData>): Promise<ControlLoopRunResult<TData>> {\n    const { signals: picked, sandbox, ctx, sense, config, log, label, displayLabel } = input;\n\n    const prefix = (config.branchPrefix ?? \"control-loop\").replace(/\\/+$/, \"\");\n    const branch = `${prefix}/${label}-${Date.now().toString(36)}`;\n    await log.step(`checking out branch ${branch}`, async () => {\n      await sandbox.git.createBranch(REPO_PATH, branch);\n      await sandbox.git.checkoutBranch(REPO_PATH, branch);\n    });\n\n    await log.step(\"preparing agent\", () => config.agent.prepare(ctx));\n\n    const memory = await readMemory(ctx, label);\n    const unresolved = await this.runFixLoop(picked, ctx, sense, memory, log, config);\n    if (unresolved.length > 0) {\n      log.finish(`fix failed \u2014 ${unresolved.length} signal(s) still present`);\n      return { status: \"fix-failed\", unresolved };\n    }\n\n    // The scratch dir holds prompts and sensor scripts; it must not end up in the PR.\n    await ctx.exec(`rm -rf ${SCRATCH_DIR}`);\n    await runConfiguredCommand(\"preCommit\", config, ctx, log);\n    await log.step(\"committing & pushing\", async () => {\n      await commitAll(ctx, prTitle(displayLabel, picked));\n      await config.git.push(sandbox, REPO_PATH, branch);\n    });\n\n    const prUrl = await log.step(\"opening pull request\", () =>\n      config.git.openPr({\n        branch,\n        label,\n        title: prTitle(displayLabel, picked),\n        body: prBody(displayLabel, picked),\n      }),\n    );\n    log.finish(`PR opened \u2192 ${prUrl}`);\n    return { status: \"pr-opened\", prUrl, fixed: picked };\n  }\n\n  /**\n   * Runs the agent on each signal, then re-senses to verify. Signals still reported\n   * by the sensor get retried (with a nudge appended) up to maxFixAttempts times.\n   */\n  private async runFixLoop(\n    picked: Signal<TData>[],\n    ctx: AgentContext,\n    sense: () => Promise<Signal<TData>[]>,\n    memory: string | undefined,\n    log: RunLog,\n    config: ControlLoopConfig,\n  ): Promise<Signal<TData>[]> {\n    const maxAttempts = config.maxFixAttempts ?? 3;\n    let remaining = picked;\n    let iteration = 0;\n\n    for (let attempt = 1; attempt <= maxAttempts && remaining.length > 0; attempt++) {\n      for (const signal of remaining) {\n        const { instructions } = await this.instructions(signal);\n        const retryNote =\n          attempt === 1\n            ? \"\"\n            : \"\\n\\nA previous attempt did not resolve this issue \u2014 the sensor still reports it. Look again and try a different approach.\";\n        const where = signalWhere(signal) || signal.message;\n        iteration++;\n        await log.step(`agent fixing ${where} (iteration ${iteration})`, () =>\n          config.agent.executeAgent(instructions + retryNote + memoryNote(memory), ctx),\n        );\n      }\n\n      const stillPresent = new Set((await log.step(\"re-sensing to verify\", sense)).map(signalKey));\n      remaining = remaining.filter((signal) => stillPresent.has(signalKey(signal)));\n    }\n\n    return remaining;\n  }\n}\n\n/** \"file:line\", \"file\", or \"\" \u2014 the human-readable location of a signal, if it has one. */\nfunction signalWhere(signal: Signal): string {\n  const { location } = signal;\n  if (!location) return \"\";\n  return `${location.file}${location.line ? `:${location.line}` : \"\"}`;\n}\n\nfunction prTitle(label: string, fixed: Signal[]): string {\n  return fixed.length === 1 ? `fix: ${fixed[0]!.message}` : `fix: ${label}: ${fixed.length} issues`;\n}\n\nfunction prBody(label: string, fixed: Signal[]): string {\n  const lines = fixed.map((signal) => {\n    const where = signalWhere(signal);\n    const priority = signal.priority ? ` (${signal.priority})` : \"\";\n    return `- ${where ? `\\`${where}\\` \u2014 ` : \"\"}${signal.message}${priority}`;\n  });\n  return [\n    `Automated fix opened by the **${label}** control loop.`,\n    \"\",\n    \"Signals resolved (verified by re-running the sensor):\",\n    ...lines,\n    \"\",\n    claimMarker(fixed),\n  ].join(\"\\n\");\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/agents.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The slice of the sandbox an agent is allowed to touch. Commands run with the repo
+ * root as cwd; file paths are relative to the repo root.
+ */
+export interface AgentContext {
+    exec: (command: string, options?: {
+        env?: Record<string, string>;
+        timeoutSec?: number;
+    }) => Promise<{
+        exitCode: number;
+        output: string;
+    }>;
+    writeFile: (path: string, content: string) => Promise<void>;
+}
+/**
+ * A coding agent that can be driven headlessly inside the sandbox. Implementations
+ * know how to install their own CLI and how to invoke it with a prompt.
+ */
+export declare abstract 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.
+     */
+    prepare(_ctx: AgentContext): Promise<void>;
+    /** Runs the agent against the repo with the given instructions, applying edits in place. */
+    abstract executeAgent(instructions: string, ctx: AgentContext): Promise<void>;
+}
+export type ClaudeProps = {
+    apiKey: string;
+    /** e.g. "claude-sonnet-5". Defaults to the CLI's default model. */
+    model?: string;
+    /** Max seconds for one agent invocation. Default 900. */
+    timeoutSec?: number;
+};
+export declare class Claude extends Agent {
+    private readonly props;
+    constructor(props: ClaudeProps);
+    prepare(ctx: AgentContext): Promise<void>;
+    executeAgent(instructions: string, ctx: AgentContext): Promise<void>;
+}
+export type CodexProps = {
+    apiKey: string;
+    /** e.g. "gpt-5.1-codex". Defaults to the CLI's default model. */
+    model?: string;
+    /** Max seconds for one agent invocation. Default 900. */
+    timeoutSec?: number;
+};
+export declare class Codex extends Agent {
+    private readonly props;
+    constructor(props: CodexProps);
+    prepare(ctx: AgentContext): Promise<void>;
+    executeAgent(instructions: string, ctx: AgentContext): Promise<void>;
+}