@bpinternal/overwatch 0.1.0

package/dist/control-loop.js

@@ -0,0 +1,285 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var control_loop_exports = {};
+__export(control_loop_exports, {
+  ControlLoop: () => ControlLoop
+});
+module.exports = __toCommonJS(control_loop_exports);
+var import_sdk = require("@daytona/sdk");
+var import_repo_handle = require("./repo-handle");
+var import_log = require("./log");
+var actuators = __toESM(require("./actuators"));
+var pickers = __toESM(require("./pickers"));
+var import_cli = require("./cli");
+var import_claims = require("./claims");
+var import_sandbox = require("./sandbox");
+const BOT_NAME = "control-loop[bot]";
+const DEFAULT_BOT_EMAIL = "control-loop@users.noreply.github.com";
+class ControlLoop {
+  constructor(options) {
+    this.options = options;
+  }
+  /**
+   * 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.
+   */
+  async run() {
+    const { config, sensor, picker } = this.options;
+    const label = slugify(this.options.label);
+    const log = new import_log.RunLog(this.options.label);
+    const maxOpenPrCount = config.maxOpenPrCount;
+    if (maxOpenPrCount !== void 0) {
+      const openPrCount = await config.git.countOpenPrs(label);
+      if (openPrCount >= maxOpenPrCount) {
+        const reason = `${openPrCount} open PR(s) labeled "${label}" (max ${maxOpenPrCount})`;
+        log.skip(reason);
+        return { status: "skipped", reason };
+      }
+    }
+    return this.withProvisionedSandbox(log, async (sandbox, ctx) => {
+      const sense = makeSensorRunner(sensor, sandbox, ctx);
+      const sensed = await log.step("sensing for signals", sense);
+      if (sensed.length === 0) {
+        log.finish("clean \u2014 no signals detected");
+        return { status: "clean" };
+      }
+      log.info(`sensed ${sensed.length} signal(s)`);
+      const claimed = new Set(
+        (await config.git.listOpenPrBodies(label)).flatMap(import_claims.parseClaimedKeys)
+      );
+      const signals = sensed.filter((signal) => !claimed.has((0, import_claims.signalKey)(signal)));
+      if (signals.length < sensed.length) {
+        log.info(`${sensed.length - signals.length} signal(s) already claimed by open PRs`);
+      }
+      if (signals.length === 0) {
+        log.finish("all sensed signals are already claimed by open PRs");
+        return { status: "skipped", reason: "all sensed signals are claimed by open PRs" };
+      }
+      const picked = await (picker ?? pickers.count(1))(signals);
+      if (picked.length === 0) {
+        log.finish("clean \u2014 picker selected nothing");
+        return { status: "clean" };
+      }
+      log.info(`picked ${picked.length} of ${signals.length} signal(s) to act on`);
+      return this.options.actuator.act({
+        signals: picked,
+        sandbox,
+        ctx,
+        sense,
+        config,
+        label,
+        displayLabel: this.options.label,
+        log
+      });
+    });
+  }
+  /**
+   * 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.
+   */
+  async withProvisionedSandbox(log, fn, branch) {
+    const { config } = this.options;
+    const sandbox = await log.step("spinning up sandbox", () => createSandbox(config));
+    log.attach(sandbox.id);
+    try {
+      await log.step(`cloning ${branch ?? config.git.branch} into ${import_sandbox.REPO_PATH}`, async () => {
+        await config.git.cloneInto(sandbox, import_sandbox.REPO_PATH, branch);
+        await sandbox.git.configureUser(BOT_NAME, config.git.email ?? DEFAULT_BOT_EMAIL, "local", import_sandbox.REPO_PATH);
+      });
+      const ctx = makeAgentContext(sandbox);
+      await ctx.exec(`mkdir -p ${import_sandbox.SCRATCH_DIR}`);
+      await (0, import_sandbox.runConfiguredCommand)("setup", config, ctx, log);
+      return await fn(sandbox, ctx);
+    } finally {
+      await log.step("tearing down sandbox", () => sandbox.delete());
+    }
+  }
+  /**
+   * 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.
+   */
+  async saveSnapshot(name) {
+    const log = new import_log.RunLog(this.options.label);
+    await this.withProvisionedSandbox(log, async (sandbox, ctx) => {
+      await ctx.exec(`rm -rf ${import_sandbox.SCRATCH_DIR}`);
+      await log.step(`saving snapshot ${name}`, () => sandbox._experimental_createSnapshot(name, 0));
+      log.finish(`snapshot saved \u2192 ${name}`);
+    });
+  }
+  /**
+   * 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.
+   */
+  async applyPrComments(prNumber) {
+    const { config, commentActuator } = this.options;
+    const label = slugify(this.options.label);
+    const log = new import_log.RunLog(`${this.options.label} \xB7 PR #${prNumber}`);
+    const pr = await config.git.getPr(prNumber);
+    const newComments = (await config.git.listPrComments(prNumber)).filter(
+      (comment) => new Date(comment.createdAt) > new Date(pr.headCommittedAt)
+    );
+    if (newComments.length === 0) {
+      log.skip("no comments newer than the PR head");
+      return { status: "no-new-comments" };
+    }
+    const comments = newComments.map(
+      (comment) => isFeedback(comment) ? { ...comment, body: stripFeedbackPrefix(comment.body) } : comment
+    );
+    const feedback = comments.filter((_, index) => isFeedback(newComments[index]));
+    log.info(`applying ${comments.length} new comment(s)`);
+    return this.withProvisionedSandbox(
+      log,
+      async (sandbox, ctx) => {
+        await log.step("preparing agent", () => config.agent.prepare(ctx));
+        const memory = await (0, import_sandbox.readMemory)(ctx, label);
+        if (feedback.length > 0) {
+          await (0, import_sandbox.appendMemory)(ctx, label, memory, feedback);
+        }
+        const { instructions } = await (commentActuator ?? actuators.prComments)(comments);
+        await log.step(
+          "agent applying comments",
+          () => config.agent.executeAgent(instructions + (0, import_sandbox.memoryNote)(memory), ctx)
+        );
+        await ctx.exec(`rm -rf ${import_sandbox.SCRATCH_DIR}`);
+        await (0, import_sandbox.runConfiguredCommand)("preCommit", config, ctx, log);
+        const status = await ctx.exec("git status --porcelain");
+        if (status.output.trim() === "") {
+          log.finish("no changes \u2014 agent left the tree untouched");
+          return { status: "no-changes", comments };
+        }
+        await log.step("committing & pushing", async () => {
+          await (0, import_sandbox.commitAll)(ctx, "fix: address PR review comments");
+          await config.git.push(sandbox, import_sandbox.REPO_PATH, pr.branch);
+        });
+        log.finish(`comments applied to ${pr.branch}`);
+        return { status: "comments-applied", branch: pr.branch, comments };
+      },
+      pr.branch
+    );
+  }
+  /**
+   * 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 = process.argv) {
+    return (0, import_cli.runCli)(this, { name: slugify(this.options.label), description: this.options.label }, argv);
+  }
+}
+const HIGH_RESOURCES = { cpu: 4, memory: 8, disk: 10 };
+async function createSandbox(config) {
+  const daytona = new import_sdk.Daytona();
+  if (config.sandbox?.snapshot) {
+    return daytona.create({ snapshot: config.sandbox.snapshot, envVars: config.env });
+  }
+  return daytona.create(
+    { image: "daytonaio/sandbox:latest", resources: HIGH_RESOURCES, envVars: config.env },
+    { timeout: 300 }
+  );
+}
+function makeAgentContext(sandbox) {
+  return {
+    exec: async (command, options) => {
+      const response = await sandbox.process.executeCommand(
+        command,
+        import_sandbox.REPO_PATH,
+        options?.env,
+        options?.timeoutSec ?? 300
+      );
+      return { exitCode: response.exitCode, output: response.result };
+    },
+    writeFile: async (path, content) => {
+      await sandbox.fs.uploadFile(Buffer.from(content), `${import_sandbox.REPO_PATH}/${path}`);
+    }
+  };
+}
+function makeSensorRunner(sensor, sandbox, ctx) {
+  if (typeof sensor === "function") {
+    const repo = new import_repo_handle.RepoHandle(sandbox, import_sandbox.REPO_PATH);
+    return () => sensor(repo);
+  }
+  const extension = sensor.localPath.endsWith(".js") ? ".js" : ".ts";
+  const scriptPath = `${import_sandbox.SCRATCH_DIR}/sensor${extension}`;
+  const signalsPath = `${import_sandbox.SCRATCH_DIR}/signals.json`;
+  let prepared = false;
+  return async () => {
+    if (!prepared) {
+      await sandbox.fs.uploadFile(sensor.localPath, `${import_sandbox.REPO_PATH}/${scriptPath}`);
+      await ctx.writeFile(
+        `${import_sandbox.SCRATCH_DIR}/run-sensor.ts`,
+        `import { writeFileSync } from "node:fs";
+const mod = await import("./sensor${extension}");
+const signals = await mod.default();
+writeFileSync("${signalsPath}", JSON.stringify(signals));
+`
+      );
+      const bun = await ctx.exec("command -v bun || npm install -g bun", { timeoutSec: 600 });
+      if (bun.exitCode !== 0)
+        throw new Error(`failed to install bun for the sensor script: ${bun.output}`);
+      prepared = true;
+    }
+    const run = await ctx.exec(`bun ${import_sandbox.SCRATCH_DIR}/run-sensor.ts`, { timeoutSec: 600 });
+    if (run.exitCode !== 0) throw new Error(`sensor script exited ${run.exitCode}: ${run.output}`);
+    const raw = await sandbox.fs.downloadFile(`${import_sandbox.REPO_PATH}/${signalsPath}`);
+    return JSON.parse(raw.toString("utf-8"));
+  };
+}
+function isFeedback(comment) {
+  return comment.body.trimStart().startsWith("/feedback");
+}
+function stripFeedbackPrefix(body) {
+  return body.trimStart().replace(/^\/feedback\s*/, "");
+}
+function slugify(label) {
+  return label.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ControlLoop
+});
+//# sourceMappingURL=control-loop.js.map

package/dist/control-loop.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/control-loop.ts"],
+  "sourcesContent": ["import { Daytona, type Sandbox } from \"@daytona/sdk\";\nimport type { AgentContext } from \"./agents\";\nimport type { PrComment } from \"./github\";\nimport { RepoHandle } from \"./repo-handle\";\nimport { RunLog } from \"./log\";\nimport * as actuators from \"./actuators\";\nimport * as pickers from \"./pickers\";\nimport { runCli } from \"./cli\";\nimport { parseClaimedKeys, signalKey } from \"./claims\";\nimport {\n  REPO_PATH,\n  SCRATCH_DIR,\n  appendMemory,\n  commitAll,\n  memoryNote,\n  readMemory,\n  runConfiguredCommand,\n} from \"./sandbox\";\nimport type { Sensor } from \"./sensors\";\nimport type {\n  ApplyCommentsResult,\n  ControlLoopConfig,\n  ControlLoopOptions,\n  ControlLoopRunResult,\n  Signal,\n} from \"./types\";\n\nconst BOT_NAME = \"control-loop[bot]\";\n/** Committer email for the loop's commits when the git source doesn't specify one. */\nconst DEFAULT_BOT_EMAIL = \"control-loop@users.noreply.github.com\";\n\nexport class ControlLoop<TData = unknown> {\n  constructor(private readonly options: ControlLoopOptions<TData>) {}\n\n  /**\n   * Executes one full cycle: sense -> pick -> run actuator -> verify -> PR.\n   * Invoke this from whatever scheduler you use (cron, CI); the loop itself\n   * does not stay resident.\n   */\n  async run(): Promise<ControlLoopRunResult<TData>> {\n    const { config, sensor, picker } = this.options;\n    const label = slugify(this.options.label);\n    const log = new RunLog(this.options.label);\n\n    const maxOpenPrCount = config.maxOpenPrCount;\n    if (maxOpenPrCount !== undefined) {\n      const openPrCount = await config.git.countOpenPrs(label);\n      if (openPrCount >= maxOpenPrCount) {\n        const reason = `${openPrCount} open PR(s) labeled \"${label}\" (max ${maxOpenPrCount})`;\n        log.skip(reason);\n        return { status: \"skipped\", reason };\n      }\n    }\n\n    return this.withProvisionedSandbox(log, async (sandbox, ctx) => {\n      const sense = makeSensorRunner(sensor, sandbox, ctx);\n\n      const sensed = await log.step(\"sensing for signals\", sense);\n      if (sensed.length === 0) {\n        log.finish(\"clean \u2014 no signals detected\");\n        return { status: \"clean\" };\n      }\n      log.info(`sensed ${sensed.length} signal(s)`);\n\n      // Signals already claimed by an open PR of this loop are excluded, so concurrent\n      // runs don't fix the same thing twice while earlier PRs await merge.\n      const claimed = new Set(\n        (await config.git.listOpenPrBodies(label)).flatMap(parseClaimedKeys),\n      );\n      const signals = sensed.filter((signal) => !claimed.has(signalKey(signal)));\n      if (signals.length < sensed.length) {\n        log.info(`${sensed.length - signals.length} signal(s) already claimed by open PRs`);\n      }\n      if (signals.length === 0) {\n        log.finish(\"all sensed signals are already claimed by open PRs\");\n        return { status: \"skipped\", reason: \"all sensed signals are claimed by open PRs\" };\n      }\n\n      const picked = await (picker ?? pickers.count<TData>(1))(signals);\n      if (picked.length === 0) {\n        log.finish(\"clean \u2014 picker selected nothing\");\n        return { status: \"clean\" };\n      }\n      log.info(`picked ${picked.length} of ${signals.length} signal(s) to act on`);\n\n      // The actuator owns everything past this point \u2014 what to do with the picked\n      // signals and how to report the outcome. The default `AgentPrActuator` runs the\n      // agent per signal and opens a PR; other actuators may do neither.\n      return this.options.actuator.act({\n        signals: picked,\n        sandbox,\n        ctx,\n        sense,\n        config,\n        label,\n        displayLabel: this.options.label,\n        log,\n      });\n    });\n  }\n\n  /**\n   * Creates a sandbox, clones `branch` (default: the base branch), configures git, and\n   * runs the `setup` hook \u2014 the provisioning every entry point shares \u2014 then invokes `fn`\n   * with the ready sandbox and its {@link AgentContext}. The sandbox is always torn down\n   * afterward, including when provisioning or `fn` throws.\n   */\n  private async withProvisionedSandbox<T>(\n    log: RunLog,\n    fn: (sandbox: Sandbox, ctx: AgentContext) => Promise<T>,\n    branch?: string,\n  ): Promise<T> {\n    const { config } = this.options;\n    const sandbox = await log.step(\"spinning up sandbox\", () => createSandbox(config));\n    log.attach(sandbox.id);\n\n    try {\n      await log.step(`cloning ${branch ?? config.git.branch} into ${REPO_PATH}`, async () => {\n        await config.git.cloneInto(sandbox, REPO_PATH, branch);\n        await sandbox.git.configureUser(BOT_NAME, config.git.email ?? DEFAULT_BOT_EMAIL, \"local\", REPO_PATH);\n      });\n\n      const ctx = makeAgentContext(sandbox);\n      await ctx.exec(`mkdir -p ${SCRATCH_DIR}`);\n\n      await runConfiguredCommand(\"setup\", config, ctx, log);\n\n      return await fn(sandbox, ctx);\n    } finally {\n      await log.step(\"tearing down sandbox\", () => sandbox.delete());\n    }\n  }\n\n  /**\n   * Provisions a sandbox the way {@link run} does up through the `setup` hook \u2014 clone,\n   * configure git, run `config.hooks.setup` \u2014 then captures its filesystem as a Daytona\n   * snapshot named `name` and returns, without sensing, touching the agent, or opening a\n   * PR. Pass the same `name` as `config.sandbox.snapshot` on later runs so they start from\n   * the baked-in toolchain instead of re-running `setup` every time.\n   *\n   * Call this instead of `run` (e.g. as a one-off provisioning step); `name` is required.\n   */\n  async saveSnapshot(name: string): Promise<void> {\n    const log = new RunLog(this.options.label);\n\n    await this.withProvisionedSandbox(log, async (sandbox, ctx) => {\n      // The scratch dir is per-run bookkeeping (prompts, sensor scripts); keep it out of\n      // the snapshot so it doesn't leak into runs created from it.\n      await ctx.exec(`rm -rf ${SCRATCH_DIR}`);\n\n      // 0 = no timeout: baking a real repo's toolchain can take well past the SDK's\n      // 60-second default.\n      await log.step(`saving snapshot ${name}`, () => sandbox._experimental_createSnapshot(name, 0));\n      log.finish(`snapshot saved \u2192 ${name}`);\n    });\n  }\n\n  /**\n   * Handler for PR comment events: reads the comments left on the PR since its last\n   * commit, has the agent apply them on the PR's branch, and pushes \u2014 updating the PR\n   * in place. Wire this to your webhook (or poller) for PR comment activity.\n   *\n   * Comments older than the PR's head commit are treated as already addressed, which\n   * makes repeated triggers for the same comment thread safe.\n   */\n  async applyPrComments(prNumber: number): Promise<ApplyCommentsResult> {\n    const { config, commentActuator } = this.options;\n    const label = slugify(this.options.label);\n    const log = new RunLog(`${this.options.label} \u00B7 PR #${prNumber}`);\n\n    const pr = await config.git.getPr(prNumber);\n    const newComments = (await config.git.listPrComments(prNumber)).filter(\n      (comment) => new Date(comment.createdAt) > new Date(pr.headCommittedAt),\n    );\n    if (newComments.length === 0) {\n      log.skip(\"no comments newer than the PR head\");\n      return { status: \"no-new-comments\" };\n    }\n\n    // \"/feedback ...\" comments are applied to the PR like any other, but their text is\n    // also persisted to the loop's memory file so every future run learns from them.\n    // The prefix is stripped so the agent sees plain instructions.\n    const comments = newComments.map((comment) =>\n      isFeedback(comment) ? { ...comment, body: stripFeedbackPrefix(comment.body) } : comment,\n    );\n    const feedback = comments.filter((_, index) => isFeedback(newComments[index]!));\n    log.info(`applying ${comments.length} new comment(s)`);\n\n    return this.withProvisionedSandbox(\n      log,\n      async (sandbox, ctx) => {\n        await log.step(\"preparing agent\", () => config.agent.prepare(ctx));\n\n        // Memory is read before appending, so the agent gets past feedback while the new\n        // feedback reaches it through the comments themselves.\n        const memory = await readMemory(ctx, label);\n        if (feedback.length > 0) {\n          await appendMemory(ctx, label, memory, feedback);\n        }\n\n        const { instructions } = await (commentActuator ?? actuators.prComments)(comments);\n        await log.step(\"agent applying comments\", () =>\n          config.agent.executeAgent(instructions + memoryNote(memory), ctx),\n        );\n\n        await ctx.exec(`rm -rf ${SCRATCH_DIR}`);\n        await runConfiguredCommand(\"preCommit\", config, ctx, log);\n        const status = await ctx.exec(\"git status --porcelain\");\n        if (status.output.trim() === \"\") {\n          log.finish(\"no changes \u2014 agent left the tree untouched\");\n          return { status: \"no-changes\", comments };\n        }\n\n        await log.step(\"committing & pushing\", async () => {\n          await commitAll(ctx, \"fix: address PR review comments\");\n          await config.git.push(sandbox, REPO_PATH, pr.branch);\n        });\n        log.finish(`comments applied to ${pr.branch}`);\n        return { status: \"comments-applied\", branch: pr.branch, comments };\n      },\n      pr.branch,\n    );\n  }\n\n  /**\n   * Ready-made CLI for driving this loop from CI (or a shell). Declare the loop, then call\n   * this once at the end of the file:\n   *\n   *     const loop = new ControlLoop({ ... });\n   *     loop.cli();\n   *\n   * Two subcommands: `run` (one full cycle \u2192 {@link run}) and `apply-comments <pr>`\n   * (apply new PR review comments \u2192 {@link applyPrComments}). Run with `--help` for usage.\n   * Parses `process.argv` by default; the process exits non-zero on error or an unresolved\n   * fix, so CI can gate on it.\n   */\n  cli(argv: string[] = process.argv): Promise<void> {\n    return runCli(this, { name: slugify(this.options.label), description: this.options.label }, argv);\n  }\n}\n\n/**\n * Every sandbox runs on a \"high\" machine: Daytona's default tier (1 vCPU / 1 GiB RAM\n * / 3 GiB disk) OOM-kills dependency installs on real repos (`setup` exiting 137),\n * and monorepo installs + an agent benefit from the extra headroom.\n */\nconst HIGH_RESOURCES = { cpu: 4, memory: 8, disk: 10 };\n\nasync function createSandbox(config: ControlLoopConfig): Promise<Sandbox> {\n  // Reads DAYTONA_API_KEY / DAYTONA_API_URL / DAYTONA_TARGET from the environment.\n  const daytona = new Daytona();\n\n  if (config.sandbox?.snapshot) {\n    // Daytona rejects resources when creating from a snapshot (\"Cannot specify Sandbox\n    // resources when using a snapshot\") \u2014 a snapshot's resources are baked in, so give\n    // yours a medium-or-bigger tier when creating it.\n    return daytona.create({ snapshot: config.sandbox.snapshot, envVars: config.env });\n  }\n\n  // Resources can only be requested for image-based creation. daytonaio/sandbox is the\n  // image behind Daytona's default snapshot (bun/node/git included); the built snapshot\n  // is cached by Daytona, so this is only slow the very first time.\n  return daytona.create(\n    { image: \"daytonaio/sandbox:latest\", resources: HIGH_RESOURCES, envVars: config.env },\n    { timeout: 300 },\n  );\n}\n\nfunction makeAgentContext(sandbox: Sandbox): AgentContext {\n  return {\n    exec: async (command, options) => {\n      const response = await sandbox.process.executeCommand(\n        command,\n        REPO_PATH,\n        options?.env,\n        options?.timeoutSec ?? 300,\n      );\n      return { exitCode: response.exitCode, output: response.result };\n    },\n    writeFile: async (path, content) => {\n      await sandbox.fs.uploadFile(Buffer.from(content), `${REPO_PATH}/${path}`);\n    },\n  };\n}\n\n/**\n * Normalizes both sensor flavors into a re-runnable `() => Promise<Signal[]>`.\n *\n * Script sensors are uploaded into the repo's scratch dir and executed with bun, with\n * the repo root as cwd. The generated runner writes the signals to a JSON file rather\n * than stdout, so the user's script is free to log without corrupting the result.\n */\nfunction makeSensorRunner<TData>(\n  sensor: Sensor<TData>,\n  sandbox: Sandbox,\n  ctx: AgentContext,\n): () => Promise<Signal<TData>[]> {\n  if (typeof sensor === \"function\") {\n    const repo = new RepoHandle(sandbox, REPO_PATH);\n    return () => sensor(repo);\n  }\n\n  const extension = sensor.localPath.endsWith(\".js\") ? \".js\" : \".ts\";\n  const scriptPath = `${SCRATCH_DIR}/sensor${extension}`;\n  const signalsPath = `${SCRATCH_DIR}/signals.json`;\n  let prepared = false;\n\n  return async () => {\n    if (!prepared) {\n      await sandbox.fs.uploadFile(sensor.localPath, `${REPO_PATH}/${scriptPath}`);\n      await ctx.writeFile(\n        `${SCRATCH_DIR}/run-sensor.ts`,\n        `import { writeFileSync } from \"node:fs\";\\n` +\n          `const mod = await import(\"./sensor${extension}\");\\n` +\n          `const signals = await mod.default();\\n` +\n          `writeFileSync(\"${signalsPath}\", JSON.stringify(signals));\\n`,\n      );\n      const bun = await ctx.exec(\"command -v bun || npm install -g bun\", { timeoutSec: 600 });\n      if (bun.exitCode !== 0)\n        throw new Error(`failed to install bun for the sensor script: ${bun.output}`);\n      prepared = true;\n    }\n\n    const run = await ctx.exec(`bun ${SCRATCH_DIR}/run-sensor.ts`, { timeoutSec: 600 });\n    if (run.exitCode !== 0) throw new Error(`sensor script exited ${run.exitCode}: ${run.output}`);\n    const raw = await sandbox.fs.downloadFile(`${REPO_PATH}/${signalsPath}`);\n    return JSON.parse(raw.toString(\"utf-8\")) as Signal<TData>[];\n  };\n}\n\nfunction isFeedback(comment: PrComment): boolean {\n  return comment.body.trimStart().startsWith(\"/feedback\");\n}\n\nfunction stripFeedbackPrefix(body: string): string {\n  return body.trimStart().replace(/^\\/feedback\\s*/, \"\");\n}\n\nfunction slugify(label: string): string {\n  return label\n    .toLowerCase()\n    .replace(/[^a-z0-9]+/g, \"-\")\n    .replace(/^-+|-+$/g, \"\");\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/github.d.ts

@@ -0,0 +1,98 @@
+import type { Sandbox } from "@daytona/sdk";
+/** A human comment on a PR. `file`/`line` are present for inline review comments only. */
+export interface PrComment {
+    id: number;
+    author: string;
+    body: string;
+    file?: string;
+    line?: number;
+    createdAt: string;
+}
+/**
+ * Where the code comes from and where the PR goes. Implemented by {@link Github};
+ * the interface exists so other forges (GitLab, ...) can slot in later.
+ */
+export interface GitSource {
+    /** Base branch the loop clones from and targets with its PR. */
+    readonly branch: string;
+    /**
+     * Committer email stamped on the loop's commits (the ones that make up the PR).
+     * Optional — the loop falls back to a default no-reply address when unset.
+     */
+    readonly email?: string;
+    countOpenPrs(label: string): Promise<number>;
+    /** Bodies of the open PRs carrying the loop's label; used to skip already-claimed signals. */
+    listOpenPrBodies(label: string): Promise<string[]>;
+    /** Clones `branch` (defaults to the base branch) into the sandbox at `path`. */
+    cloneInto(sandbox: Sandbox, path: string, branch?: string): Promise<void>;
+    push(sandbox: Sandbox, path: string, branch: string): Promise<void>;
+    openPr(params: {
+        branch: string;
+        title: string;
+        body: string;
+        label: string;
+    }): Promise<string>;
+    /** Head branch of the PR and the commit date of its tip, used to skip already-addressed comments. */
+    getPr(prNumber: number): Promise<{
+        branch: string;
+        headCommittedAt: string;
+    }>;
+    /**
+     * Comments on the PR — inline review comments and PR-level comments — oldest first.
+     * Inline comments whose review thread has been resolved are excluded.
+     */
+    listPrComments(prNumber: number): Promise<PrComment[]>;
+}
+export type GithubProps = {
+    /** e.g. "https://github.com/botpress/some-repo.git" */
+    repo: string;
+    branch: string;
+    /**
+     * GitHub token. Optional for cloning/counting PRs on public repos, but required to
+     * push and open PRs — a run that reaches the PR stage without one fails there.
+     */
+    key?: string;
+    /**
+     * Committer email stamped on the loop's commits. Optional; set it to attribute the
+     * PR's commits to a specific bot/user account instead of the default no-reply address.
+     */
+    email?: string;
+};
+export declare class Github implements GitSource {
+    readonly branch: string;
+    readonly email?: string;
+    private readonly repoUrl;
+    private readonly owner;
+    private readonly name;
+    private readonly key?;
+    private readonly octokit;
+    constructor(props: GithubProps);
+    countOpenPrs(label: string): Promise<number>;
+    listOpenPrBodies(label: string): Promise<string[]>;
+    private openPrIssues;
+    cloneInto(sandbox: Sandbox, path: string, branch?: string): Promise<void>;
+    getPr(prNumber: number): Promise<{
+        branch: string;
+        headCommittedAt: string;
+    }>;
+    listPrComments(prNumber: number): Promise<PrComment[]>;
+    push(sandbox: Sandbox, path: string, branch: string): Promise<void>;
+    openPr(params: {
+        branch: string;
+        title: string;
+        body: string;
+        label: string;
+    }): Promise<string>;
+    /** Retries a request a few times; the label call must not be abandoned over a transient error. */
+    private retry;
+    /** Best-effort PR close used to roll back a partially-created PR; a failure here is swallowed. */
+    private closePrQuietly;
+    private ensureLabel;
+    /**
+     * IDs of inline review comments whose thread has been resolved. Thread resolution
+     * is only exposed by GitHub's GraphQL API, which always requires auth — without a
+     * key, nothing is filtered.
+     */
+    private resolvedReviewCommentIds;
+    private requireKey;
+}