@app-vitals/agent-runtime 0.0.1 → 0.1.0

package/github-installations-manager.integration.test.ts

@@ -0,0 +1,323 @@
+/**
+ * Integration tests for GitHubInstallationsManager with injected auth,
+ * fetchFn, Clock and a fake setIntervalFn. No real network or timers.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, spyOn } from "bun:test";
+import {
+  GitHubInstallationsManager,
+  type InstallationEvent,
+  type InstallationsSnapshot,
+} from "./github-installations.ts";
+
+const SECRET_TOKEN = "ghs_SECRET_TOKEN_VALUE";
+const SECRET_JWT = "eyJ.SECRET.JWT";
+
+type Raw = { id: number; owner: string; suspended?: boolean };
+
+function makeHarness(opts: { pinnedId?: number } = {}) {
+  let installs: Raw[] = [];
+  let discoveryStatus = 200;
+  const mintBehavior = new Map<number, number | "network">(); // id -> failure
+  const mintCalls: number[] = [];
+  let mintSeq = 0;
+  const events: InstallationEvent[] = [];
+  const changes: InstallationsSnapshot[] = [];
+  const intervals: { fn: () => void; ms: number; cleared: boolean }[] = [];
+
+  const auth = async (p?: { type: string; installationId?: number }) => {
+    if (!p) throw new Error("no params");
+    if (p.type === "app")
+      return {
+        token: SECRET_JWT,
+        expiresAt: "",
+        type: "app",
+        tokenType: "app",
+      };
+    const id = p.installationId as number;
+    mintCalls.push(id);
+    const fail = mintBehavior.get(id);
+    if (fail === "network") throw new Error("socket hang up");
+    if (fail) throw Object.assign(new Error("mint rejected"), { status: fail });
+    return {
+      token: `${SECRET_TOKEN}_${id}_${++mintSeq}`,
+      expiresAt: new Date(Date.UTC(2030, 0, 1)).toISOString(),
+      type: "token",
+      tokenType: "installation",
+    };
+  };
+  const fetchFn = (async () =>
+    new Response(
+      JSON.stringify(
+        installs.map((i) => ({
+          id: i.id,
+          account: { login: i.owner },
+          suspended_at: i.suspended ? "2026-01-01T00:00:00Z" : null,
+        })),
+      ),
+      { status: discoveryStatus },
+    )) as unknown as typeof fetch;
+  const setIntervalFn = ((fn: () => void, ms: number) => {
+    const rec = { fn, ms, cleared: false };
+    intervals.push(rec);
+    return rec as unknown as ReturnType<typeof setInterval>;
+  }) as unknown as typeof setInterval;
+  const clearIntervalFn = ((h: { cleared: boolean }) => {
+    h.cleared = true;
+  }) as unknown as typeof clearInterval;
+
+  const manager = new GitHubInstallationsManager({
+    auth,
+    fetchFn,
+    clock: { now: () => new Date(Date.UTC(2029, 0, 1)) },
+    setIntervalFn,
+    clearIntervalFn,
+    pinnedId: opts.pinnedId,
+    onEvent: (e) => events.push(e),
+    onChange: (s) => changes.push(s),
+  });
+  return {
+    manager,
+    events,
+    changes,
+    intervals,
+    mintCalls,
+    mintBehavior,
+    setInstalls: (i: Raw[]) => {
+      installs = i;
+    },
+    setDiscoveryStatus: (s: number) => {
+      discoveryStatus = s;
+    },
+  };
+}
+
+describe("GitHubInstallationsManager", () => {
+  let logSpy: ReturnType<typeof spyOn>;
+  let errSpy: ReturnType<typeof spyOn>;
+  let logged: string[];
+  beforeEach(() => {
+    logged = [];
+    logSpy = spyOn(console, "log").mockImplementation((...a) => {
+      logged.push(a.map(String).join(" "));
+    });
+    errSpy = spyOn(console, "error").mockImplementation((...a) => {
+      logged.push(a.map(String).join(" "));
+    });
+  });
+  afterEach(() => {
+    logSpy.mockRestore();
+    errSpy.mockRestore();
+  });
+
+  it("creates exactly one interval for N installations", async () => {
+    const h = makeHarness();
+    h.setInstalls([
+      { id: 1, owner: "a" },
+      { id: 2, owner: "b" },
+      { id: 3, owner: "c" },
+    ]);
+    await h.manager.reconcile(["a", "b", "c"]);
+    h.manager.start();
+    h.manager.start();
+    expect(h.manager.getState().installations).toHaveLength(3);
+    expect(h.intervals).toHaveLength(1);
+    h.manager.stop();
+    expect(h.intervals[0].cleared).toBe(true);
+  });
+
+  it("a broken installation does not affect the others' tokens", async () => {
+    const h = makeHarness();
+    h.setInstalls([
+      { id: 1, owner: "a" },
+      { id: 2, owner: "b" },
+    ]);
+    h.mintBehavior.set(1, 403);
+    await h.manager.reconcile(["a", "b"]);
+    await h.manager.refresh();
+    const byId = new Map(
+      h.manager.getState().installations.map((i) => [i.id, i]),
+    );
+    expect(byId.get(1)?.health).toBe("broken");
+    expect(byId.get(1)?.reason).toBe("mint_rejected");
+    expect(byId.get(2)?.health).toBe("ok");
+    expect(await h.manager.getToken(2)).toContain("_2_");
+    await expect(h.manager.getToken(1)).rejects.toThrow("broken");
+    // broken installation is no longer retried on later ticks
+    h.mintCalls.length = 0;
+    await h.manager.refresh();
+    expect(h.mintCalls).not.toContain(1);
+  });
+
+  it("treats suspended installations as broken without minting", async () => {
+    const h = makeHarness();
+    h.setInstalls([{ id: 1, owner: "a", suspended: true }]);
+    await h.manager.reconcile(["a"]);
+    await h.manager.refresh();
+    expect(h.manager.getState().installations[0]).toMatchObject({
+      health: "broken",
+      reason: "suspended",
+    });
+    expect(h.mintCalls).toHaveLength(0);
+  });
+
+  it("recovers a suspended installation after it is unsuspended", async () => {
+    const h = makeHarness();
+    h.setInstalls([{ id: 1, owner: "a", suspended: true }]);
+    await h.manager.reconcile(["a"]);
+    await h.manager.refresh();
+    expect(h.manager.getState().installations[0]).toMatchObject({
+      health: "broken",
+      reason: "suspended",
+    });
+    h.setInstalls([{ id: 1, owner: "a" }]);
+    await h.manager.reconcile(["a"]);
+    await h.manager.refresh();
+    expect(h.manager.getState().installations[0]).toMatchObject({
+      health: "ok",
+      reason: null,
+    });
+    expect(h.mintCalls).toEqual([1]);
+    expect(await h.manager.getToken(1)).toContain("_1_");
+  });
+
+  it("marks 404/422 broken but keeps 5xx and network errors transient", async () => {
+    const h = makeHarness();
+    h.setInstalls([
+      { id: 1, owner: "a" },
+      { id: 2, owner: "b" },
+      { id: 3, owner: "c" },
+      { id: 4, owner: "d" },
+    ]);
+    h.mintBehavior.set(1, 404);
+    h.mintBehavior.set(2, 422);
+    h.mintBehavior.set(3, 503);
+    h.mintBehavior.set(4, "network");
+    await h.manager.reconcile(["a", "b", "c", "d"]);
+    await h.manager.refresh();
+    const health = Object.fromEntries(
+      h.manager.getState().installations.map((i) => [i.id, i.health]),
+    );
+    expect(health).toEqual({
+      1: "broken",
+      2: "broken",
+      3: "unknown",
+      4: "unknown",
+    });
+    // transient ones retry, and recover when the error clears
+    h.mintBehavior.delete(3);
+    await h.manager.refresh();
+    expect(
+      h.manager.getState().installations.find((i) => i.id === 3)?.health,
+    ).toBe("ok");
+    const failed = h.events.filter((e) => e.type === "mint_failed");
+    expect(
+      failed
+        .slice(0, 4)
+        .map((e) => (e.type === "mint_failed" ? e.statusClass : null)),
+    ).toEqual(["4xx", "4xx", "5xx", "network"]);
+  });
+
+  it("emits minted, mint_failed, discovered and removed events", async () => {
+    const h = makeHarness();
+    h.setInstalls([
+      { id: 1, owner: "a" },
+      { id: 2, owner: "b" },
+    ]);
+    h.mintBehavior.set(2, 500);
+    await h.manager.reconcile(["a", "b"]);
+    await h.manager.refresh();
+    h.setInstalls([{ id: 2, owner: "b" }]);
+    await h.manager.reconcile(["a", "b"]);
+    const types = new Set(h.events.map((e) => e.type));
+    expect(types).toEqual(
+      new Set(["discovered", "minted", "mint_failed", "removed"]),
+    );
+    expect(h.events).toContainEqual({ type: "removed", installationId: 1 });
+    expect(h.events).toContainEqual({ type: "minted", installationId: 1 });
+    expect(h.manager.getState().installations.map((i) => i.id)).toEqual([2]);
+  });
+
+  it("minted is emitted only when a new token is minted", async () => {
+    const h = makeHarness();
+    h.setInstalls([{ id: 1, owner: "a" }]);
+    await h.manager.reconcile(["a"]);
+    await h.manager.refresh();
+    await h.manager.refresh();
+    expect(h.events.filter((e) => e.type === "minted")).toHaveLength(1);
+  });
+
+  it("a discovery failure leaves the previous installation list in place", async () => {
+    const h = makeHarness();
+    h.setInstalls([{ id: 1, owner: "a" }]);
+    await h.manager.reconcile(["a"]);
+    h.setDiscoveryStatus(500);
+    await h.manager.reconcile(["a"]);
+    expect(h.manager.getState().installations.map((i) => i.id)).toEqual([1]);
+    expect(h.events).toContainEqual({ type: "discovery_failed" });
+    expect(h.events.some((e) => e.type === "removed")).toBe(false);
+  });
+
+  it("calls onChange only when state changes", async () => {
+    const h = makeHarness();
+    h.setInstalls([{ id: 1, owner: "a" }]);
+    await h.manager.reconcile(["a"]);
+    await h.manager.reconcile(["a"]);
+    expect(h.changes).toHaveLength(1);
+    await h.manager.refresh();
+    expect(h.changes).toHaveLength(2);
+    expect(h.changes[1].installations[0].health).toBe("ok");
+  });
+
+  it("never throws out of the timer, even when listeners or auth throw", async () => {
+    const h = makeHarness();
+    h.setInstalls([{ id: 1, owner: "a" }]);
+    await h.manager.reconcile(["a"]);
+    h.manager.start();
+    h.mintBehavior.set(1, 500);
+    expect(() => h.intervals[0].fn()).not.toThrow();
+    await h.manager.refresh();
+    const bad = new GitHubInstallationsManager({
+      auth: async () => {
+        throw new Error("jwt signing failed");
+      },
+      onEvent: () => {
+        throw new Error("listener boom");
+      },
+    });
+    await expect(bad.reconcile(["a"])).resolves.toBeUndefined();
+    await expect(bad.refresh()).resolves.toBeUndefined();
+  });
+
+  it("uses a pinned id before scope is synced", async () => {
+    const h = makeHarness({ pinnedId: 7 });
+    h.setInstalls([
+      { id: 7, owner: "a" },
+      { id: 8, owner: "b" },
+    ]);
+    await h.manager.reconcile(null);
+    expect(h.manager.getState()).toMatchObject({ defaultId: 7 });
+    expect(h.manager.getState().installations.map((i) => i.id)).toEqual([7]);
+  });
+
+  it("never exposes token or key material in logs or events", async () => {
+    const h = makeHarness();
+    h.setInstalls([
+      { id: 1, owner: "a" },
+      { id: 2, owner: "b" },
+    ]);
+    h.mintBehavior.set(2, 403);
+    await h.manager.reconcile(["a", "b"]);
+    await h.manager.refresh();
+    h.setDiscoveryStatus(500);
+    await h.manager.reconcile(["a", "b"]);
+    const blob = JSON.stringify([
+      h.events,
+      h.changes,
+      h.manager.getState(),
+      logged,
+    ]);
+    expect(blob).not.toContain("SECRET");
+    expect(blob).not.toContain("ghs_");
+  });
+});

package/github-installations-reporter.integration.test.ts

@@ -0,0 +1,124 @@
+/**
+ * Integration: GitHubInstallationsManager -> HttpGitHubInstallationsReporter.
+ * Real manager with injected auth/fetch/clock, reporter wired via onChange.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, spyOn } from "bun:test";
+import { GitHubInstallationsManager } from "./github-installations.ts";
+import { HttpGitHubInstallationsReporter } from "./github-installations-reporter.ts";
+
+const SECRET_TOKEN = "ghs_SECRET_TOKEN_VALUE";
+const SECRET_JWT = "eyJ.SECRET.JWT";
+
+function setup(opts: { reporterFetch?: typeof fetch } = {}) {
+  let mintFail: number | null = null;
+  let seq = 0;
+  const bodies: string[] = [];
+  const auth = async (p?: { type: string }) =>
+    p?.type === "app"
+      ? { token: SECRET_JWT, expiresAt: "", type: "app", tokenType: "app" }
+      : mintFail
+        ? Promise.reject(
+            Object.assign(new Error("rejected"), { status: mintFail }),
+          )
+        : {
+            token: `${SECRET_TOKEN}_${++seq}`,
+            expiresAt: new Date(Date.UTC(2030, 0, 1)).toISOString(),
+            type: "token",
+            tokenType: "installation",
+          };
+  const discovery = (async () =>
+    new Response(
+      JSON.stringify([
+        { id: 1, account: { login: "acme" }, suspended_at: null },
+      ]),
+    )) as unknown as typeof fetch;
+  const reporterFetch =
+    opts.reporterFetch ??
+    ((async (_u: RequestInfo | URL, init?: RequestInit) => {
+      bodies.push(String(init?.body));
+      return new Response("{}", { status: 200 });
+    }) as unknown as typeof fetch);
+  const clock = { now: () => new Date(Date.UTC(2029, 0, 1)) };
+  const reporter = new HttpGitHubInstallationsReporter({
+    apiUrl: "http://api",
+    agentId: "a1",
+    apiKey: "KEY",
+    fetchFn: reporterFetch,
+    clock,
+  });
+  const manager = new GitHubInstallationsManager({
+    auth: auth as never,
+    fetchFn: discovery,
+    clock,
+    onChange: (s) => void reporter.report(s),
+  });
+  return {
+    manager,
+    bodies,
+    setMintFail: (s: number | null) => {
+      mintFail = s;
+    },
+  };
+}
+
+describe("manager -> reporter", () => {
+  let spies: ReturnType<typeof spyOn>[];
+  beforeEach(() => {
+    spies = [
+      spyOn(console, "log").mockImplementation(() => {}),
+      spyOn(console, "error").mockImplementation(() => {}),
+      spyOn(console, "warn").mockImplementation(() => {}),
+    ];
+  });
+  afterEach(() => {
+    for (const s of spies) s.mockRestore();
+  });
+
+  it("mint failure marks broken without discovery; later success clears it", async () => {
+    const h = setup();
+    h.setMintFail(403);
+    await h.manager.reconcile(["acme"]);
+    await h.manager.refresh();
+    const states = () =>
+      h.bodies.map((b) => JSON.parse(b).installations[0].state as string);
+    expect(states().at(-1)).toBe("broken");
+    h.setMintFail(null);
+    await h.manager.reconcile(["acme"]); // clears the rejection for retry
+    await h.manager.refresh();
+    expect(states().at(-1)).toBe("ok");
+  });
+
+  it("refresh with no state change posts nothing extra", async () => {
+    const h = setup();
+    await h.manager.reconcile(["acme"]);
+    await h.manager.refresh();
+    const n = h.bodies.length;
+    await h.manager.refresh();
+    await h.manager.refresh();
+    expect(h.bodies).toHaveLength(n);
+  });
+
+  it("a reporter that rejects or times out does not change manager behavior", async () => {
+    const h = setup({
+      reporterFetch: (async () => {
+        throw new Error("timeout");
+      }) as unknown as typeof fetch,
+    });
+    await h.manager.reconcile(["acme"]);
+    await h.manager.refresh();
+    expect(h.manager.getState().installations[0].health).toBe("ok");
+    expect(await h.manager.getToken(1)).toContain(SECRET_TOKEN);
+  });
+
+  it("no token or key material in any posted payload", async () => {
+    const h = setup();
+    await h.manager.reconcile(["acme"]);
+    await h.manager.refresh();
+    expect(h.bodies.length).toBeGreaterThan(0);
+    for (const b of h.bodies) {
+      expect(b).not.toContain("ghs_");
+      expect(b).not.toContain("SECRET");
+    }
+  });
+});

package/github-installations-reporter.ts

@@ -0,0 +1,150 @@
+/**
+ * GitHubInstallationsReporter — reports the installations manager's state to
+ * the admin API: PUT /agents/:agentId/github-installations (replace-all).
+ *
+ * Posts a full snapshot when the state signature changes (discovered,
+ * removed, ok <-> broken) and on a heartbeat once HEARTBEAT_MS has passed
+ * since the last post; a report with no change inside the heartbeat window
+ * posts nothing. Same fire-and-forget contract as WorkQueueReporter: never
+ * throws, swallows non-2xx and thrown errors with console.warn, injectable
+ * `fetchFn` and `clock`. The payload is built from a fixed allowlist of
+ * fields with constant error strings — no token, key, or raw response body.
+ *
+ * HttpGitHubInstallationsReporter: production implementation.
+ * NoopGitHubInstallationsReporter: testing / default when not configured.
+ */
+
+import { type Clock, SystemClock } from "./clock.ts";
+import type {
+  InstallationState,
+  InstallationsSnapshot,
+} from "./github-installations.ts";
+
+export const INSTALLATIONS_HEARTBEAT_MS = 30 * 60 * 1000;
+const REQUEST_TIMEOUT_MS = 10_000;
+
+export interface GitHubInstallationsReporter {
+  /** Fire-and-forget: never throws, never blocks the caller on a failed PUT. */
+  report(snapshot: InstallationsSnapshot): Promise<void>;
+}
+
+interface ReportedInstallation {
+  owner: string;
+  installationId: number;
+  state: InstallationState["health"];
+  lastError: string | null;
+}
+
+const REASON_TEXT: Record<NonNullable<InstallationState["reason"]>, string> = {
+  suspended: "installation suspended",
+  mint_rejected: "installation token mint rejected",
+};
+
+function toReported(i: InstallationState): ReportedInstallation {
+  return {
+    owner: i.owner ?? "unknown",
+    installationId: i.id,
+    state: i.health,
+    lastError: i.reason ? REASON_TEXT[i.reason] : null,
+  };
+}
+
+interface HttpGitHubInstallationsReporterOptions {
+  apiUrl: string;
+  agentId: string;
+  apiKey: string;
+  fetchFn?: typeof fetch;
+  clock?: Clock;
+  heartbeatMs?: number;
+}
+
+export class HttpGitHubInstallationsReporter
+  implements GitHubInstallationsReporter
+{
+  private readonly fetchFn: typeof fetch;
+  private readonly clock: Clock;
+  private readonly heartbeatMs: number;
+  private lastSignature: string | null = null;
+  private lastPostedAt = 0;
+
+  constructor(private opts: HttpGitHubInstallationsReporterOptions) {
+    this.fetchFn = opts.fetchFn ?? fetch;
+    this.clock = opts.clock ?? SystemClock();
+    this.heartbeatMs = opts.heartbeatMs ?? INSTALLATIONS_HEARTBEAT_MS;
+  }
+
+  async report(snapshot: InstallationsSnapshot): Promise<void> {
+    try {
+      const installations = snapshot.installations.map(toReported);
+      const signature = JSON.stringify(installations);
+      const nowMs = this.clock.now().getTime();
+      const changed = signature !== this.lastSignature;
+      if (!changed && nowMs - this.lastPostedAt < this.heartbeatMs) return;
+      // Claim the slot before awaiting so overlapping reports don't double-post.
+      this.lastSignature = signature;
+      this.lastPostedAt = nowMs;
+      await this.put(installations, new Date(nowMs).toISOString());
+    } catch (err) {
+      console.warn(
+        `[github-installations-reporter] report failed: ${String(err)} — swallowing`,
+      );
+    }
+  }
+
+  private async put(
+    installations: ReportedInstallation[],
+    reportedAt: string,
+  ): Promise<void> {
+    const { apiUrl, agentId, apiKey } = this.opts;
+    const url = `${apiUrl}/agents/${agentId}/github-installations`;
+    try {
+      const res = await this.fetchFn(url, {
+        method: "PUT",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({ reportedAt, installations }),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      });
+      if (!res.ok) {
+        this.lastSignature = null; // retry on the next report
+        console.warn(
+          `[github-installations-reporter] PUT ${url} returned ${res.status} — swallowing`,
+        );
+      }
+    } catch (err) {
+      this.lastSignature = null;
+      console.warn(
+        `[github-installations-reporter] PUT ${url} failed: ${String(err)} — swallowing`,
+      );
+    }
+  }
+}
+
+export class NoopGitHubInstallationsReporter
+  implements GitHubInstallationsReporter
+{
+  async report(_snapshot: InstallationsSnapshot): Promise<void> {
+    // intentional no-op
+  }
+}
+
+/**
+ * Drives the heartbeat: the manager only calls onChange on a state change, so
+ * a quiet period needs its own tick to re-report the current state.
+ */
+export function startInstallationsHeartbeat(
+  reporter: GitHubInstallationsReporter,
+  getState: () => InstallationsSnapshot,
+  opts: { setIntervalFn?: typeof setInterval; tickMs?: number } = {},
+): () => void {
+  const setIntervalFn = opts.setIntervalFn ?? setInterval;
+  const timer = setIntervalFn(
+    () => {
+      void reporter.report(getState());
+    },
+    opts.tickMs ?? 5 * 60 * 1000,
+  );
+  return () => clearInterval(timer);
+}