@app-vitals/agent-runtime 0.0.1 → 0.1.0

package/health.smoke.test.ts

@@ -0,0 +1,244 @@
+/**
+ * Smoke tests for startHealthServer() in agent/src/runtime/health.ts
+ *
+ * These tests boot real Bun.serve() instances on localhost ports and make
+ * live fetch() calls to exercise HTTP route contracts (status codes,
+ * response shapes) — an HTTP-server-booting test belongs in smoke per
+ * docs/test-readiness/test-system.md, even though it uses a real socket
+ * rather than Hono's app.request().
+ */
+
+import { afterEach, describe, expect, it } from "bun:test";
+import type { Server } from "bun";
+import { FixedClock } from "./clock.ts";
+import {
+  claudeVersionState,
+  markSlackConnected,
+  markSlackDisconnected,
+  SLACK_DOWN_GRACE_MS,
+  slackState,
+  startHealthServer,
+} from "./health.ts";
+
+describe("startHealthServer", () => {
+  const servers: Server<undefined>[] = [];
+
+  afterEach(() => {
+    for (const s of servers) s.stop(true);
+    servers.length = 0;
+    slackState.connected = false;
+    slackState.downSince = null;
+    claudeVersionState.version = "unknown";
+  });
+
+  function serve(port: number): Server<undefined> {
+    const s = startHealthServer(port);
+    servers.push(s);
+    return s;
+  }
+
+  it("GET /health returns 200 with slack disconnected when not connected", async () => {
+    slackState.connected = false;
+    slackState.downSince = null;
+    serve(19901);
+    const res = await fetch("http://localhost:19901/health");
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toEqual({
+      ok: true,
+      slack: "disconnected",
+      claudeCodeVersion: "unknown",
+    });
+  });
+
+  it("GET /health returns slack connected when slackState.connected is true", async () => {
+    slackState.connected = true;
+    serve(19902);
+    const res = await fetch("http://localhost:19902/health");
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toEqual({
+      ok: true,
+      slack: "connected",
+      claudeCodeVersion: "unknown",
+    });
+  });
+
+  it("reflects state changes at runtime without restart", async () => {
+    slackState.connected = false;
+    slackState.downSince = null;
+    serve(19903);
+
+    const res1 = await fetch("http://localhost:19903/health");
+    expect((await res1.json()).slack).toBe("disconnected");
+
+    slackState.connected = true;
+    const res2 = await fetch("http://localhost:19903/health");
+    expect((await res2.json()).slack).toBe("connected");
+
+    slackState.connected = false;
+    const res3 = await fetch("http://localhost:19903/health");
+    expect((await res3.json()).slack).toBe("disconnected");
+  });
+
+  it("GET /health reports the detected claudeCodeVersion", async () => {
+    claudeVersionState.version = "2.1.236";
+    serve(19906);
+    const res = await fetch("http://localhost:19906/health");
+    expect(res.status).toBe(200);
+    expect((await res.json()).claudeCodeVersion).toBe("2.1.236");
+  });
+
+  it("GET /health includes claudeCodeVersion on the 500 wedge response too", async () => {
+    claudeVersionState.version = "2.1.236";
+    const downAt = new Date("2026-06-06T00:00:00.000Z").getTime();
+    const clock = FixedClock(new Date(downAt + SLACK_DOWN_GRACE_MS + 1_000));
+    slackState.connected = false;
+    slackState.downSince = downAt;
+    servers.push(startHealthServer(19907, undefined, clock));
+    const res = await fetch("http://localhost:19907/health");
+    expect(res.status).toBe(500);
+    expect((await res.json()).claudeCodeVersion).toBe("2.1.236");
+  });
+
+  it("returns 404 for unknown paths", async () => {
+    serve(19904);
+    const res = await fetch("http://localhost:19904/not-a-thing");
+    expect(res.status).toBe(404);
+  });
+
+  it("returns 404 for POST /health", async () => {
+    serve(19905);
+    const res = await fetch("http://localhost:19905/health", {
+      method: "POST",
+    });
+    expect(res.status).toBe(404);
+  });
+
+  // ─── Self-heal grace-window behavior ──────────────────────────────────────
+
+  // A1: Healthy → 200 connected
+  it("GET /health returns 200 connected when socket is up", async () => {
+    const clock = FixedClock(new Date("2026-06-06T00:00:00.000Z"));
+    slackState.connected = true;
+    slackState.downSince = null;
+    const s = startHealthServer(19910, undefined, clock);
+    servers.push(s);
+    const res = await fetch("http://localhost:19910/health");
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({
+      ok: true,
+      slack: "connected",
+      claudeCodeVersion: "unknown",
+    });
+  });
+
+  // A2: Disconnected but within grace window → 200 disconnected
+  it("GET /health returns 200 when disconnected within grace window", async () => {
+    const downAt = new Date("2026-06-06T00:00:00.000Z").getTime();
+    // Server clock 30s later — well under the 90s grace window.
+    const clock = FixedClock(new Date("2026-06-06T00:00:30.000Z"));
+    slackState.connected = false;
+    slackState.downSince = downAt;
+    const s = startHealthServer(19911, undefined, clock);
+    servers.push(s);
+    const res = await fetch("http://localhost:19911/health");
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({
+      ok: true,
+      slack: "disconnected",
+      claudeCodeVersion: "unknown",
+    });
+  });
+
+  // A3: Disconnected beyond grace window → 500 disconnected
+  it("GET /health returns 500 when disconnected beyond grace window", async () => {
+    const downAt = new Date("2026-06-06T00:00:00.000Z").getTime();
+    // Server clock past the grace window.
+    const clock = FixedClock(new Date(downAt + SLACK_DOWN_GRACE_MS + 1_000));
+    slackState.connected = false;
+    slackState.downSince = downAt;
+    const s = startHealthServer(19912, undefined, clock);
+    servers.push(s);
+    const res = await fetch("http://localhost:19912/health");
+    expect(res.status).toBe(500);
+    expect(await res.json()).toEqual({
+      ok: false,
+      slack: "disconnected",
+      claudeCodeVersion: "unknown",
+    });
+  });
+
+  // A4: Recovery — markSlackConnected clears downSince → 200 again
+  it("GET /health returns 200 again after recovery from a wedge", async () => {
+    const downAt = new Date("2026-06-06T00:00:00.000Z").getTime();
+    const clock = FixedClock(new Date(downAt + SLACK_DOWN_GRACE_MS + 1_000));
+    slackState.connected = false;
+    slackState.downSince = downAt;
+    const s = startHealthServer(19913, undefined, clock);
+    servers.push(s);
+
+    const wedged = await fetch("http://localhost:19913/health");
+    expect(wedged.status).toBe(500);
+
+    markSlackConnected();
+    expect(slackState.connected).toBe(true);
+    expect(slackState.downSince).toBeNull();
+
+    const recovered = await fetch("http://localhost:19913/health");
+    expect(recovered.status).toBe(200);
+    expect(await recovered.json()).toEqual({
+      ok: true,
+      slack: "connected",
+      claudeCodeVersion: "unknown",
+    });
+  });
+
+  // A5: Cold start / never connected → 200 (not killed during initial connect)
+  it("GET /health returns 200 at cold start before first connect", async () => {
+    const clock = FixedClock(new Date("2026-06-06T05:00:00.000Z"));
+    slackState.connected = false;
+    slackState.downSince = null;
+    const s = startHealthServer(19914, undefined, clock);
+    servers.push(s);
+    const res = await fetch("http://localhost:19914/health");
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({
+      ok: true,
+      slack: "disconnected",
+      claudeCodeVersion: "unknown",
+    });
+  });
+
+  // A6: Repeated markSlackDisconnected does not push downSince forward
+  it("markSlackDisconnected anchors downSince to the first drop", () => {
+    slackState.connected = true;
+    slackState.downSince = null;
+
+    const first = FixedClock(new Date("2026-06-06T00:00:00.000Z"));
+    markSlackDisconnected(first);
+    const firstDown = slackState.downSince as unknown as number;
+    expect(firstDown).toBe(new Date("2026-06-06T00:00:00.000Z").getTime());
+
+    // A later error event must NOT reset/extend the timer.
+    const later = FixedClock(new Date("2026-06-06T00:01:00.000Z"));
+    markSlackDisconnected(later);
+    expect(slackState.downSince as number | null).toBe(firstDown);
+  });
+
+  it("markSlackConnected then markSlackDisconnected re-anchors after reconnect", () => {
+    slackState.connected = false;
+    slackState.downSince = null;
+
+    const first = FixedClock(new Date("2026-06-06T00:00:00.000Z"));
+    markSlackDisconnected(first);
+    expect(slackState.downSince as number | null).toBe(first.now().getTime());
+
+    markSlackConnected();
+    expect(slackState.downSince).toBeNull();
+
+    const second = FixedClock(new Date("2026-06-06T01:00:00.000Z"));
+    markSlackDisconnected(second);
+    expect(slackState.downSince as number | null).toBe(second.now().getTime());
+  });
+});

package/health.ts

@@ -0,0 +1,193 @@
+import type { ErrorCapturingClient } from "@app-vitals/agent-lib/sentry";
+import type { Server } from "bun";
+import { Hono } from "hono";
+import { reportClaudeError } from "./claude.ts";
+import { UNKNOWN_CLAUDE_CODE_VERSION } from "./claude-version.ts";
+import { type Clock, SystemClock } from "./clock.ts";
+import {
+  type CronHandlerDeps,
+  handleCronRequest,
+  ValidationError,
+} from "./cron-handler.ts";
+
+/**
+ * Shared connection state — mutated by index.ts as Slack socket connects/disconnects.
+ *
+ * `downSince` is the epoch-ms timestamp of the connected→disconnected transition
+ * (anchored to the FIRST drop, see markSlackDisconnected), or `null` when the
+ * socket is up or has never connected. It is the anchor for the grace-window
+ * wedge detection in /health.
+ */
+export const slackState = {
+  connected: false,
+  downSince: null as number | null,
+};
+
+/** Claude Code CLI version detected at startup (set by index.ts); reported in /health. */
+export const claudeVersionState = {
+  version: UNKNOWN_CLAUDE_CODE_VERSION,
+};
+
+/**
+ * How long the Slack socket may stay down before /health reports unhealthy (500).
+ * Sized above the liveness probe blip tolerance so transient reconnects don't
+ * trip the probe, while a sustained wedge does. K8s liveness on /health is
+ * periodSeconds=30, failureThreshold=3 — ~90s of failures triggers a restart.
+ */
+export const SLACK_DOWN_GRACE_MS = 90_000;
+
+/** Default port for the dedicated health server (SHIPWRIGHT_HEALTH_PORT). */
+export const DEFAULT_HEALTH_PORT = 3459;
+
+/** Mark the Slack socket as connected and clear the down-timer. */
+export function markSlackConnected(): void {
+  slackState.connected = true;
+  slackState.downSince = null;
+}
+
+/**
+ * Mark the Slack socket as disconnected.
+ *
+ * Anchors `downSince` to the FIRST drop only — repeated `error`/`disconnecting`
+ * events while already down must not keep resetting the timer (that would let a
+ * flapping-but-wedged socket extend the grace window indefinitely).
+ */
+export function markSlackDisconnected(clock: Clock): void {
+  slackState.connected = false;
+  if (slackState.downSince === null) {
+    slackState.downSince = clock.now().getTime();
+  }
+}
+
+/**
+ * Create a minimal Hono health app for container liveness probes.
+ *
+ * GET /health → 200 { status: "ok" }
+ *
+ * No Slack state — the Shipwright reference agent is a CLI runner, not a
+ * long-lived Slack socket process.
+ */
+export function createHealthApp(): Hono {
+  const app = new Hono();
+  app.get("/health", (c) => c.json({ status: "ok" }));
+  return app;
+}
+
+/**
+ * Start a minimal HTTP health server for K8s liveness probes.
+ *
+ * GET  /health → 200 { ok: true, slack: "connected" | "disconnected", claudeCodeVersion }
+ *              → 500 { ok: false, slack: "disconnected", claudeCodeVersion } when
+ *                the socket has been down longer than `graceMs` (sustained wedge)
+ * GET  /cron   → 405 Method Not Allowed
+ * POST /cron   → run a cron prompt through Claude and post result to Slack
+ *               503 if cronDeps not configured
+ *               400 for bad JSON or missing jobId/prompt
+ *               422 for ValidationError (e.g. missing delivery target)
+ *               500 for runner errors
+ *               200 on success
+ * Other routes → 404
+ *
+ * /health returns 500 ONLY when the Slack socket has been continuously down for
+ * longer than `graceMs` — this is the self-heal path: a sustained wedge trips the
+ * K8s liveness probe → pod restart → fresh socket. Transient reconnect blips and
+ * the not-yet-connected startup window (downSince === null) stay 200 so the pod
+ * is not killed during normal reconnects or cold start.
+ *
+ * `sentryClient` is optional — when absent (Sentry not initialized, i.e.
+ * SENTRY_DSN unset), the POST /cron catch block simply skips the capture call
+ * and behaves exactly as before. Only unhandled runner/delivery errors are
+ * reported; ValidationError (422) is an expected, typed outcome and is not.
+ */
+export function startHealthServer(
+  port: number,
+  cronDeps?: CronHandlerDeps,
+  clock: Clock = SystemClock(),
+  graceMs: number = SLACK_DOWN_GRACE_MS,
+  sentryClient?: ErrorCapturingClient,
+): Server<undefined> {
+  return Bun.serve({
+    port,
+    async fetch(req) {
+      const url = new URL(req.url);
+
+      if (url.pathname === "/health" && req.method === "GET") {
+        const wedged =
+          !slackState.connected &&
+          slackState.downSince !== null &&
+          clock.now().getTime() - slackState.downSince > graceMs;
+        if (wedged) {
+          return Response.json(
+            {
+              ok: false,
+              slack: "disconnected",
+              claudeCodeVersion: claudeVersionState.version,
+            },
+            { status: 500 },
+          );
+        }
+        return Response.json({
+          ok: true,
+          slack: slackState.connected ? "connected" : "disconnected",
+          claudeCodeVersion: claudeVersionState.version,
+        });
+      }
+
+      if (url.pathname === "/cron" && req.method === "GET") {
+        return new Response("Method Not Allowed", { status: 405 });
+      }
+
+      if (url.pathname === "/cron" && req.method === "POST") {
+        if (!cronDeps) {
+          return Response.json(
+            { error: "cron handler not configured" },
+            { status: 503 },
+          );
+        }
+        let body: unknown;
+        try {
+          body = await req.json();
+        } catch {
+          return Response.json({ error: "invalid JSON body" }, { status: 400 });
+        }
+        if (
+          typeof body !== "object" ||
+          body === null ||
+          typeof (body as Record<string, unknown>).jobId !== "string" ||
+          typeof (body as Record<string, unknown>).prompt !== "string"
+        ) {
+          return Response.json(
+            { error: "missing required fields: jobId, prompt" },
+            { status: 400 },
+          );
+        }
+        const { jobId, prompt, channel, user, silent, preCheck } =
+          body as Record<string, unknown>;
+        try {
+          await handleCronRequest(
+            {
+              jobId: jobId as string,
+              prompt: prompt as string,
+              channel: typeof channel === "string" ? channel : undefined,
+              user: typeof user === "string" ? user : undefined,
+              silent: typeof silent === "boolean" ? silent : undefined,
+              preCheck: typeof preCheck === "string" ? preCheck : undefined,
+            },
+            cronDeps,
+          );
+          return Response.json({ ok: true });
+        } catch (err) {
+          if (err instanceof ValidationError) {
+            return Response.json({ error: err.message }, { status: 422 });
+          }
+          reportClaudeError(sentryClient, err);
+          console.error("[agent:cron] handler error:", err);
+          const message = err instanceof Error ? err.message : String(err);
+          return Response.json({ error: message }, { status: 500 });
+        }
+      }
+
+      return new Response("Not Found", { status: 404 });
+    },
+  });
+}

package/health.unit.test.ts

@@ -0,0 +1,40 @@
+/**
+ * Unit tests for createHealthApp() in agent/src/runtime/health.ts
+ *
+ * Uses Hono's in-process app.request() — no real socket needed.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { createHealthApp } from "./health.ts";
+
+// ─── createHealthApp ──────────────────────────────────────────────────────────
+
+describe("GET /health (createHealthApp)", () => {
+  test("returns 200 with { status: 'ok' }", async () => {
+    const app = createHealthApp();
+    const res = await app.request("/health");
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { status: string };
+    expect(body).toEqual({ status: "ok" });
+  });
+
+  test("response is JSON", async () => {
+    const app = createHealthApp();
+    const res = await app.request("/health");
+    expect(res.headers.get("content-type")).toContain("application/json");
+  });
+});
+
+describe("unknown routes (createHealthApp)", () => {
+  test("GET /other returns 404", async () => {
+    const app = createHealthApp();
+    const res = await app.request("/other");
+    expect(res.status).toBe(404);
+  });
+
+  test("POST /health returns 404 (only GET is registered)", async () => {
+    const app = createHealthApp();
+    const res = await app.request("/health", { method: "POST" });
+    expect(res.status).toBe(404);
+  });
+});