@app-vitals/agent-runtime 0.0.1 → 0.1.0

package/cleanup-after-days-ref.ts

@@ -0,0 +1,83 @@
+/**
+ * agent/src/runtime/cleanup-after-days-ref.ts
+ *
+ * A tiny mutable box holding the agent's most recently synced
+ * `cleanupAfterDays` policy field (APM-1.6), so downstream consumers
+ * (check-helpers.ts's readCleanupAfterDays()) 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 allow-self-review-ref.ts's style
+ * exactly.
+ */
+
+export interface CleanupAfterDaysRef {
+  /**
+   * Returns the most recently synced `cleanupAfterDays` value, or `14` if
+   * set() was never called. The underlying Agent row field defaults to `14`
+   * in the database (admin/prisma/schema/), so once synced this
+   * always reflects a real DB value — callers that need to distinguish
+   * "never synced" (config-bundle fetch has never succeeded) from "synced
+   * to a DB value of 14" must check hasSynced() rather than inferring it
+   * from this return value, since both states return 14.
+   */
+  get(): number;
+  /**
+   * True once set() has been called at least once. readCleanupAfterDays()
+   * returns its hardcoded default while this is false (config-sync has
+   * never succeeded, e.g. the fetch keeps failing).
+   */
+  hasSynced(): boolean;
+  /** Replaces the current cleanupAfterDays value. */
+  set(cleanupAfterDays: number): void;
+}
+
+/** Creates a new, independent cleanup-after-days ref defaulting to unsynced/14. */
+export function createCleanupAfterDaysRef(): CleanupAfterDaysRef {
+  let cleanupAfterDays = 14;
+  let synced = false;
+
+  return {
+    get(): number {
+      return cleanupAfterDays;
+    },
+    hasSynced(): boolean {
+      return synced;
+    },
+    set(next: number): void {
+      cleanupAfterDays = next;
+      synced = true;
+    },
+  };
+}
+
+/**
+ * The process-wide cleanup-after-days ref. agent/src/index.ts's syncConfig()
+ * writes into this on every successful config-sync tick; check-helpers.ts's
+ * readCleanupAfterDays() reads it with a hardcoded default when unsynced, so a DB-side change (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 — readers must
+ * return their hardcoded default in that case.
+ */
+export const cleanupAfterDaysRef: CleanupAfterDaysRef =
+  createCleanupAfterDaysRef();
+
+/**
+ * Read the `cleanup_after_days` policy field: the synced DB value from
+ * `configRef` (default: the process-wide `cleanupAfterDaysRef`), else the
+ * hardcoded default `14` while the ref has never synced.
+ *
+ * WTR-1.4: reused as the staleness threshold gating the force-removal of a
+ * merged/closed PR's worktree (see `removeWorktree`'s production
+ * implementation in pr-state-reconciler.ts) — the same field that governs
+ * "remove worktrees older than N days, even if the PR is still open" also
+ * governs "don't force-remove a worktree younger than N days even if its PR
+ * just merged/closed", so a worktree still being actively worked on by a
+ * concurrent dev-task/patch/deploy session isn't yanked out from under it
+ * purely on remote GitHub state.
+ */
+export async function readCleanupAfterDays(
+  _workspacePath: string,
+  configRef: CleanupAfterDaysRef = cleanupAfterDaysRef,
+): Promise<number> {
+  return configRef.hasSynced() ? configRef.get() : 14;
+}

package/cleanup-after-days-ref.unit.test.ts

@@ -0,0 +1,89 @@
+/**
+ * agent/src/runtime/cleanup-after-days-ref.unit.test.ts
+ *
+ * Unit tests for createCleanupAfterDaysRef() — pure logic, no I/O.
+ * Mirrors allow-self-review-ref.unit.test.ts's coverage pattern.
+ *
+ * Deliberately does NOT exercise the process-wide `cleanupAfterDaysRef`
+ * singleton's set() here (unlike allow-self-review-ref.unit.test.ts) — once
+ * set() is called, hasSynced() can never be un-set, so mutating the shared
+ * singleton would permanently poison it for the rest of this bun test
+ * process (this repo's test-isolation hard rule: "Bun shares the test
+ * process, so leaked globals break sibling suites"). That would silently
+ * break check-helpers.unit.test.ts's readCleanupAfterDays() "no injected
+ * ref" tests, which rely on the singleton staying unsynced.
+ * createCleanupAfterDaysRef() exercises identical get/hasSynced/set logic on
+ * an independent instance, so coverage is unaffected.
+ */
+
+import { describe, expect, it, test } from "bun:test";
+import {
+  createCleanupAfterDaysRef,
+  readCleanupAfterDays,
+} from "./cleanup-after-days-ref.ts";
+
+describe("createCleanupAfterDaysRef", () => {
+  it("initial get() before any set() returns 14 (matches the DB/file default)", () => {
+    const ref = createCleanupAfterDaysRef();
+    expect(ref.get()).toBe(14);
+  });
+
+  it("hasSynced() is false before any set() call", () => {
+    const ref = createCleanupAfterDaysRef();
+    expect(ref.hasSynced()).toBe(false);
+  });
+
+  it("hasSynced() becomes true after the first set(), even if set to the default value", () => {
+    const ref = createCleanupAfterDaysRef();
+    ref.set(14);
+    expect(ref.hasSynced()).toBe(true);
+    expect(ref.get()).toBe(14);
+  });
+
+  it("hasSynced() stays true after subsequent set() calls, regardless of value", () => {
+    const ref = createCleanupAfterDaysRef();
+    ref.set(30);
+    expect(ref.hasSynced()).toBe(true);
+
+    ref.set(7);
+    expect(ref.hasSynced()).toBe(true);
+  });
+
+  it("returns the most recently set value regardless of how many times set() was called", () => {
+    const ref = createCleanupAfterDaysRef();
+    ref.set(30);
+    expect(ref.get()).toBe(30);
+
+    ref.set(7);
+    expect(ref.get()).toBe(7);
+
+    ref.set(21);
+    expect(ref.get()).toBe(21);
+  });
+
+  it("multiple independent ref instances don't share state", () => {
+    const refA = createCleanupAfterDaysRef();
+    const refB = createCleanupAfterDaysRef();
+
+    refA.set(30);
+
+    expect(refA.get()).toBe(30);
+    expect(refB.get()).toBe(14);
+    expect(refA.hasSynced()).toBe(true);
+    expect(refB.hasSynced()).toBe(false);
+  });
+});
+
+describe("readCleanupAfterDays", () => {
+  test("never-synced ref (config fetch failing) returns the hardcoded default 14", async () => {
+    expect(
+      await readCleanupAfterDays("/nonexistent", createCleanupAfterDaysRef()),
+    ).toBe(14);
+  });
+
+  test("DB-hit: an injected ref that has synced is returned", async () => {
+    const configRef = createCleanupAfterDaysRef();
+    configRef.set(30);
+    expect(await readCleanupAfterDays("/nonexistent", configRef)).toBe(30);
+  });
+});

package/cleanup-merged-worktrees-ref.ts

@@ -0,0 +1,75 @@
+/**
+ * agent/src/runtime/cleanup-merged-worktrees-ref.ts
+ *
+ * A tiny mutable box holding the agent's most recently synced
+ * `cleanupMergedWorktrees` policy field (APM-1.6), so downstream consumers
+ * (check-helpers.ts's readCleanupMergedWorktrees()) 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 allow-self-review-ref.ts's style
+ * exactly.
+ */
+
+export interface CleanupMergedWorktreesRef {
+  /**
+   * Returns the most recently synced `cleanupMergedWorktrees` value, or
+   * `true` if set() was never called. The underlying Agent row field
+   * defaults to `true` in the database (admin/prisma/schema/), so once
+   * synced this always reflects a real DB value — callers that need to
+   * distinguish "never synced" (config-bundle fetch has never succeeded)
+   * from "synced to a DB value of true" must check hasSynced() rather than
+   * inferring it from this return value, since both states return true.
+   */
+  get(): boolean;
+  /**
+   * True once set() has been called at least once. readCleanupMergedWorktrees()
+   * returns its hardcoded default while this is false (config-sync has
+   * never succeeded, e.g. the fetch keeps failing).
+   */
+  hasSynced(): boolean;
+  /** Replaces the current cleanupMergedWorktrees value. */
+  set(cleanupMergedWorktrees: boolean): void;
+}
+
+/** Creates a new, independent cleanup-merged-worktrees ref defaulting to unsynced/true. */
+export function createCleanupMergedWorktreesRef(): CleanupMergedWorktreesRef {
+  let cleanupMergedWorktrees = true;
+  let synced = false;
+
+  return {
+    get(): boolean {
+      return cleanupMergedWorktrees;
+    },
+    hasSynced(): boolean {
+      return synced;
+    },
+    set(next: boolean): void {
+      cleanupMergedWorktrees = next;
+      synced = true;
+    },
+  };
+}
+
+/**
+ * The process-wide cleanup-merged-worktrees ref. agent/src/index.ts's
+ * syncConfig() writes into this on every successful config-sync tick;
+ * check-helpers.ts's readCleanupMergedWorktrees() reads it with a hardcoded default when unsynced, so a DB-side change (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 — readers
+ * readers must return their hardcoded default in that case.
+ */
+export const cleanupMergedWorktreesRef: CleanupMergedWorktreesRef =
+  createCleanupMergedWorktreesRef();
+
+/**
+ * Read the `cleanup_merged_worktrees` policy field (WTR-1.1): the synced DB
+ * value from `configRef` (default: the process-wide
+ * `cleanupMergedWorktreesRef`), else the hardcoded default `true` while the
+ * ref has never synced. Same shape as `readAllowSelfReview()`.
+ */
+export async function readCleanupMergedWorktrees(
+  _workspacePath: string,
+  configRef: CleanupMergedWorktreesRef = cleanupMergedWorktreesRef,
+): Promise<boolean> {
+  return configRef.hasSynced() ? configRef.get() : true;
+}

package/cleanup-merged-worktrees-ref.unit.test.ts

@@ -0,0 +1,72 @@
+/**
+ * agent/src/runtime/cleanup-merged-worktrees-ref.unit.test.ts
+ *
+ * Unit tests for createCleanupMergedWorktreesRef() — pure logic, no I/O.
+ * Mirrors allow-self-review-ref.unit.test.ts's coverage pattern.
+ *
+ * Deliberately does NOT exercise the process-wide `cleanupMergedWorktreesRef`
+ * singleton's set() here (unlike allow-self-review-ref.unit.test.ts) — once
+ * set() is called, hasSynced() can never be un-set, so mutating the shared
+ * singleton would permanently poison it for the rest of this bun test
+ * process (this repo's test-isolation hard rule: "Bun shares the test
+ * process, so leaked globals break sibling suites"). That would silently
+ * break check-helpers.unit.test.ts's readCleanupMergedWorktrees()
+ * "no injected ref" tests, which rely on the singleton staying unsynced.
+ * createCleanupMergedWorktreesRef() exercises identical get/hasSynced/set
+ * logic on an independent instance, so coverage is unaffected.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { createCleanupMergedWorktreesRef } from "./cleanup-merged-worktrees-ref.ts";
+
+describe("createCleanupMergedWorktreesRef", () => {
+  it("initial get() before any set() returns true (matches the DB/file default)", () => {
+    const ref = createCleanupMergedWorktreesRef();
+    expect(ref.get()).toBe(true);
+  });
+
+  it("hasSynced() is false before any set() call", () => {
+    const ref = createCleanupMergedWorktreesRef();
+    expect(ref.hasSynced()).toBe(false);
+  });
+
+  it("hasSynced() becomes true after the first set(), even if set to false", () => {
+    const ref = createCleanupMergedWorktreesRef();
+    ref.set(false);
+    expect(ref.hasSynced()).toBe(true);
+    expect(ref.get()).toBe(false);
+  });
+
+  it("hasSynced() stays true after subsequent set() calls, regardless of value", () => {
+    const ref = createCleanupMergedWorktreesRef();
+    ref.set(false);
+    expect(ref.hasSynced()).toBe(true);
+
+    ref.set(true);
+    expect(ref.hasSynced()).toBe(true);
+  });
+
+  it("returns the most recently set value regardless of how many times set() was called", () => {
+    const ref = createCleanupMergedWorktreesRef();
+    ref.set(false);
+    expect(ref.get()).toBe(false);
+
+    ref.set(true);
+    expect(ref.get()).toBe(true);
+
+    ref.set(false);
+    expect(ref.get()).toBe(false);
+  });
+
+  it("multiple independent ref instances don't share state", () => {
+    const refA = createCleanupMergedWorktreesRef();
+    const refB = createCleanupMergedWorktreesRef();
+
+    refA.set(false);
+
+    expect(refA.get()).toBe(false);
+    expect(refB.get()).toBe(true);
+    expect(refA.hasSynced()).toBe(true);
+    expect(refB.hasSynced()).toBe(false);
+  });
+});

package/cli-args.ts

@@ -0,0 +1,36 @@
+/**
+ * agent/src/runtime/cli-args.ts
+ *
+ * CLI argument parsing for the agent entrypoint.
+ *
+ * Parses --agent-id, --api-url, --api-key flags from argv.
+ * Falls back to environment variables when flags are absent.
+ * Pure — no I/O, no process.env reads at module level.
+ */
+
+import { parseFlags } from "@app-vitals/agent-lib/cli-flags";
+
+interface CliArgs {
+  agentId: string | undefined;
+  apiUrl: string | undefined;
+  apiKey: string | undefined;
+}
+
+/**
+ * Parses CLI arguments and merges with env var fallbacks.
+ *
+ * @param argv - argument list (without the node/bun executable prefix, i.e. process.argv.slice(2))
+ * @param env  - environment variable map (pass process.env or a subset for testing)
+ */
+export function parseCliArgs(
+  argv: string[],
+  env: Record<string, string | undefined>,
+): CliArgs {
+  const flags = parseFlags(argv, ["--agent-id", "--api-url", "--api-key"]);
+
+  return {
+    agentId: flags["--agent-id"] ?? env.SHIPWRIGHT_AGENT_ID,
+    apiUrl: flags["--api-url"] ?? env.SHIPWRIGHT_API_URL,
+    apiKey: flags["--api-key"] ?? env.SHIPWRIGHT_AGENT_API_KEY,
+  };
+}

package/cli-args.unit.test.ts

@@ -0,0 +1,94 @@
+/**
+ * agent/src/runtime/cli-args.unit.test.ts
+ *
+ * Unit tests for CLI argument parsing.
+ * Pure logic — no I/O, no env side effects.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { parseCliArgs } from "./cli-args.ts";
+
+describe("parseCliArgs — explicit flags", () => {
+  it("parses --agent-id", () => {
+    const result = parseCliArgs(["--agent-id", "agent-123"], {});
+    expect(result.agentId).toBe("agent-123");
+  });
+
+  it("parses --api-url", () => {
+    const result = parseCliArgs(["--api-url", "https://api.example.com"], {});
+    expect(result.apiUrl).toBe("https://api.example.com");
+  });
+
+  it("parses --api-key", () => {
+    const result = parseCliArgs(["--api-key", "secret-key"], {});
+    expect(result.apiKey).toBe("secret-key");
+  });
+
+  it("parses all three flags together", () => {
+    const result = parseCliArgs(
+      [
+        "--agent-id",
+        "agent-abc",
+        "--api-url",
+        "https://api.test.com",
+        "--api-key",
+        "key-xyz",
+      ],
+      {},
+    );
+    expect(result.agentId).toBe("agent-abc");
+    expect(result.apiUrl).toBe("https://api.test.com");
+    expect(result.apiKey).toBe("key-xyz");
+  });
+
+  it("supports --flag=value syntax via the shared parser", () => {
+    const result = parseCliArgs(
+      ["--agent-id=eq-agent", "--api-url=https://eq.test"],
+      {},
+    );
+    expect(result.agentId).toBe("eq-agent");
+    expect(result.apiUrl).toBe("https://eq.test");
+  });
+
+  it("ignores unknown flags", () => {
+    const result = parseCliArgs(["--unknown", "value", "--agent-id", "x"], {});
+    expect(result.agentId).toBe("x");
+  });
+});
+
+describe("parseCliArgs — env var fallback", () => {
+  it("falls back to SHIPWRIGHT_AGENT_ID when --agent-id not provided", () => {
+    const result = parseCliArgs([], {
+      SHIPWRIGHT_AGENT_ID: "env-agent-id",
+    });
+    expect(result.agentId).toBe("env-agent-id");
+  });
+
+  it("falls back to SHIPWRIGHT_API_URL when --api-url not provided", () => {
+    const result = parseCliArgs([], {
+      SHIPWRIGHT_API_URL: "https://env.api.com",
+    });
+    expect(result.apiUrl).toBe("https://env.api.com");
+  });
+
+  it("falls back to SHIPWRIGHT_AGENT_API_KEY when --api-key not provided", () => {
+    const result = parseCliArgs([], {
+      SHIPWRIGHT_AGENT_API_KEY: "env-key",
+    });
+    expect(result.apiKey).toBe("env-key");
+  });
+
+  it("CLI flags take precedence over env vars", () => {
+    const result = parseCliArgs(["--agent-id", "cli-agent"], {
+      SHIPWRIGHT_AGENT_ID: "env-agent",
+    });
+    expect(result.agentId).toBe("cli-agent");
+  });
+
+  it("returns undefined when neither flag nor env var is set", () => {
+    const result = parseCliArgs([], {});
+    expect(result.agentId).toBeUndefined();
+    expect(result.apiUrl).toBeUndefined();
+    expect(result.apiKey).toBeUndefined();
+  });
+});

package/clock.ts

@@ -0,0 +1,47 @@
+/**
+ * agent/src/runtime/clock.ts
+ * Clock interface and production implementation for injectable time.
+ *
+ * Any code that needs the current time should accept a `Clock` via dependency
+ * injection rather than calling `new Date()` or `Date.now()` directly.
+ * This makes time-dependent logic trivially testable and deterministic.
+ */
+
+// ─── Interface ────────────────────────────────────────────────────────────────
+
+export interface Clock {
+  /** Returns the current time as a Date. */
+  now(): Date;
+}
+
+// ─── SystemClock ──────────────────────────────────────────────────────────────
+
+/**
+ * Production clock — delegates to the real system time.
+ *
+ * @example
+ * const clock = SystemClock();
+ * clock.now(); // → current wall-clock time
+ */
+export function SystemClock(): Clock {
+  return {
+    now(): Date {
+      return new Date();
+    },
+  };
+}
+
+/**
+ * Fixed-time clock for deterministic testing.
+ *
+ * @example
+ * const clock = FixedClock(new Date("2024-01-01T00:00:00Z"));
+ * clock.now(); // → always 2024-01-01T00:00:00.000Z
+ */
+export function FixedClock(date: Date): Clock {
+  return {
+    now(): Date {
+      return date;
+    },
+  };
+}

package/config.ts

@@ -0,0 +1,99 @@
+import { join } from "node:path";
+import { DEFAULT_CLAUDE_TIMEOUT_MS } from "@app-vitals/agent-lib/claude-timeout";
+import { DEFAULT_ANTHROPIC_MODEL } from "@app-vitals/agent-lib/default-agent-env";
+
+/**
+ * Idle-reset timeout default (25min) — cleared/restarted on every stdout line
+ * from a `claude -p` session (see `agent/src/runtime/claude.ts`'s `_spawn`). This is
+ * the primary timeout in practice; calibrated from a 900-session log analysis
+ * (p99 inter-line gap 713s, largest legitimate single gap 1303s from an
+ * `Agent()` subagent delegation). `DEFAULT_CLAUDE_TIMEOUT_MS` (1hr, in
+ * `@app-vitals/agent-lib/claude-timeout`) is the hard ceiling backstop, not primary.
+ */
+const DEFAULT_CLAUDE_IDLE_TIMEOUT_MS = 1_500_000;
+
+function optional(key: string): string | undefined {
+  return process.env[key];
+}
+
+/**
+ * Reads a positive-integer millisecond env var, falling back to `fallback`
+ * when the value is unset, non-numeric, non-integer, zero, or negative — so a
+ * malformed override never silently disables or shortens the timeout.
+ */
+function positiveIntMs(key: string, fallback: number): number {
+  const raw = optional(key);
+  if (raw === undefined) return fallback;
+  const parsed = Number(raw);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function buildConfig(agentHome: string) {
+  return {
+    claude: {
+      model: optional("ANTHROPIC_MODEL") ?? DEFAULT_ANTHROPIC_MODEL,
+      fallbackModel: optional("ANTHROPIC_FALLBACK_MODEL"),
+      effortLevel: optional("ANTHROPIC_EFFORT_LEVEL"),
+      timeoutMs: positiveIntMs(
+        "SHIPWRIGHT_CLAUDE_TIMEOUT_MS",
+        DEFAULT_CLAUDE_TIMEOUT_MS,
+      ),
+      idleTimeoutMs: positiveIntMs(
+        "SHIPWRIGHT_CLAUDE_IDLE_TIMEOUT_MS",
+        DEFAULT_CLAUDE_IDLE_TIMEOUT_MS,
+      ),
+      anthropicApiKey: optional("ANTHROPIC_API_KEY"),
+      oauthToken: optional("CLAUDE_CODE_OAUTH_TOKEN"),
+    },
+    shipwright: {
+      apiUrl: optional("SHIPWRIGHT_API_URL"),
+      apiKey: optional("SHIPWRIGHT_AGENT_API_KEY"),
+      agentId: optional("SHIPWRIGHT_AGENT_ID"),
+    },
+    slack: {
+      botToken: optional("SLACK_BOT_TOKEN"),
+      appToken: optional("SLACK_APP_TOKEN"),
+      signingSecret: optional("SLACK_SIGNING_SECRET"),
+      adminToken: optional("SLACK_ADMIN_TOKEN"),
+    },
+    alerts: {
+      channel: optional("SLACK_ALERT_CHANNEL"),
+    },
+    owner: {
+      user: optional("SLACK_OWNER_USER"),
+    },
+    voice: {
+      groqApiKey: optional("GROQ_API_KEY"),
+      elevenLabsApiKey: optional("ELEVENLABS_API_KEY"),
+      voiceId: optional("ELEVENLABS_VOICE_ID"),
+      piperVoice: optional("PIPER_VOICE"),
+      whisperServiceUrl: optional("WHISPER_SERVICE_URL"),
+    },
+    chat: {
+      serviceUrl: optional("SHIPWRIGHT_CHAT_SERVICE_URL"),
+      serviceToken: optional("SHIPWRIGHT_CHAT_SERVICE_TOKEN"),
+      pollIntervalMs: optional("SHIPWRIGHT_CHAT_POLL_INTERVAL_MS")
+        ? Number(optional("SHIPWRIGHT_CHAT_POLL_INTERVAL_MS"))
+        : undefined,
+    },
+    paths: {
+      home: agentHome,
+      workspace: join(agentHome, "workspace"),
+      sessions: join(agentHome, "sessions.json"),
+      chatSessions: join(agentHome, "chat-sessions.json"),
+    },
+  } as const;
+}
+
+/**
+ * Creates config from a given agent home directory.
+ * Reads env vars at call time — no module-level side effects.
+ *
+ * AGENT_HOME defaults to ~/.shipwright-agent/ at the call site (index.ts).
+ * Not defaulted here to avoid module-level env reads.
+ */
+export function createConfig(agentHome: string) {
+  return {
+    config: buildConfig(agentHome),
+  };
+}