@app-vitals/agent-runtime 0.0.1 → 0.1.0

package/agent-repos-ref.ts

@@ -0,0 +1,63 @@
+/**
+ * agent/src/runtime/agent-repos-ref.ts
+ *
+ * A tiny mutable box holding the agent's most recently synced list of scoped
+ * repos (org/repo strings from AgentConfigResponse.repos), so downstream
+ * consumers can read a live view without closing over a single syncConfig()
+ * tick. Kept pure and zero-I/O so it's unit-testable in isolation — mirrors
+ * loop-jobs-ref.ts's style.
+ */
+
+export interface AgentReposRef {
+  /**
+   * Returns the most recently set repos list, or [] if set() was never
+   * called. Callers that need to distinguish "never synced" (config-bundle
+   * fetch has never succeeded — e.g. a persistent 404) from "synced to a
+   * deliberately empty scope" must check hasSynced() rather than inferring
+   * it from an empty get() result, since both states return [].
+   */
+  get(): string[];
+  /**
+   * True once set() has been called at least once. Consumers that gate
+   * candidacy on scope should fail open (skip filtering) while this is
+   * false, so a persistent config-sync failure doesn't silently exclude
+   * every repo from candidacy — before this ref existed, scope was never a
+   * candidacy gate at all, and that pre-sync behavior must be preserved.
+   */
+  hasSynced(): boolean;
+  /** Replaces the current repos list. */
+  set(repos: string[]): void;
+}
+
+/** Creates a new, independent agent repos ref defaulting to an empty list. */
+export function createAgentReposRef(): AgentReposRef {
+  let repos: string[] = [];
+  let synced = false;
+
+  return {
+    get(): string[] {
+      return repos;
+    },
+    hasSynced(): boolean {
+      return synced;
+    },
+    set(next: string[]): void {
+      repos = next;
+      synced = true;
+    },
+  };
+}
+
+/**
+ * The process-wide agent repos ref. index.ts's syncConfig() calls
+ * `.set(bundle.repos)` on every successful config sync tick; check-review.ts,
+ * check-patch.ts, and check-deploy.ts's buildProductionDeps default their
+ * getScopedRepos/hasSynced dependencies to `.get`/`.hasSynced` from this same
+ * instance, so scope changes take effect on their very next
+ * candidate-collection call without requiring loop-orchestrator.ts (which
+ * builds those deps once and reuses them for the orchestrator's lifetime) to
+ * be touched at all. syncConfig()'s 404 branch never calls `.set()`, so
+ * `hasSynced()` stays false for the process lifetime if the agent's config
+ * bundle never becomes available — consumers must fail open in that case.
+ */
+export const agentReposRef: AgentReposRef = createAgentReposRef();

package/agent-repos-ref.unit.test.ts

@@ -0,0 +1,84 @@
+/**
+ * agent/src/runtime/agent-repos-ref.unit.test.ts
+ *
+ * Unit tests for createAgentReposRef() — pure logic, no I/O.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { agentReposRef, createAgentReposRef } from "./agent-repos-ref.ts";
+
+describe("createAgentReposRef", () => {
+  it("initial get() before any set() returns an empty/safe default", () => {
+    const ref = createAgentReposRef();
+    expect(ref.get()).toEqual([]);
+  });
+
+  it("hasSynced() is false before any set() call", () => {
+    const ref = createAgentReposRef();
+    expect(ref.hasSynced()).toBe(false);
+  });
+
+  it("hasSynced() becomes true after the first set(), even if set to an empty list", () => {
+    const ref = createAgentReposRef();
+    ref.set([]);
+    expect(ref.hasSynced()).toBe(true);
+    expect(ref.get()).toEqual([]);
+  });
+
+  it("hasSynced() stays true after subsequent set() calls, regardless of value", () => {
+    const ref = createAgentReposRef();
+    ref.set(["org/repo-a"]);
+    expect(ref.hasSynced()).toBe(true);
+
+    ref.set([]);
+    expect(ref.hasSynced()).toBe(true);
+  });
+
+  it("returns the most recently set repos list regardless of how many times set() was called", () => {
+    const ref = createAgentReposRef();
+    const first = ["org/repo-a"];
+    const second = ["org/repo-b"];
+    const third = ["org/repo-c", "org/repo-d"];
+
+    ref.set(first);
+    expect(ref.get()).toBe(first);
+
+    ref.set(second);
+    expect(ref.get()).toBe(second);
+
+    ref.set(third);
+    expect(ref.get()).toEqual(third);
+  });
+
+  it("multiple independent ref instances don't share state", () => {
+    const refA = createAgentReposRef();
+    const refB = createAgentReposRef();
+
+    refA.set(["org/repo-a"]);
+
+    expect(refA.get()).toEqual(["org/repo-a"]);
+    expect(refB.get()).toEqual([]);
+    expect(refA.hasSynced()).toBe(true);
+    expect(refB.hasSynced()).toBe(false);
+  });
+
+  it("set() with an empty array is reflected by the next get()", () => {
+    const ref = createAgentReposRef();
+    ref.set(["org/repo-a"]);
+    expect(ref.get()).toHaveLength(1);
+
+    ref.set([]);
+    expect(ref.get()).toEqual([]);
+  });
+});
+
+describe("agentReposRef (process-wide singleton)", () => {
+  it("is a working ref that reflects set() through get(), independent of createAgentReposRef() instances", () => {
+    const independent = createAgentReposRef();
+    independent.set(["org/should-not-leak"]);
+
+    agentReposRef.set(["org/scoped-repo"]);
+    expect(agentReposRef.get()).toEqual(["org/scoped-repo"]);
+    expect(independent.get()).toEqual(["org/should-not-leak"]);
+  });
+});

package/agent-slack-membership-ref.ts

@@ -0,0 +1,94 @@
+/**
+ * agent/src/runtime/agent-slack-membership-ref.ts
+ *
+ * A tiny mutable box holding the agent's most recently synced
+ * Slack membership restriction config (whether to restrict Slack access to
+ * specific members + the list of allowed member email addresses), so
+ * downstream consumers can read a live view without closing over a single
+ * syncConfig() tick. Kept pure and zero-I/O so it's unit-testable in
+ * isolation — mirrors review-author-allowlist-ref.ts's style.
+ */
+
+interface SlackMembershipConfig {
+  restrict: boolean;
+  emails: string[];
+}
+
+export interface AgentSlackMembershipRef {
+  /**
+   * Returns the most recently set Slack membership config, or
+   * {restrict: false, emails: []} if set() was never called. Callers that
+   * need to distinguish "never synced" (config-bundle fetch has never
+   * succeeded — e.g. a persistent 404) from "synced to a deliberately
+   * unrestricted state" must check hasSynced() rather than inferring it
+   * from the default value, since both states return {restrict: false,
+   * emails: []}.
+   */
+  get(): SlackMembershipConfig;
+  /**
+   * True once set() has been called at least once. Consumers that gate on
+   * the membership restriction should fail open (skip filtering / allow) while
+   * this is false, so a persistent config-sync failure doesn't silently
+   * restrict Slack access — before the first successful config sync,
+   * unrestricted access is the safe default.
+   */
+  hasSynced(): boolean;
+  /** Replaces the current Slack membership config. */
+  set(config: SlackMembershipConfig): void;
+}
+
+/**
+ * Defaults a config-bundle's restrictSlackToMembers and memberEmails to
+ * fail-open when the values are null/undefined before they're handed to
+ * agentSlackMembershipRef.set().
+ *
+ * The AgentConfigResponse type declares restrictSlackToMembers as a
+ * non-nullable boolean and memberEmails as a non-nullable string[], but
+ * the live config-bundle API has been observed returning null/undefined
+ * for fields in production — a runtime/type mismatch that, left unguarded,
+ * gets baked into the process-wide agentSlackMembershipRef singleton.
+ * Defaulting here, at the config-sync write site, ensures every downstream
+ * consumer of the ref never sees null and always respects fail-open semantics
+ * (restrict: false, emails: []) on config-sync failure.
+ */
+export function resolveSlackMembership(
+  restrictSlackToMembers: boolean | null | undefined,
+  memberEmails: string[] | null | undefined,
+): SlackMembershipConfig {
+  return {
+    restrict: restrictSlackToMembers ?? false,
+    emails: memberEmails ?? [],
+  };
+}
+
+/** Creates a new, independent agent Slack membership ref defaulting to an unrestricted state. */
+export function createAgentSlackMembershipRef(): AgentSlackMembershipRef {
+  let config: SlackMembershipConfig = { restrict: false, emails: [] };
+  let synced = false;
+
+  return {
+    get(): SlackMembershipConfig {
+      return config;
+    },
+    hasSynced(): boolean {
+      return synced;
+    },
+    set(next: SlackMembershipConfig): void {
+      config = next;
+      synced = true;
+    },
+  };
+}
+
+/**
+ * The process-wide agent Slack membership ref. Downstream consumers
+ * (e.g. Slack message handlers checking membership restriction) will
+ * default their restriction-checking behavior to this same instance
+ * (once the consuming code lands), so membership changes take effect on
+ * the very next candidate-collection or message-handling call without
+ * requiring any agent restart. If the agent's config bundle never becomes
+ * available, `hasSynced()` stays false for the process lifetime —
+ * consumers must fail open (allow) in that case.
+ */
+export const agentSlackMembershipRef: AgentSlackMembershipRef =
+  createAgentSlackMembershipRef();

package/agent-slack-membership-ref.unit.test.ts

@@ -0,0 +1,201 @@
+/**
+ * agent/src/runtime/agent-slack-membership-ref.unit.test.ts
+ *
+ * Unit tests for createAgentSlackMembershipRef() — pure logic, no I/O.
+ */
+
+import { afterEach, describe, expect, it } from "bun:test";
+import {
+  agentSlackMembershipRef,
+  createAgentSlackMembershipRef,
+  resolveSlackMembership,
+} from "./agent-slack-membership-ref.ts";
+
+describe("createAgentSlackMembershipRef", () => {
+  it("initial get() before any set() returns the fail-open default", () => {
+    const ref = createAgentSlackMembershipRef();
+    expect(ref.get()).toEqual({ restrict: false, emails: [] });
+  });
+
+  it("hasSynced() is false before any set() call", () => {
+    const ref = createAgentSlackMembershipRef();
+    expect(ref.hasSynced()).toBe(false);
+  });
+
+  it("hasSynced() becomes true after the first set(), even if set to empty state", () => {
+    const ref = createAgentSlackMembershipRef();
+    ref.set({ restrict: false, emails: [] });
+    expect(ref.hasSynced()).toBe(true);
+    expect(ref.get()).toEqual({ restrict: false, emails: [] });
+  });
+
+  it("hasSynced() stays true after subsequent set() calls, regardless of value", () => {
+    const ref = createAgentSlackMembershipRef();
+    ref.set({ restrict: true, emails: ["alice@example.com"] });
+    expect(ref.hasSynced()).toBe(true);
+
+    ref.set({ restrict: false, emails: [] });
+    expect(ref.hasSynced()).toBe(true);
+  });
+
+  it("returns the most recently set membership config regardless of how many times set() was called", () => {
+    const ref = createAgentSlackMembershipRef();
+    const first = { restrict: false, emails: [] };
+    const second = { restrict: true, emails: ["alice@example.com"] };
+    const third = {
+      restrict: true,
+      emails: ["bob@example.com", "carol@example.com"],
+    };
+
+    ref.set(first);
+    expect(ref.get()).toBe(first);
+
+    ref.set(second);
+    expect(ref.get()).toBe(second);
+
+    ref.set(third);
+    expect(ref.get()).toEqual(third);
+  });
+
+  it("multiple independent ref instances don't share state", () => {
+    const refA = createAgentSlackMembershipRef();
+    const refB = createAgentSlackMembershipRef();
+
+    refA.set({ restrict: true, emails: ["alice@example.com"] });
+
+    expect(refA.get()).toEqual({
+      restrict: true,
+      emails: ["alice@example.com"],
+    });
+    expect(refB.get()).toEqual({ restrict: false, emails: [] });
+    expect(refA.hasSynced()).toBe(true);
+    expect(refB.hasSynced()).toBe(false);
+  });
+
+  it("set() with restrict:true and emails is reflected by the next get()", () => {
+    const ref = createAgentSlackMembershipRef();
+    ref.set({ restrict: false, emails: [] });
+    expect(ref.get()).toEqual({ restrict: false, emails: [] });
+
+    ref.set({
+      restrict: true,
+      emails: ["alice@example.com", "bob@example.com"],
+    });
+    expect(ref.get()).toEqual({
+      restrict: true,
+      emails: ["alice@example.com", "bob@example.com"],
+    });
+  });
+});
+
+describe("agentSlackMembershipRef (process-wide singleton)", () => {
+  afterEach(() => {
+    agentSlackMembershipRef.set({ restrict: false, emails: [] });
+  });
+
+  it("is a working ref that reflects set() through get(), independent of createAgentSlackMembershipRef() instances", () => {
+    const independent = createAgentSlackMembershipRef();
+    independent.set({
+      restrict: true,
+      emails: ["should-not-leak@example.com"],
+    });
+
+    agentSlackMembershipRef.set({
+      restrict: true,
+      emails: ["alice@example.com"],
+    });
+    expect(agentSlackMembershipRef.get()).toEqual({
+      restrict: true,
+      emails: ["alice@example.com"],
+    });
+    expect(independent.get()).toEqual({
+      restrict: true,
+      emails: ["should-not-leak@example.com"],
+    });
+  });
+});
+
+describe("resolveSlackMembership", () => {
+  // Regression coverage: the live config-bundle API may return null/undefined
+  // for these fields even though AgentConfigResponse types them as
+  // non-nullable. resolveSlackMembership must default to a fail-open state
+  // (restrict: false, emails: []) to protect every downstream consumer.
+
+  it("defaults a null restrictSlackToMembers to false", () => {
+    expect(
+      resolveSlackMembership(null as unknown as boolean, ["alice@example.com"]),
+    ).toEqual({
+      restrict: false,
+      emails: ["alice@example.com"],
+    });
+  });
+
+  it("defaults an undefined restrictSlackToMembers to false", () => {
+    expect(
+      resolveSlackMembership(undefined as unknown as boolean, [
+        "alice@example.com",
+      ]),
+    ).toEqual({
+      restrict: false,
+      emails: ["alice@example.com"],
+    });
+  });
+
+  it("defaults a null memberEmails to an empty array", () => {
+    expect(resolveSlackMembership(true, null as unknown as string[])).toEqual({
+      restrict: true,
+      emails: [],
+    });
+  });
+
+  it("defaults an undefined memberEmails to an empty array", () => {
+    expect(
+      resolveSlackMembership(true, undefined as unknown as string[]),
+    ).toEqual({
+      restrict: true,
+      emails: [],
+    });
+  });
+
+  it("defaults both null restrictSlackToMembers and null memberEmails to fail-open state", () => {
+    expect(
+      resolveSlackMembership(
+        null as unknown as boolean,
+        null as unknown as string[],
+      ),
+    ).toEqual({
+      restrict: false,
+      emails: [],
+    });
+  });
+
+  it("syncing a null restrictSlackToMembers into the ref does not throw and leaves restrict as false", () => {
+    const ref = createAgentSlackMembershipRef();
+    const result = resolveSlackMembership(null as unknown as boolean, [
+      "alice@example.com",
+    ]);
+
+    expect(() => ref.set(result)).not.toThrow();
+    expect(ref.get()).toEqual({
+      restrict: false,
+      emails: ["alice@example.com"],
+    });
+  });
+
+  it("passes through a real restrictSlackToMembers and memberEmails array unchanged (no behavior change for real values)", () => {
+    const emails = ["alice@example.com", "bob@example.com"];
+    const result = resolveSlackMembership(true, emails);
+    expect(result).toEqual({
+      restrict: true,
+      emails: emails,
+    });
+    // Verify emails array is the same reference (not copied)
+    expect(result.emails).toBe(emails);
+  });
+
+  it("passes through an already-empty memberEmails array unchanged", () => {
+    const config = { restrict: false, emails: [] };
+    const result = resolveSlackMembership(config.restrict, config.emails);
+    expect(result).toEqual(config);
+  });
+});

package/agent-trial-expiry-ref.ts

@@ -0,0 +1,63 @@
+/**
+ * agent/src/runtime/agent-trial-expiry-ref.ts
+ *
+ * A tiny mutable box holding the agent's most recently synced trial-expiry
+ * timestamp (ATE-3.1), so downstream consumers (agent/src/runtime/slack.ts's
+ * isTrialExpired() gate) can read a live view without closing over a single
+ * syncConfig() tick. Kept pure and zero-I/O so it's unit-testable in
+ * isolation — mirrors agent-slack-membership-ref.ts's style exactly.
+ */
+
+export interface AgentTrialExpiryRef {
+  /**
+   * Returns the most recently synced trial-expiry Date, or null if either
+   * set() was never called or the agent has no trial configured. Callers
+   * that need to distinguish "never synced" (config-bundle fetch has never
+   * succeeded) from "synced to no-trial-configured" must check hasSynced()
+   * rather than inferring it from the null return value, since both states
+   * return null.
+   */
+  get(): Date | null;
+  /**
+   * True once set() has been called at least once. Consumers gating on
+   * trial expiry should fail open (treat as not-expired) while this is
+   * false, so a persistent config-sync failure never locks a customer out
+   * of their own paying agent — before the first successful config sync,
+   * unexpired access is the safe default.
+   */
+  hasSynced(): boolean;
+  /** Replaces the current trial-expiry timestamp. */
+  set(trialExpiresAt: Date | null): void;
+}
+
+/** Creates a new, independent agent trial-expiry ref defaulting to "no trial configured". */
+export function createAgentTrialExpiryRef(): AgentTrialExpiryRef {
+  let trialExpiresAt: Date | null = null;
+  let synced = false;
+
+  return {
+    get(): Date | null {
+      return trialExpiresAt;
+    },
+    hasSynced(): boolean {
+      return synced;
+    },
+    set(next: Date | null): void {
+      trialExpiresAt = next;
+      synced = true;
+    },
+  };
+}
+
+/**
+ * The process-wide agent trial-expiry ref. agent/src/index.ts's syncConfig()
+ * writes into this on every successful config-sync tick;
+ * agent/src/runtime/slack.ts's isTrialExpired() gate reads it on every inbound Slack
+ * event, so a trial-expiry change (set via PATCH /agents/:id) takes effect
+ * on the very next config-sync tick without requiring an agent restart. If
+ * the agent's config bundle never becomes available, hasSynced() stays
+ * false for the process lifetime — consumers must fail open (allow) in that
+ * case.
+ */
+export const agentTrialExpiryRef: AgentTrialExpiryRef =
+  createAgentTrialExpiryRef();

package/agent-trial-expiry-ref.unit.test.ts

@@ -0,0 +1,84 @@
+/**
+ * agent/src/runtime/agent-trial-expiry-ref.unit.test.ts
+ *
+ * Unit tests for createAgentTrialExpiryRef() — pure logic, no I/O.
+ * Mirrors agent-slack-membership-ref.unit.test.ts's coverage pattern.
+ */
+
+import { afterEach, describe, expect, it } from "bun:test";
+import {
+  agentTrialExpiryRef,
+  createAgentTrialExpiryRef,
+} from "./agent-trial-expiry-ref.ts";
+
+describe("createAgentTrialExpiryRef", () => {
+  it("initial get() before any set() returns null (fail-open default)", () => {
+    const ref = createAgentTrialExpiryRef();
+    expect(ref.get()).toBeNull();
+  });
+
+  it("hasSynced() is false before any set() call", () => {
+    const ref = createAgentTrialExpiryRef();
+    expect(ref.hasSynced()).toBe(false);
+  });
+
+  it("hasSynced() becomes true after the first set(), even if set to null", () => {
+    const ref = createAgentTrialExpiryRef();
+    ref.set(null);
+    expect(ref.hasSynced()).toBe(true);
+    expect(ref.get()).toBeNull();
+  });
+
+  it("hasSynced() stays true after subsequent set() calls, regardless of value", () => {
+    const ref = createAgentTrialExpiryRef();
+    ref.set(new Date("2026-01-01T00:00:00.000Z"));
+    expect(ref.hasSynced()).toBe(true);
+
+    ref.set(null);
+    expect(ref.hasSynced()).toBe(true);
+  });
+
+  it("returns the most recently set trial-expiry date regardless of how many times set() was called", () => {
+    const ref = createAgentTrialExpiryRef();
+    const first = new Date("2026-01-01T00:00:00.000Z");
+    const second = null;
+    const third = new Date("2026-06-15T00:00:00.000Z");
+
+    ref.set(first);
+    expect(ref.get()).toBe(first);
+
+    ref.set(second);
+    expect(ref.get()).toBeNull();
+
+    ref.set(third);
+    expect(ref.get()).toBe(third);
+  });
+
+  it("multiple independent ref instances don't share state", () => {
+    const refA = createAgentTrialExpiryRef();
+    const refB = createAgentTrialExpiryRef();
+
+    refA.set(new Date("2026-01-01T00:00:00.000Z"));
+
+    expect(refA.get()).toEqual(new Date("2026-01-01T00:00:00.000Z"));
+    expect(refB.get()).toBeNull();
+    expect(refA.hasSynced()).toBe(true);
+    expect(refB.hasSynced()).toBe(false);
+  });
+});
+
+describe("agentTrialExpiryRef (process-wide singleton)", () => {
+  afterEach(() => {
+    agentTrialExpiryRef.set(null);
+  });
+
+  it("is a working ref that reflects set() through get(), independent of createAgentTrialExpiryRef() instances", () => {
+    const independent = createAgentTrialExpiryRef();
+    independent.set(new Date("2099-01-01T00:00:00.000Z"));
+
+    const expiry = new Date("2026-03-01T00:00:00.000Z");
+    agentTrialExpiryRef.set(expiry);
+    expect(agentTrialExpiryRef.get()).toEqual(expiry);
+    expect(independent.get()).toEqual(new Date("2099-01-01T00:00:00.000Z"));
+  });
+});

package/anthropic-federation-guard.ts

@@ -0,0 +1,72 @@
+/**
+ * agent/src/runtime/anthropic-federation-guard.ts
+ *
+ * Defense in depth for Anthropic workload identity federation (WIF-2.1). The
+ * admin already refuses to store or serve these keys for federated agents; this
+ * guards the agent process itself. When ANTHROPIC_FEDERATION_RULE_ID is in the
+ * pod env, CLAUDE_CODE_OAUTH_TOKEN / ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN
+ * are skipped and deleted from process.env — each outranks federation in the
+ * Anthropic client, even when set to an empty string.
+ */
+
+export const ANTHROPIC_CREDENTIAL_KEYS = [
+  "CLAUDE_CODE_OAUTH_TOKEN",
+  "ANTHROPIC_API_KEY",
+  "ANTHROPIC_AUTH_TOKEN",
+] as const;
+
+interface GuardDeps {
+  processEnv?: Record<string, string | undefined>;
+  /** Keys already logged by this process — log once per key. */
+  logged?: Set<string>;
+  log?: (message: string) => void;
+}
+
+const loggedKeys = new Set<string>();
+
+/**
+ * Returns `env` without the Anthropic credential keys and removes them from
+ * process.env, when federation is configured. A no-op otherwise. Logs key
+ * names only, once per key.
+ */
+export function filterAnthropicCredentials(
+  env: Record<string, string>,
+  deps: GuardDeps = {},
+): Record<string, string> {
+  const processEnv = deps.processEnv ?? process.env;
+  if (!processEnv.ANTHROPIC_FEDERATION_RULE_ID) return env;
+
+  const logged = deps.logged ?? loggedKeys;
+  const log = deps.log ?? ((m: string) => console.warn(m));
+  const filtered = { ...env };
+  for (const key of ANTHROPIC_CREDENTIAL_KEYS) {
+    const present = key in filtered || processEnv[key] !== undefined;
+    delete filtered[key];
+    delete processEnv[key];
+    if (present && !logged.has(key)) {
+      logged.add(key);
+      log(
+        `[federation] ignoring ${key}: Anthropic workload identity federation is active`,
+      );
+    }
+  }
+  return filtered;
+}
+
+/**
+ * Apply a config-bundle env to process.env, honoring the federation guard.
+ * Used by both the entrypoint and syncConfig(). Returns the keys whose value
+ * changed (names only, for logging).
+ */
+export function applyEnvToProcess(
+  env: Record<string, string>,
+  deps: GuardDeps = {},
+): string[] {
+  const processEnv = deps.processEnv ?? process.env;
+  const filtered = filterAnthropicCredentials(env, deps);
+  const changed = Object.keys(filtered).filter(
+    (key) => filtered[key] !== processEnv[key],
+  );
+  Object.assign(processEnv, filtered);
+  return changed;
+}