@app-vitals/agent-runtime 0.0.1 → 0.1.0

package/spawn-env.ts

@@ -0,0 +1,58 @@
+/**
+ * agent/src/runtime/spawn-env.ts
+ *
+ * Builds the extraEnv for a Claude spawn, adding the SHIPWRIGHT_GH_OWNER hint
+ * the `gh` wrapper uses to pick the matching App installation token (GOR-1.3).
+ *
+ *   - "loop": owner of the dispatched task or PR's repo
+ *   - "cron": the default org (pinned installation, else lowest installation id)
+ *   - "dm":   deliberately NO hint — a Slack DM is not tied to an org
+ *
+ * Observability: a loop or cron spawn that should carry the hint but has no
+ * resolvable owner logs ONE warn line. Spawns with an owner, and DM spawns,
+ * log nothing.
+ */
+
+import type { InstallationsSnapshot } from "./github-installations.ts";
+
+export type SpawnKind = "loop" | "cron" | "dm";
+
+interface BuildSpawnEnvOptions {
+  kind: SpawnKind;
+  /** Task id (loop) or cron job id (cron); named in the warn line. */
+  id?: string;
+  /** The resolved owner, if any. Ignored for "dm". */
+  owner?: string | null;
+  /** Existing env (e.g. SLACK_CHANNEL_ID) — preserved, never overwritten by an absent hint. */
+  extraEnv?: Record<string, string>;
+  warn?: (message: string) => void;
+}
+
+/**
+ * Returns extraEnv merged with SHIPWRIGHT_GH_OWNER when an owner is known.
+ * Returns the input extraEnv untouched (possibly undefined) otherwise.
+ */
+export function buildSpawnEnv(
+  opts: BuildSpawnEnvOptions,
+): Record<string, string> | undefined {
+  const { kind, id, owner, extraEnv, warn = console.warn } = opts;
+  if (kind === "dm") return extraEnv;
+  if (!owner) {
+    warn(
+      `[spawn-env] ${kind} spawn${id ? ` ${id}` : ""} has no resolvable GitHub owner — running without SHIPWRIGHT_GH_OWNER`,
+    );
+    return extraEnv;
+  }
+  return { ...extraEnv, SHIPWRIGHT_GH_OWNER: owner };
+}
+
+/** The default installation's owner login, or null when none is known. */
+export function defaultOwnerOf(
+  snapshot: InstallationsSnapshot | null | undefined,
+): string | null {
+  if (!snapshot || snapshot.defaultId === null) return null;
+  return (
+    snapshot.installations.find((i) => i.id === snapshot.defaultId)?.owner ??
+    null
+  );
+}

package/spawn-env.unit.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, test } from "bun:test";
+import { buildSpawnEnv, defaultOwnerOf } from "./spawn-env.ts";
+
+function collector() {
+  const lines: string[] = [];
+  return { lines, warn: (m: string) => lines.push(m) };
+}
+
+describe("buildSpawnEnv", () => {
+  test("loop-dispatched item carries its owner and preserves extraEnv", () => {
+    const c = collector();
+    const env = buildSpawnEnv({
+      kind: "loop",
+      id: "GOR-1.3",
+      owner: "acme",
+      extraEnv: { SLACK_CHANNEL_ID: "C1" },
+      warn: c.warn,
+    });
+    expect(env).toEqual({
+      SLACK_CHANNEL_ID: "C1",
+      SHIPWRIGHT_GH_OWNER: "acme",
+    });
+    expect(c.lines).toEqual([]);
+  });
+
+  test("cron without a repo carries the default org", () => {
+    const c = collector();
+    expect(
+      buildSpawnEnv({
+        kind: "cron",
+        id: "nightly",
+        owner: "default-org",
+        warn: c.warn,
+      }),
+    ).toEqual({ SHIPWRIGHT_GH_OWNER: "default-org" });
+    expect(c.lines).toEqual([]);
+  });
+
+  test("DM spawn carries no hint and logs nothing, even if an owner is passed", () => {
+    const c = collector();
+    expect(buildSpawnEnv({ kind: "dm", warn: c.warn })).toBeUndefined();
+    expect(
+      buildSpawnEnv({
+        kind: "dm",
+        owner: "acme",
+        extraEnv: { A: "b" },
+        warn: c.warn,
+      }),
+    ).toEqual({ A: "b" });
+    expect(c.lines).toEqual([]);
+  });
+
+  test("loop or cron spawn with no owner warns exactly once, naming kind and id", () => {
+    const c = collector();
+    const env = buildSpawnEnv({
+      kind: "loop",
+      id: "GOR-9.9",
+      extraEnv: { SLACK_CHANNEL_ID: "C1" },
+      warn: c.warn,
+    });
+    expect(env).toEqual({ SLACK_CHANNEL_ID: "C1" });
+    expect(c.lines).toHaveLength(1);
+    expect(c.lines[0]).toContain("loop");
+    expect(c.lines[0]).toContain("GOR-9.9");
+
+    buildSpawnEnv({ kind: "cron", id: "nightly", owner: null, warn: c.warn });
+    expect(c.lines).toHaveLength(2);
+    expect(c.lines[1]).toContain("cron");
+    expect(c.lines[1]).toContain("nightly");
+  });
+});
+
+describe("defaultOwnerOf", () => {
+  const inst = (id: number, owner: string | null) => ({
+    id,
+    owner,
+    pinned: false,
+    health: "ok" as const,
+    reason: null,
+  });
+  test("returns the default installation's owner", () => {
+    expect(
+      defaultOwnerOf({
+        installations: [inst(1, "a"), inst(2, "b")],
+        defaultId: 2,
+      }),
+    ).toBe("b");
+  });
+  test("null when there is no default or no snapshot", () => {
+    expect(defaultOwnerOf({ installations: [], defaultId: null })).toBeNull();
+    expect(defaultOwnerOf(null)).toBeNull();
+    expect(
+      defaultOwnerOf({ installations: [inst(1, null)], defaultId: 1 }),
+    ).toBeNull();
+  });
+});

package/startup-dm.integration.test.ts

@@ -0,0 +1,156 @@
+/**
+ * Integration tests for agent/src/runtime/startup-dm.ts
+ *
+ * Strategy: inject a typed mock WebClient — no mock.module(), no global overrides.
+ * Covers all three branches:
+ *  1. Happy path — conversations.open resolves with a valid channel.id → postMessage called
+ *  2. No channel-id — channel.id undefined → postMessage NOT called, no error
+ *  3. Slack API throws — caught, console.warn called, no crash
+ */
+
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import type { WebClient } from "@slack/web-api";
+import { sendBackOnlineDm } from "./startup-dm.ts";
+
+// ─── Mock WebClient factory ───────────────────────────────────────────────────
+
+function makeMockSlack(
+  overrides: {
+    conversationsOpenResult?: Awaited<
+      ReturnType<WebClient["conversations"]["open"]>
+    >;
+    conversationsOpenError?: Error;
+    postMessageResult?: Awaited<ReturnType<WebClient["chat"]["postMessage"]>>;
+  } = {},
+) {
+  const conversationsOpen = overrides.conversationsOpenError
+    ? mock(async (_args: unknown) => {
+        throw overrides.conversationsOpenError;
+      })
+    : mock(
+        async (_args: unknown) =>
+          overrides.conversationsOpenResult ?? {
+            ok: true,
+            channel: { id: "DM_CHAN_1" },
+          },
+      );
+
+  const postMessage = mock(async (_args: unknown) => ({
+    ok: true,
+    ts: "123.456",
+  }));
+
+  return {
+    conversations: { open: conversationsOpen },
+    chat: { postMessage },
+  } as unknown as WebClient;
+}
+
+// ─── Capture console.warn ─────────────────────────────────────────────────────
+
+let warnMessages: string[] = [];
+const originalWarn = console.warn.bind(console);
+
+beforeEach(() => {
+  warnMessages = [];
+  console.warn = (...args: unknown[]) => {
+    warnMessages.push(args.map(String).join(" "));
+  };
+});
+
+afterEach(() => {
+  console.warn = originalWarn;
+});
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe("sendBackOnlineDm — happy path", () => {
+  test("opens a DM and posts 'back online' when channel.id is present", async () => {
+    const slack = makeMockSlack();
+    await sendBackOnlineDm(slack, "U12345");
+
+    expect(slack.conversations.open).toHaveBeenCalledTimes(1);
+    expect(slack.conversations.open).toHaveBeenCalledWith({ users: "U12345" });
+
+    expect(slack.chat.postMessage).toHaveBeenCalledTimes(1);
+    expect(slack.chat.postMessage).toHaveBeenCalledWith({
+      channel: "DM_CHAN_1",
+      text: "back online",
+    });
+
+    expect(warnMessages.length).toBe(0);
+  });
+});
+
+describe("sendBackOnlineDm — no-channel-id branch", () => {
+  test("skips postMessage when conversations.open returns no channel.id", async () => {
+    const slack = makeMockSlack({
+      conversationsOpenResult: { ok: true, channel: { id: undefined } },
+    });
+    await sendBackOnlineDm(slack, "U12345");
+
+    expect(slack.conversations.open).toHaveBeenCalledTimes(1);
+    expect(slack.chat.postMessage).not.toHaveBeenCalled();
+    expect(warnMessages.length).toBe(0);
+  });
+
+  test("skips postMessage when conversations.open returns null channel", async () => {
+    const slack = makeMockSlack({
+      // biome-ignore lint/suspicious/noExplicitAny: testing undefined channel path
+      conversationsOpenResult: { ok: true, channel: null } as any,
+    });
+    await sendBackOnlineDm(slack, "U12345");
+
+    expect(slack.chat.postMessage).not.toHaveBeenCalled();
+    expect(warnMessages.length).toBe(0);
+  });
+
+  test("does nothing when ownerUser is undefined", async () => {
+    const slack = makeMockSlack();
+    await sendBackOnlineDm(slack, undefined);
+
+    expect(slack.conversations.open).not.toHaveBeenCalled();
+    expect(slack.chat.postMessage).not.toHaveBeenCalled();
+    expect(warnMessages.length).toBe(0);
+  });
+
+  test("does nothing when ownerUser is empty string", async () => {
+    const slack = makeMockSlack();
+    await sendBackOnlineDm(slack, "");
+
+    expect(slack.conversations.open).not.toHaveBeenCalled();
+    expect(slack.chat.postMessage).not.toHaveBeenCalled();
+    expect(warnMessages.length).toBe(0);
+  });
+});
+
+describe("sendBackOnlineDm — error-caught branch", () => {
+  test("catches Slack API error, warns, and does not crash", async () => {
+    const slack = makeMockSlack({
+      conversationsOpenError: new Error("channel_not_found"),
+    });
+
+    await expect(sendBackOnlineDm(slack, "U12345")).resolves.toBeUndefined();
+
+    expect(slack.chat.postMessage).not.toHaveBeenCalled();
+    expect(warnMessages.length).toBe(1);
+    expect(warnMessages[0]).toContain("back-online DM failed");
+    expect(warnMessages[0]).toContain("channel_not_found");
+  });
+
+  test("warns with non-Error thrown value as string", async () => {
+    const slack = {
+      conversations: {
+        open: mock(async (_args: unknown) => {
+          throw "string-error";
+        }),
+      },
+      chat: { postMessage: mock(async (_args: unknown) => ({})) },
+    } as unknown as WebClient;
+
+    await expect(sendBackOnlineDm(slack, "U12345")).resolves.toBeUndefined();
+
+    expect(warnMessages.length).toBe(1);
+    expect(warnMessages[0]).toContain("string-error");
+  });
+});

package/startup-dm.ts

@@ -0,0 +1,29 @@
+/**
+ * Sends a "back online" DM to the agent owner on startup.
+ *
+ * Non-fatal: silently skips if owner is not configured, channel-id is missing,
+ * or the Slack API throws. Extracted for testability.
+ */
+
+import type { WebClient } from "@slack/web-api";
+
+export async function sendBackOnlineDm(
+  slack: WebClient,
+  ownerUser: string | undefined,
+): Promise<void> {
+  if (!ownerUser) return;
+  try {
+    const dm = await slack.conversations.open({ users: ownerUser });
+    if (dm.channel?.id) {
+      await slack.chat.postMessage({
+        channel: dm.channel.id,
+        text: "back online",
+      });
+    }
+  } catch (err) {
+    console.warn(
+      "[agent] back-online DM failed (non-fatal):",
+      err instanceof Error ? err.message : String(err),
+    );
+  }
+}

package/sync-config-clone.ts

@@ -0,0 +1,238 @@
+/**
+ * agent/src/runtime/sync-config-clone.ts
+ *
+ * Auto-clones newly-configured repos on config sync (RSF-4.1).
+ *
+ * index.ts's syncConfig() tick (runs every 60s) fetches the agent's config
+ * bundle and calls agentReposRef.set(bundle.repos) to update the in-memory
+ * scope — but historically did nothing to actually fetch a newly-added repo
+ * onto disk, leaving a human to clone it manually before any dev-task/review/
+ * patch/deploy work against it could proceed.
+ *
+ * This module reuses lib/clone-plan.ts's computeMissingClones() — the same
+ * pure, already-unit-tested planner already used by the manual
+ * agent-workspace-pull CLI and hitl.ts — against the real repos/ dir, and
+ * clones anything missing via `gh repo clone`. The planner lives in `lib/`
+ * (not `scripts/`) precisely because this module imports it: agent/Dockerfile's
+ * runtime stage copies `lib/` but not `scripts/`, so a `scripts/` import would
+ * resolve locally and then crash-loop the deployed pod.
+ *
+ * Kept deliberately simple (explicit product decision): the clone step runs
+ * within syncConfig()'s own tick, not backgrounded or queued — no new
+ * interval, no fire-and-forget dispatch. The `gh` child process itself is
+ * spawned *asynchronously* (`Bun.spawn` + `await proc.exited`, matching
+ * claude.ts's convention for long-running children) rather than with
+ * `Bun.spawnSync`: this runs inside the long-lived server process that also
+ * serves the liveness/readiness probes, and a synchronous clone would block
+ * that process's event loop for the full duration of the clone — long enough
+ * for a probe to fail and restart the pod mid-clone.
+ *
+ * Because the spawn is async, two syncConfig() ticks can now overlap (index.ts
+ * schedules them with a bare `setInterval`, which does not serialize), so an
+ * in-flight set guards against two ticks racing the same destination.
+ *
+ * A single repo's clone failure (auth hiccup, rate limit, invalid repo name,
+ * ...) is caught and logged per-repo — never thrown — so one bad repo can't
+ * block the rest of the plan or crash the tick; the partially-written
+ * destination is removed so the next tick's computeMissingClones() sees it as
+ * missing again and retries it, with no explicit retry/backoff logic needed.
+ */
+
+import { existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import {
+  computeMissingClones,
+  findRepoNameCollisions,
+} from "@app-vitals/agent-lib/clone-plan";
+import { ownerOfRepo } from "./gh-helpers.ts";
+
+export interface SyncConfigCloneDeps {
+  /**
+   * The agent's currently-configured repo scope ("org/repo" strings) — read
+   * fresh on every call (mirrors worktree-reaper.ts's own getScopedRepos
+   * doc comment) so a repo added between two ticks is picked up on the very
+   * next call without rebuilding deps.
+   */
+  getScopedRepos: () => string[];
+  /** Absolute path to the repos/ dir clones land in. */
+  reposDir: string;
+  /** Existence check for the clone-skip plan — injectable for tests. */
+  exists: (path: string) => boolean;
+  /** Clones a single repo ("org/repo") to `dest` via `gh repo clone`. */
+  cloneRepo: (repo: string, dest: string) => Promise<void>;
+  /**
+   * Deletes a destination directory left behind by a failed clone, so the
+   * next tick's computeMissingClones() plans it again instead of treating the
+   * half-written directory as an already-cloned repo.
+   */
+  removePartialClone: (dest: string) => void;
+  /**
+   * Returns the owner of an existing clone's `origin` remote, or null when it
+   * can't be determined. Optional — when omitted, no owner check is made.
+   */
+  getRemoteOwner?: (dest: string) => string | null;
+}
+
+/**
+ * Destinations with a clone in flight right now. Module-scoped (not per-deps)
+ * because the hazard it guards is process-wide: index.ts drives this with
+ * `setInterval(() => void syncConfig(), 60_000)`, which never waits for the
+ * previous tick, so a clone slower than 60s would otherwise be started a
+ * second time by the next tick before `gh` has created the destination dir.
+ */
+const inFlightClones = new Set<string>();
+
+/**
+ * Clones every configured-but-missing repo onto disk via computeMissingClones()'s
+ * plan. Already-present repos are left untouched — this reuses
+ * computeMissingClones()'s own skip-if-exists logic rather than
+ * re-implementing it.
+ *
+ * A single repo's cloneRepo() failure is caught and logged; it never prevents
+ * the remaining repos in the plan from being attempted, and it never throws
+ * out of this function — callers (index.ts's syncConfig()) can call this
+ * every tick without a wrapping try/catch of their own being load-bearing.
+ */
+export async function syncClonedRepos(
+  deps: SyncConfigCloneDeps,
+): Promise<void> {
+  const repos = deps.getScopedRepos();
+
+  // repos/<name> is keyed by basename only: skip the later-listed repo of any
+  // cross-owner name collision so it can never share (or push from) the
+  // earlier repo's folder.
+  const skipped = new Set<string>();
+  for (const { repo, collidesWith } of findRepoNameCollisions(repos)) {
+    skipped.add(repo);
+    console.error(
+      `[config-sync] repo name collision: ${repo} and ${collidesWith} share the folder name — skipping ${repo}`,
+    );
+  }
+
+  // An existing folder whose remote belongs to a different owner is the same
+  // hazard from the other direction (e.g. repos/<name> cloned for another org).
+  if (deps.getRemoteOwner) {
+    for (const repo of repos) {
+      if (skipped.has(repo)) continue;
+      const dest = join(deps.reposDir, repo.slice(repo.lastIndexOf("/") + 1));
+      if (!deps.exists(dest)) continue;
+      const actual = deps.getRemoteOwner(dest);
+      const expected = repo.slice(0, repo.lastIndexOf("/"));
+      if (actual && actual.toLowerCase() !== expected.toLowerCase()) {
+        skipped.add(repo);
+        console.error(
+          `[config-sync] repo name collision: ${dest} has a remote owned by ${actual}, not ${expected} — skipping ${repo}`,
+        );
+      }
+    }
+  }
+
+  const plan = computeMissingClones(
+    repos.filter((r) => !skipped.has(r)),
+    deps.reposDir,
+    deps.exists,
+  );
+
+  for (const { repo, dest } of plan) {
+    // An overlapping tick is already cloning this destination — skip rather
+    // than racing a second `gh repo clone` into the same directory.
+    if (inFlightClones.has(dest)) continue;
+    inFlightClones.add(dest);
+    try {
+      await deps.cloneRepo(repo, dest);
+    } catch (err) {
+      console.error(
+        `[config-sync] clone failed for ${repo}: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+      // Clear whatever the failed clone left on disk: a half-written
+      // directory still satisfies the planner's existence check and would
+      // otherwise wedge this repo as "cloned" forever.
+      try {
+        deps.removePartialClone(dest);
+      } catch (rmErr) {
+        console.error(
+          `[config-sync] failed to clean up partial clone at ${dest}: ${
+            rmErr instanceof Error ? rmErr.message : String(rmErr)
+          }`,
+        );
+      }
+    } finally {
+      inFlightClones.delete(dest);
+    }
+  }
+}
+
+/**
+ * Builds the real `gh repo clone` shell-out. Async by design — see the module
+ * header: `Bun.spawnSync` here would block the event loop of the process that
+ * serves the health probes for the whole duration of the clone.
+ *
+ * The spawner is injectable so unit tests can assert the command, the options
+ * and the exit-code handling without a real `gh` invocation (mirrors
+ * claude.ts's `spawner: typeof Bun.spawn = Bun.spawn` parameter).
+ */
+export function makeCloneRepo(
+  spawn: typeof Bun.spawn = Bun.spawn,
+): (repo: string, dest: string) => Promise<void> {
+  return async (repo: string, dest: string): Promise<void> => {
+    const proc = spawn(["gh", "repo", "clone", repo, dest], {
+      // env: process.env is required — Bun.spawn otherwise snapshots env at
+      // Bun startup and misses runtime mutations. This clone runs inside
+      // syncConfig()'s tick, right after Object.assign(process.env,
+      // bundle.env), so without this a freshly-synced/rotated GH_TOKEN never
+      // reaches `gh`. Mirrors setup.ts's defaultExec and cron-handler.ts,
+      // which document the same gotcha. SHIPWRIGHT_GH_OWNER (GOR-1.3) is the
+      // repo scope entry's org, layered over a fresh copy of process.env.
+      env: { ...process.env, SHIPWRIGHT_GH_OWNER: ownerOfRepo(repo) },
+      stdout: "inherit",
+      stderr: "inherit",
+    });
+    const exitCode = await proc.exited;
+    if (exitCode !== 0) {
+      throw new Error(`gh repo clone failed for ${repo} (exit ${exitCode})`);
+    }
+  };
+}
+
+/**
+ * Production deps for syncClonedRepos(): real existsSync, real async `gh repo
+ * clone` shell-out, real recursive delete for partial clones. `reposDir` is
+ * passed in by the caller (index.ts, via join(config.paths.workspace,
+ * "repos") — the repos dir convention confirmed by setup.ts/
+ * worktree-reaper.ts/pr-state-reconciler.ts/check-helpers.ts) rather than
+ * re-resolved here, so this module stays free of any direct
+ * process.env/AGENT_HOME dependency of its own.
+ */
+export function buildProductionDeps(opts: {
+  getScopedRepos: () => string[];
+  reposDir: string;
+}): SyncConfigCloneDeps {
+  return {
+    getScopedRepos: opts.getScopedRepos,
+    reposDir: opts.reposDir,
+    exists: existsSync,
+    cloneRepo: makeCloneRepo(),
+    removePartialClone: (dest: string) =>
+      rmSync(dest, { recursive: true, force: true }),
+    getRemoteOwner: readRemoteOwner,
+  };
+}
+
+/**
+ * Parses the owner out of a clone's `origin` URL (https or ssh form); null
+ * when the folder has no readable origin.
+ */
+export function readRemoteOwner(
+  dest: string,
+  spawnSync: typeof Bun.spawnSync = Bun.spawnSync,
+): string | null {
+  const proc = spawnSync(["git", "-C", dest, "remote", "get-url", "origin"]);
+  if (proc.exitCode !== 0) return null;
+  const m = proc.stdout
+    .toString()
+    .trim()
+    .match(/[:/]([^/:]+)\/[^/]+?(?:\.git)?$/);
+  return m?.[1] ?? null;
+}