@app-vitals/agent-runtime 0.4.0 → 0.5.0

package/boot.ts

@@ -31,6 +31,7 @@ import {
   planCronSchedule,
   runPeriodicPasses,
 } from "./agent-extension.ts";
+import { agentFeaturesRef } from "./agent-features-ref.ts";
 import { agentReposRef } from "./agent-repos-ref.ts";
 import {
   agentSlackMembershipRef,
@@ -50,7 +51,6 @@ import {
   setLiveClaudeConfig,
 } from "./claude.ts";
 import { bunExec, detectClaudeCodeVersion } from "./claude-version.ts";
-import { agentFeaturesRef } from "./agent-features-ref.ts";
 import { cleanupAfterDaysRef } from "./cleanup-after-days-ref.ts";
 import { SystemClock } from "./clock.ts";
 import { createConfig } from "./config.ts";
@@ -85,6 +85,10 @@ import {
 import { HttpChatServiceClient } from "./http-chat-service-client.ts";
 import { buildLogPrefix } from "./log-prefix.ts";
 import { validatePiperVoice } from "./piper-voice.ts";
+import {
+  createRepoAccessProbe,
+  createRepoAccessTokenFor,
+} from "./repo-access-probe.ts";
 import {
   createFileSessionStore,
   startSessionPruner,
@@ -224,6 +228,17 @@ export async function startAgent(
           apiUrl: config.shipwright.apiUrl,
           agentId: config.shipwright.agentId,
           apiKey: config.shipwright.apiKey,
+          repoAccessProbe: createRepoAccessProbe({
+            fetch,
+            clock: SystemClock(),
+            log: (message) => console.log(message),
+            getRepos: () => agentReposRef.get(),
+            isEnabled: () => agentFeaturesRef.get()?.repoAccessCheck === true,
+            tokenFor: createRepoAccessTokenFor(
+              () => githubInstallationsManagerRef.get(),
+              process.env,
+            ),
+          }),
         })
       : new NoopGitHubInstallationsReporter();
 

package/github-installations-reporter.ts

@@ -19,6 +19,7 @@ import type {
   InstallationState,
   InstallationsSnapshot,
 } from "./github-installations.ts";
+import type { RepoAccessEntry, RepoAccessProbe } from "./repo-access-probe.ts";
 
 export const INSTALLATIONS_HEARTBEAT_MS = 30 * 60 * 1000;
 const REQUEST_TIMEOUT_MS = 10_000;
@@ -56,6 +57,11 @@ interface HttpGitHubInstallationsReporterOptions {
   fetchFn?: typeof fetch;
   clock?: Clock;
   heartbeatMs?: number;
+  /**
+   * COS-44.1: per-repo access probe. It gates itself (flag, once per interval,
+   * scope change); the reporter just merges whatever it returns into the PUT.
+   */
+  repoAccessProbe?: RepoAccessProbe;
 }
 
 export class HttpGitHubInstallationsReporter
@@ -66,6 +72,7 @@ export class HttpGitHubInstallationsReporter
   private readonly heartbeatMs: number;
   private lastSignature: string | null = null;
   private lastPostedAt = 0;
+  private lastRepos: RepoAccessEntry[] | undefined;
 
   constructor(private opts: HttpGitHubInstallationsReporterOptions) {
     this.fetchFn = opts.fetchFn ?? fetch;
@@ -77,13 +84,19 @@ export class HttpGitHubInstallationsReporter
     try {
       const installations = snapshot.installations.map(toReported);
       const signature = JSON.stringify(installations);
+      const probed = await this.opts.repoAccessProbe?.run();
+      if (probed) this.lastRepos = probed;
       const nowMs = this.clock.now().getTime();
-      const changed = signature !== this.lastSignature;
+      const changed = signature !== this.lastSignature || probed !== undefined;
       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());
+      await this.put(
+        installations,
+        new Date(nowMs).toISOString(),
+        this.lastRepos,
+      );
     } catch (err) {
       console.warn(
         `[github-installations-reporter] report failed: ${String(err)} — swallowing`,
@@ -94,6 +107,7 @@ export class HttpGitHubInstallationsReporter
   private async put(
     installations: ReportedInstallation[],
     reportedAt: string,
+    repos: RepoAccessEntry[] | undefined,
   ): Promise<void> {
     const { apiUrl, agentId, apiKey } = this.opts;
     const url = `${apiUrl}/agents/${agentId}/github-installations`;
@@ -104,7 +118,11 @@ export class HttpGitHubInstallationsReporter
           "Content-Type": "application/json",
           Authorization: `Bearer ${apiKey}`,
         },
-        body: JSON.stringify({ reportedAt, installations }),
+        body: JSON.stringify({
+          reportedAt,
+          installations,
+          ...(repos ? { repos } : {}),
+        }),
         signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
       });
       if (!res.ok) {

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

@@ -5,6 +5,7 @@
 
 import { describe, expect, test } from "bun:test";
 import type { InstallationsSnapshot } from "./github-installations.ts";
+import type { RepoAccessEntry, RepoAccessProbe } from "./repo-access-probe.ts";
 import {
   HttpGitHubInstallationsReporter,
   INSTALLATIONS_HEARTBEAT_MS,
@@ -31,7 +32,10 @@ function snap(
   };
 }
 
-function harness(responses: (Response | Error)[] = []) {
+function harness(
+  responses: (Response | Error)[] = [],
+  repoAccessProbe?: RepoAccessProbe,
+) {
   let nowMs = Date.UTC(2026, 0, 1);
   const calls: { url: string; init: RequestInit | undefined }[] = [];
   let i = 0;
@@ -47,6 +51,7 @@ function harness(responses: (Response | Error)[] = []) {
     apiKey: "KEY",
     fetchFn,
     clock: { now: () => new Date(nowMs) },
+    repoAccessProbe,
   });
   return {
     reporter,
@@ -164,3 +169,48 @@ describe("NoopGitHubInstallationsReporter", () => {
     await new NoopGitHubInstallationsReporter().report(snap());
   });
 });
+
+describe("HttpGitHubInstallationsReporter repo access (COS-44.1)", () => {
+  const entry: RepoAccessEntry = {
+    repo: "a",
+    owner: "acme",
+    read: true,
+    write: false,
+    checkedAt: "2026-01-01T00:00:00.000Z",
+  };
+
+  test("a probe result is merged into the PUT body as repos", async () => {
+    const h = harness([], { run: async () => [entry] });
+    await h.reporter.report(snap());
+    expect(JSON.parse(String(h.calls[0].init?.body)).repos).toEqual([entry]);
+  });
+
+  test("a fresh probe result posts even when installations are unchanged", async () => {
+    let result: RepoAccessEntry[] | undefined = [entry];
+    const h = harness([], { run: async () => result });
+    await h.reporter.report(snap());
+    result = [{ ...entry, write: true }];
+    h.advance(60_000);
+    await h.reporter.report(snap());
+    expect(h.calls).toHaveLength(2);
+    expect(JSON.parse(String(h.calls[1].init?.body)).repos[0].write).toBe(true);
+  });
+
+  test("later heartbeats re-send the last probe result", async () => {
+    let result: RepoAccessEntry[] | undefined = [entry];
+    const h = harness([], { run: async () => result });
+    await h.reporter.report(snap());
+    result = undefined;
+    h.advance(INSTALLATIONS_HEARTBEAT_MS);
+    await h.reporter.report(snap());
+    expect(JSON.parse(String(h.calls[1].init?.body)).repos).toEqual([entry]);
+  });
+
+  test("no probe result -> body has no repos key", async () => {
+    const h = harness([], { run: async () => undefined });
+    await h.reporter.report(snap());
+    expect(
+      Object.keys(JSON.parse(String(h.calls[0].init?.body))).sort(),
+    ).toEqual(["installations", "reportedAt"]);
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@app-vitals/agent-runtime",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/app-vitals/agent.git",
@@ -40,8 +40,8 @@
     "./workspace-paths": "./workspace-paths.ts"
   },
   "dependencies": {
-    "@app-vitals/agent-admin": "0.4.0",
-    "@app-vitals/agent-lib": "0.4.0",
+    "@app-vitals/agent-admin": "0.5.0",
+    "@app-vitals/agent-lib": "0.5.0",
     "@octokit/auth-app": "^8.2.0",
     "@sentry/bun": "^10.63.0",
     "@slack/bolt": "^5.0.0",

package/repo-access-probe.ts

@@ -0,0 +1,193 @@
+/**
+ * runtime/repo-access-probe.ts
+ *
+ * Per-repo GitHub access probe (COS-44.1). For each repo in the agent's scope it
+ * calls GET /repos/{owner}/{repo} with the owner's installation token (or the
+ * PAT) and maps `permissions.pull` -> read, `permissions.push` -> write. A
+ * failure becomes read:false, write:false plus a fixed error class
+ * (not_found | forbidden | rate_limited | network).
+ *
+ * Gating lives here, not in the caller: run() does nothing (zero fetch calls)
+ * unless the feature flag is on, and then probes at most once per interval or
+ * when the repo scope changed. Concurrency is capped at 3. The token is passed
+ * only in the Authorization header — never logged, never in the result.
+ * Everything is injected so it is deterministically testable.
+ */
+
+import type { Clock } from "./clock.ts";
+
+export const REPO_ACCESS_INTERVAL_MS = 30 * 60 * 1000;
+const REPO_ACCESS_CONCURRENCY = 3;
+const REQUEST_TIMEOUT_MS = 10_000;
+
+export type RepoAccessErrorClass =
+  | "not_found"
+  | "forbidden"
+  | "rate_limited"
+  | "network";
+
+export interface RepoAccessEntry {
+  repo: string;
+  owner: string;
+  read: boolean;
+  write: boolean;
+  checkedAt: string;
+  error?: RepoAccessErrorClass;
+}
+
+export interface RepoAccessProbeDeps {
+  fetch: typeof fetch;
+  clock: Clock;
+  /** Token for the owner's installation, the PAT, or null when there is none. */
+  tokenFor(owner: string): Promise<string | null>;
+  log(message: string): void;
+  /** Scoped repos as `org/repo` strings. */
+  getRepos(): string[];
+  isEnabled(): boolean;
+  intervalMs?: number;
+}
+
+export interface RepoAccessProbe {
+  /**
+   * Returns a fresh result when a probe round ran, or undefined when it did
+   * not (feature off, or not due and the scope is unchanged).
+   */
+  run(): Promise<RepoAccessEntry[] | undefined>;
+}
+
+function classify(res: Response): RepoAccessErrorClass {
+  if (res.status === 404) return "not_found";
+  if (res.status === 429) return "rate_limited";
+  if (res.status === 403) {
+    return res.headers.get("x-ratelimit-remaining") === "0"
+      ? "rate_limited"
+      : "forbidden";
+  }
+  if (res.status === 401) return "forbidden";
+  return "network";
+}
+
+function failed(
+  owner: string,
+  repo: string,
+  checkedAt: string,
+  error: RepoAccessErrorClass,
+): RepoAccessEntry {
+  return { repo, owner, read: false, write: false, checkedAt, error };
+}
+
+export function createRepoAccessProbe(
+  deps: RepoAccessProbeDeps,
+): RepoAccessProbe {
+  const intervalMs = deps.intervalMs ?? REPO_ACCESS_INTERVAL_MS;
+  let lastScope: string | null = null;
+  let lastRunAt = 0;
+  let running = false;
+
+  async function probeOne(slug: string): Promise<RepoAccessEntry> {
+    const [owner = "", repo = ""] = slug.split("/");
+    const checkedAt = deps.clock.now().toISOString();
+    try {
+      const token = await deps.tokenFor(owner);
+      if (!token) return failed(owner, repo, checkedAt, "forbidden");
+      const res = await deps.fetch(
+        `https://api.github.com/repos/${owner}/${repo}`,
+        {
+          headers: {
+            Authorization: `Bearer ${token}`,
+            Accept: "application/vnd.github+json",
+          },
+          signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        },
+      );
+      if (!res.ok) return failed(owner, repo, checkedAt, classify(res));
+      const body = (await res.json()) as {
+        permissions?: { pull?: boolean; push?: boolean };
+      };
+      return {
+        repo,
+        owner,
+        read: body.permissions?.pull === true,
+        write: body.permissions?.push === true,
+        checkedAt,
+      };
+    } catch {
+      // Never interpolate the error: a thrown message could carry request detail.
+      return failed(owner, repo, checkedAt, "network");
+    }
+  }
+
+  async function probeAll(slugs: string[]): Promise<RepoAccessEntry[]> {
+    const results: RepoAccessEntry[] = new Array(slugs.length);
+    let next = 0;
+    const worker = async () => {
+      while (next < slugs.length) {
+        const i = next++;
+        results[i] = await probeOne(slugs[i] as string);
+      }
+    };
+    await Promise.all(
+      Array.from(
+        { length: Math.min(REPO_ACCESS_CONCURRENCY, slugs.length) },
+        worker,
+      ),
+    );
+    return results;
+  }
+
+  return {
+    async run() {
+      if (!deps.isEnabled() || running) return undefined;
+      const slugs = [...new Set(deps.getRepos())]
+        .filter((r) => r.includes("/"))
+        .sort();
+      const scope = slugs.join(",");
+      const nowMs = deps.clock.now().getTime();
+      const scopeChanged = scope !== lastScope;
+      if (!scopeChanged && nowMs - lastRunAt < intervalMs) return undefined;
+      running = true;
+      lastScope = scope;
+      lastRunAt = nowMs;
+      try {
+        const results = await probeAll(slugs);
+        deps.log(
+          `[repo-access] probed ${results.length} repo(s), ${results.filter((r) => r.error).length} with errors`,
+        );
+        return results;
+      } finally {
+        running = false;
+      }
+    },
+  };
+}
+
+interface InstallationTokenSource {
+  getState?(): {
+    installations: { id: number; owner: string | null; health: string }[];
+  };
+  /** Present on the real manager; the ref's narrower type omits it. */
+  getToken?(installationId: number): Promise<string>;
+}
+
+/**
+ * Builds `tokenFor`: the healthy installation whose owner matches (case
+ * insensitive), else the PAT from GH_TOKEN, else null. The manager is read
+ * lazily because App auth may activate after boot.
+ */
+export function createRepoAccessTokenFor(
+  getManager: () => InstallationTokenSource | null | undefined,
+  env: Readonly<Record<string, string | undefined>>,
+): (owner: string) => Promise<string | null> {
+  return async (owner) => {
+    const manager = getManager();
+    const match = manager
+      ?.getState?.()
+      .installations.find(
+        (i) =>
+          i.owner?.toLowerCase() === owner.toLowerCase() &&
+          i.health !== "broken",
+      );
+    if (manager?.getToken && match) return manager.getToken(match.id);
+    return env.GH_TOKEN || null;
+  };
+}

package/repo-access-probe.unit.test.ts

@@ -0,0 +1,211 @@
+/**
+ * runtime/repo-access-probe.unit.test.ts
+ * Probe behaviour via a routed fetch fake and an injected clock (COS-44.1).
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  createRepoAccessProbe,
+  createRepoAccessTokenFor,
+  REPO_ACCESS_INTERVAL_MS,
+} from "./repo-access-probe.ts";
+
+const SECRET = "ghs_SUPERSECRETTOKEN";
+
+type Route = Response | Error | ((req: { url: string }) => Response);
+
+function harness(
+  routes: Record<string, Route>,
+  opts: { repos?: string[]; enabled?: boolean; token?: string | null } = {},
+) {
+  let nowMs = Date.UTC(2026, 0, 1);
+  const calls: { url: string; auth: string | null }[] = [];
+  const logs: string[] = [];
+  let inFlight = 0;
+  let maxInFlight = 0;
+  const state = {
+    repos: opts.repos ?? ["acme/a"],
+    enabled: opts.enabled ?? true,
+  };
+  const fetchFn = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = String(input);
+    calls.push({
+      url,
+      auth: new Headers(init?.headers).get("authorization"),
+    });
+    inFlight++;
+    maxInFlight = Math.max(maxInFlight, inFlight);
+    await new Promise((r) => setTimeout(r, 1));
+    inFlight--;
+    const route = routes[url.replace("https://api.github.com/repos/", "")];
+    if (route instanceof Error) throw route;
+    if (typeof route === "function") return route({ url });
+    return route ?? new Response("{}", { status: 404 });
+  }) as unknown as typeof fetch;
+  const probe = createRepoAccessProbe({
+    fetch: fetchFn,
+    clock: { now: () => new Date(nowMs) },
+    tokenFor: async () => (opts.token === undefined ? SECRET : opts.token),
+    log: (m) => logs.push(m),
+    getRepos: () => state.repos,
+    isEnabled: () => state.enabled,
+  });
+  return {
+    probe,
+    calls,
+    logs,
+    state,
+    maxInFlight: () => maxInFlight,
+    advance: (ms: number) => {
+      nowMs += ms;
+    },
+  };
+}
+
+const ok = (pull: boolean, push: boolean) =>
+  new Response(JSON.stringify({ permissions: { pull, push } }), {
+    status: 200,
+  });
+
+describe("createRepoAccessProbe", () => {
+  test("maps permissions.pull/push to read/write", async () => {
+    const h = harness(
+      {
+        "acme/rw": ok(true, true),
+        "acme/ro": ok(true, false),
+      },
+      { repos: ["acme/rw", "acme/ro"] },
+    );
+    const result = await h.probe.run();
+    expect(result).toEqual([
+      expect.objectContaining({
+        repo: "ro",
+        owner: "acme",
+        read: true,
+        write: false,
+      }),
+      expect.objectContaining({
+        repo: "rw",
+        owner: "acme",
+        read: true,
+        write: true,
+      }),
+    ]);
+    expect(result?.every((r) => r.error === undefined)).toBe(true);
+    expect(result?.[0]?.checkedAt).toBe("2026-01-01T00:00:00.000Z");
+  });
+
+  test.each([
+    ["404", new Response("", { status: 404 }), "not_found"],
+    ["403", new Response("", { status: 403 }), "forbidden"],
+    [
+      "403 with exhausted rate limit",
+      new Response("", {
+        status: 403,
+        headers: { "x-ratelimit-remaining": "0" },
+      }),
+      "rate_limited",
+    ],
+    ["429", new Response("", { status: 429 }), "rate_limited"],
+    ["network error", new Error("ECONNRESET"), "network"],
+    ["5xx", new Response("", { status: 502 }), "network"],
+  ] as const)(
+    "%s -> read:false, write:false, error %s",
+    async (_n, route, error) => {
+      const h = harness({ "acme/a": route });
+      const result = await h.probe.run();
+      expect(result).toEqual([
+        expect.objectContaining({
+          repo: "a",
+          read: false,
+          write: false,
+          error,
+        }),
+      ]);
+    },
+  );
+
+  test("no credential for the owner -> forbidden without a fetch", async () => {
+    const h = harness({}, { token: null });
+    const result = await h.probe.run();
+    expect(result?.[0]?.error).toBe("forbidden");
+    expect(h.calls).toHaveLength(0);
+  });
+
+  test("feature off -> no calls and no result", async () => {
+    const h = harness({ "acme/a": ok(true, true) }, { enabled: false });
+    expect(await h.probe.run()).toBeUndefined();
+    expect(h.calls).toHaveLength(0);
+  });
+
+  test("at most once per interval, again after it elapses", async () => {
+    const h = harness({ "acme/a": ok(true, true) });
+    expect(await h.probe.run()).toBeDefined();
+    h.advance(REPO_ACCESS_INTERVAL_MS - 1);
+    expect(await h.probe.run()).toBeUndefined();
+    h.advance(1);
+    expect(await h.probe.run()).toBeDefined();
+    expect(h.calls).toHaveLength(2);
+  });
+
+  test("a scope change probes immediately", async () => {
+    const h = harness({ "acme/a": ok(true, true), "acme/b": ok(true, false) });
+    await h.probe.run();
+    h.state.repos = ["acme/a", "acme/b"];
+    const result = await h.probe.run();
+    expect(result).toHaveLength(2);
+    // Same set in a different order is not a change.
+    h.state.repos = ["acme/b", "acme/a"];
+    expect(await h.probe.run()).toBeUndefined();
+  });
+
+  test("concurrency is capped at 3", async () => {
+    const repos = Array.from({ length: 8 }, (_, i) => `acme/r${i}`);
+    const routes = Object.fromEntries(repos.map((r) => [r, ok(true, true)]));
+    const h = harness(routes, { repos });
+    await h.probe.run();
+    expect(h.calls).toHaveLength(8);
+    expect(h.maxInFlight()).toBe(3);
+  });
+
+  test("the token is sent only as a header and never logged or returned", async () => {
+    const h = harness({
+      "acme/a": new Error(`boom with ${SECRET}`),
+    });
+    const result = await h.probe.run();
+    expect(h.calls[0]?.auth).toBe(`Bearer ${SECRET}`);
+    expect(JSON.stringify(result)).not.toContain(SECRET);
+    expect(h.logs.join("\n")).not.toContain(SECRET);
+  });
+});
+
+describe("createRepoAccessTokenFor", () => {
+  const manager = {
+    getState: () => ({
+      installations: [
+        { id: 1, owner: "Acme", health: "ok" },
+        { id: 2, owner: "dead", health: "broken" },
+      ],
+    }),
+    getToken: async (id: number) => `inst-${id}`,
+  };
+
+  test("uses the matching healthy installation (case-insensitive)", async () => {
+    const tokenFor = createRepoAccessTokenFor(() => manager, {
+      GH_TOKEN: "pat",
+    });
+    expect(await tokenFor("acme")).toBe("inst-1");
+  });
+
+  test("falls back to the PAT, then null", async () => {
+    expect(
+      await createRepoAccessTokenFor(() => manager, { GH_TOKEN: "pat" })(
+        "dead",
+      ),
+    ).toBe("pat");
+    expect(
+      await createRepoAccessTokenFor(() => null, { GH_TOKEN: "pat" })("x"),
+    ).toBe("pat");
+    expect(await createRepoAccessTokenFor(() => null, {})("x")).toBeNull();
+  });
+});