@app-vitals/agent-runtime 0.0.1 → 0.1.1

package/chat-token-reporter.integration.test.ts

@@ -0,0 +1,282 @@
+/**
+ * Integration tests for HttpChatTokenReporter.
+ *
+ * Strategy: spin up a real Bun.serve stub admin API, inject its URL, and verify
+ * the reporter POSTs the correct daily-usage payload — no global.fetch overrides,
+ * no mock.module(). Time is injected via a FixedClock so the date is deterministic.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import {
+  formatDailyDate,
+  HttpChatTokenReporter,
+  NoopChatTokenReporter,
+} from "./chat-token-reporter.ts";
+import {
+  liveClaudeConfig,
+  type ModelUsage,
+  setLiveClaudeConfig,
+  type TokenUsage,
+} from "./claude.ts";
+import { FixedClock } from "./clock.ts";
+
+// ─── Shared helpers ───────────────────────────────────────────────────────────
+
+interface CapturedRequest {
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  body: unknown;
+}
+
+interface StubState {
+  captured: CapturedRequest[];
+  statusToReturn: number;
+}
+
+function startStubServer(
+  port: number,
+  state: StubState,
+  // biome-ignore lint/suspicious/noExplicitAny: Server type param varies by bun version
+): ReturnType<typeof Bun.serve<any>> {
+  return Bun.serve({
+    port,
+    fetch: async (req) => {
+      const body = await req.json().catch(() => null);
+      state.captured.push({
+        url: req.url,
+        method: req.method,
+        headers: Object.fromEntries(req.headers.entries()),
+        body,
+      });
+
+      if (state.statusToReturn >= 400) {
+        return new Response(JSON.stringify({ error: "stub error" }), {
+          status: state.statusToReturn,
+          headers: { "Content-Type": "application/json" },
+        });
+      }
+      return new Response(
+        JSON.stringify({ row: { id: "chat-token-daily-stub-1" } }),
+        {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        },
+      );
+    },
+  });
+}
+
+const USAGE: TokenUsage = {
+  input_tokens: 100,
+  output_tokens: 50,
+  cache_read_input_tokens: 20,
+  cache_creation_input_tokens: 10,
+};
+
+// ─── formatDailyDate ──────────────────────────────────────────────────────────
+
+describe("formatDailyDate", () => {
+  test("formats a Date as YYYY-MM-DD in the given timezone", () => {
+    const date = new Date("2026-01-15T12:00:00.000Z");
+    expect(formatDailyDate(date, "UTC")).toBe("2026-01-15");
+  });
+
+  test("respects the timezone when crossing a day boundary", () => {
+    // 00:30 UTC on the 15th is still the 14th in US Pacific.
+    const date = new Date("2026-01-15T00:30:00.000Z");
+    expect(formatDailyDate(date, "America/Los_Angeles")).toBe("2026-01-14");
+  });
+});
+
+// ─── HttpChatTokenReporter ────────────────────────────────────────────────────
+
+describe("HttpChatTokenReporter", () => {
+  // biome-ignore lint/suspicious/noExplicitAny: Server type param varies by bun version
+  let server: ReturnType<typeof Bun.serve<any>>;
+  let state: StubState;
+  let baseUrl: string;
+  const AGENT_ID = "agent-abc";
+  const API_KEY = "test-api-key";
+  const CLOCK = FixedClock(new Date("2026-01-15T12:00:00.000Z"));
+  let originalModel: string;
+
+  beforeEach(() => {
+    state = { captured: [], statusToReturn: 200 };
+    server = startStubServer(0, state);
+    baseUrl = `http://localhost:${server.port}`;
+    // liveClaudeConfig is a shared mutable module singleton (see claude.ts) —
+    // tests must not depend on the ambient ANTHROPIC_MODEL env var. Inject a
+    // model guaranteed to be present in pricing.ts's RATES table with a
+    // non-zero rate, and restore the original value in afterEach so this
+    // override doesn't leak into sibling test files sharing the same Bun
+    // test process.
+    originalModel = liveClaudeConfig.model;
+    setLiveClaudeConfig({ model: "claude-sonnet-4-6" });
+  });
+
+  afterEach(async () => {
+    await server.stop(true);
+    setLiveClaudeConfig({ model: originalModel });
+  });
+
+  function makeReporter() {
+    return new HttpChatTokenReporter({
+      apiUrl: baseUrl,
+      agentId: AGENT_ID,
+      apiKey: API_KEY,
+      clock: CLOCK,
+      timeZone: "UTC",
+    });
+  }
+
+  test("recordSession POSTs to /agents/:agentId/chat-tokens/daily", async () => {
+    const reporter = makeReporter();
+    await reporter.recordSession(USAGE);
+
+    expect(state.captured).toHaveLength(1);
+    expect(state.captured[0].method).toBe("POST");
+    expect(state.captured[0].url).toContain(
+      `/agents/${AGENT_ID}/chat-tokens/daily`,
+    );
+  });
+
+  test("recordSession sends the correct date and token fields in modelBreakdown", async () => {
+    const reporter = makeReporter();
+    await reporter.recordSession(USAGE);
+
+    const body = state.captured[0].body as Record<string, unknown>;
+    expect(body.date).toBe("2026-01-15");
+    expect(Array.isArray(body.modelBreakdown)).toBe(true);
+    const breakdown = body.modelBreakdown as Array<Record<string, unknown>>;
+    expect(breakdown.length).toBe(1);
+    expect(breakdown[0].inputTokens).toBe(100);
+    expect(breakdown[0].outputTokens).toBe(50);
+    expect(breakdown[0].cacheReadTokens).toBe(20);
+    expect(breakdown[0].cacheCreationTokens).toBe(10);
+  });
+
+  test("recordSession sends modelBreakdown when modelUsage is provided", async () => {
+    const reporter = makeReporter();
+    const modelUsage: ModelUsage = {
+      "claude-sonnet-4-5": {
+        inputTokens: 80,
+        outputTokens: 40,
+        cacheReadInputTokens: 15,
+        cacheCreationInputTokens: 8,
+        costUSD: 0.006,
+      },
+      "claude-haiku-3-5": {
+        inputTokens: 20,
+        outputTokens: 10,
+        cacheReadInputTokens: 5,
+        cacheCreationInputTokens: 2,
+        costUSD: 0.0008,
+      },
+    };
+    await reporter.recordSession(USAGE, undefined, modelUsage);
+
+    const body = state.captured[0].body as Record<string, unknown>;
+    expect(Array.isArray(body.modelBreakdown)).toBe(true);
+    const breakdown = body.modelBreakdown as Array<Record<string, unknown>>;
+    expect(breakdown.length).toBe(2);
+    const models = breakdown.map((b) => b.model).sort();
+    expect(models).toEqual(["claude-haiku-3-5", "claude-sonnet-4-5"]);
+    const byModel = Object.fromEntries(breakdown.map((b) => [b.model, b]));
+    // costUsd is passed through directly from the CLI's costUSD per model
+    expect(byModel["claude-sonnet-4-5"].costUsd).toBe(0.006);
+    expect(byModel["claude-haiku-3-5"].costUsd).toBe(0.0008);
+    expect(byModel["claude-sonnet-4-5"].inputTokens).toBe(80);
+    expect(byModel["claude-sonnet-4-5"].outputTokens).toBe(40);
+    expect(byModel["claude-sonnet-4-5"].cacheReadTokens).toBe(15);
+    expect(byModel["claude-sonnet-4-5"].cacheCreationTokens).toBe(8);
+  });
+
+  test("recordSession uses live model as fallback when modelUsage is not provided", async () => {
+    const reporter = makeReporter();
+    await reporter.recordSession(USAGE);
+
+    const body = state.captured[0].body as Record<string, unknown>;
+    // When no modelUsage provided, modelBreakdown has a single entry using liveClaudeConfig.model
+    const breakdown = body.modelBreakdown as Array<Record<string, unknown>>;
+    expect(Array.isArray(breakdown)).toBe(true);
+    expect(breakdown.length).toBe(1);
+    // model field is set (to liveClaudeConfig.model)
+    expect(typeof breakdown[0].model).toBe("string");
+    expect((breakdown[0].model as string).length).toBeGreaterThan(0);
+  });
+
+  test("recordSession sends costUsd in modelBreakdown from totalCostUsd when provided", async () => {
+    const reporter = makeReporter();
+    await reporter.recordSession(USAGE, 0.0099);
+
+    const body = state.captured[0].body as Record<string, unknown>;
+    const breakdown = body.modelBreakdown as Array<Record<string, unknown>>;
+    expect(breakdown[0].costUsd).toBe(0.0099);
+  });
+
+  test("recordSession falls back to calculateCost in modelBreakdown when totalCostUsd not provided", async () => {
+    const reporter = makeReporter();
+    await reporter.recordSession(USAGE);
+
+    const body = state.captured[0].body as Record<string, unknown>;
+    const breakdown = body.modelBreakdown as Array<Record<string, unknown>>;
+    // Falls back to calculateCost(usage, liveClaudeConfig.model) — non-zero computed cost
+    expect(typeof breakdown[0].costUsd).toBe("number");
+    expect(breakdown[0].costUsd as number).toBeGreaterThan(0);
+  });
+
+  test("recordSession sends Authorization: Bearer header", async () => {
+    const reporter = makeReporter();
+    await reporter.recordSession(USAGE);
+
+    expect(state.captured[0].headers.authorization).toBe(`Bearer ${API_KEY}`);
+  });
+
+  test("recordSession(undefined) makes NO request (no-op)", async () => {
+    const reporter = makeReporter();
+    await reporter.recordSession(undefined);
+
+    expect(state.captured).toHaveLength(0);
+  });
+
+  test("recordSession swallows network errors (does not throw)", async () => {
+    const reporter = new HttpChatTokenReporter({
+      apiUrl: "http://localhost:19999", // nothing listening
+      agentId: AGENT_ID,
+      apiKey: API_KEY,
+      clock: CLOCK,
+      timeZone: "UTC",
+    });
+
+    await expect(reporter.recordSession(USAGE)).resolves.toBeUndefined();
+  });
+
+  test("recordSession swallows HTTP error responses (does not throw)", async () => {
+    state.statusToReturn = 500;
+    const reporter = makeReporter();
+
+    await expect(reporter.recordSession(USAGE)).resolves.toBeUndefined();
+  });
+
+  test("recordSession swallows HTTP 4xx responses (does not throw)", async () => {
+    state.statusToReturn = 400;
+    const reporter = makeReporter();
+
+    await expect(reporter.recordSession(USAGE)).resolves.toBeUndefined();
+  });
+});
+
+// ─── NoopChatTokenReporter ────────────────────────────────────────────────────
+
+describe("NoopChatTokenReporter", () => {
+  test("recordSession resolves immediately and does not throw", async () => {
+    const reporter = new NoopChatTokenReporter();
+    await expect(reporter.recordSession(USAGE)).resolves.toBeUndefined();
+  });
+
+  test("recordSession(undefined) resolves and does not throw", async () => {
+    const reporter = new NoopChatTokenReporter();
+    await expect(reporter.recordSession(undefined)).resolves.toBeUndefined();
+  });
+});

package/chat-token-reporter.ts

@@ -0,0 +1,136 @@
+/**
+ * ChatTokenReporter — reports per-session Slack chat token usage to the admin
+ * daily-upsert endpoint: POST /agents/:agentId/chat-tokens/daily.
+ *
+ * Each completed Slack session (DM, mention, or reaction) POSTs its accumulated
+ * token counts broken down by model; the admin endpoint accumulates rows
+ * atomically per (agent, date, model).
+ *
+ * HttpChatTokenReporter: production implementation, fire-and-forget (never throws).
+ * NoopChatTokenReporter: testing / default when the admin API is not configured.
+ */
+
+import type { ModelUsage, TokenUsage } from "./claude.ts";
+import { liveClaudeConfig } from "./claude.ts";
+import { type Clock, SystemClock } from "./clock.ts";
+import { calculateCost } from "./pricing.ts";
+
+/**
+ * Format a Date as YYYY-MM-DD in an IANA timezone.
+ *
+ * Uses the `en-CA` locale, which renders dates as YYYY-MM-DD. When `timeZone`
+ * is undefined, the process-local zone (the "agent timezone") is used.
+ */
+export function formatDailyDate(date: Date, timeZone?: string): string {
+  return new Intl.DateTimeFormat("en-CA", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).format(date);
+}
+
+export interface ChatTokenReporter {
+  /** Called at Slack session completion. No-op when usage is undefined. */
+  recordSession(
+    usage: TokenUsage | undefined,
+    totalCostUsd?: number,
+    modelUsage?: ModelUsage,
+  ): Promise<void>;
+}
+
+interface HttpChatTokenReporterOptions {
+  apiUrl: string;
+  agentId: string;
+  apiKey: string;
+  clock?: Clock;
+  timeZone?: string;
+}
+
+export class HttpChatTokenReporter implements ChatTokenReporter {
+  private readonly clock: Clock;
+  private readonly timeZone?: string;
+
+  constructor(private opts: HttpChatTokenReporterOptions) {
+    this.clock = opts.clock ?? SystemClock();
+    this.timeZone = opts.timeZone;
+  }
+
+  async recordSession(
+    usage: TokenUsage | undefined,
+    totalCostUsd?: number,
+    modelUsage?: ModelUsage,
+  ): Promise<void> {
+    if (usage === undefined) return;
+
+    const { apiUrl, agentId, apiKey } = this.opts;
+    const url = `${apiUrl}/agents/${agentId}/chat-tokens/daily`;
+
+    const date = formatDailyDate(this.clock.now(), this.timeZone);
+
+    // Build modelBreakdown from modelUsage when provided.
+    // When modelUsage is absent, fall back to a single entry using the live model.
+    let modelBreakdown: Array<{
+      model: string;
+      inputTokens: number;
+      outputTokens: number;
+      cacheReadTokens: number;
+      cacheCreationTokens: number;
+      costUsd: number;
+    }>;
+
+    if (modelUsage && Object.keys(modelUsage).length > 0) {
+      modelBreakdown = Object.entries(modelUsage).map(([model, mu]) => ({
+        model,
+        inputTokens: mu.inputTokens,
+        outputTokens: mu.outputTokens,
+        cacheReadTokens: mu.cacheReadInputTokens,
+        cacheCreationTokens: mu.cacheCreationInputTokens,
+        costUsd: mu.costUSD,
+      }));
+    } else {
+      modelBreakdown = [
+        {
+          model: liveClaudeConfig.model,
+          inputTokens: usage.input_tokens,
+          outputTokens: usage.output_tokens,
+          cacheReadTokens: usage.cache_read_input_tokens,
+          cacheCreationTokens: usage.cache_creation_input_tokens,
+          costUsd: totalCostUsd ?? calculateCost(usage, liveClaudeConfig.model),
+        },
+      ];
+    }
+
+    const body = { date, modelBreakdown };
+
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify(body),
+      });
+      if (!res.ok) {
+        console.warn(
+          `[chat-token-reporter] POST ${url} returned ${res.status} — swallowing`,
+        );
+      }
+    } catch (err) {
+      console.warn(
+        `[chat-token-reporter] POST ${url} failed: ${String(err)} — swallowing`,
+      );
+    }
+  }
+}
+
+export class NoopChatTokenReporter implements ChatTokenReporter {
+  async recordSession(
+    _usage: TokenUsage | undefined,
+    _totalCostUsd?: number,
+    _modelUsage?: ModelUsage,
+  ): Promise<void> {
+    // intentional no-op
+  }
+}

package/claude-version.ts

@@ -0,0 +1,55 @@
+/**
+ * Detects the installed Claude Code CLI version once at agent startup so it can
+ * be logged and surfaced in /health. Fail-soft: any exec failure, non-semver
+ * output, or timeout resolves to "unknown" — never throws, never blocks startup
+ * beyond the bounded timeout.
+ *
+ * The exec is injected (no mock.module in tests); `bunExec` is the real one.
+ */
+
+export const UNKNOWN_CLAUDE_CODE_VERSION = "unknown";
+
+/** Upper bound on how long `claude --version` may delay startup. */
+const CLAUDE_VERSION_TIMEOUT_MS = 5_000;
+
+/** Runs a command and resolves to its stdout; rejects on non-zero exit. */
+type VersionExec = (cmd: string[]) => Promise<string>;
+
+const SEMVER_RE = /\b(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)\b/;
+
+/** Extracts the first semver from `claude --version` output (e.g. "2.1.236 (Claude Code)"). */
+export function parseClaudeVersion(output: string): string | null {
+  return SEMVER_RE.exec(output)?.[1] ?? null;
+}
+
+export async function detectClaudeCodeVersion(
+  exec: VersionExec,
+  timeoutMs: number = CLAUDE_VERSION_TIMEOUT_MS,
+): Promise<string> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<null>((resolve) => {
+    timer = setTimeout(() => resolve(null), timeoutMs);
+  });
+  try {
+    const output = await Promise.race([
+      exec(["claude", "--version"]).catch(() => null),
+      timeout,
+    ]);
+    if (output === null) return UNKNOWN_CLAUDE_CODE_VERSION;
+    return parseClaudeVersion(output) ?? UNKNOWN_CLAUDE_CODE_VERSION;
+  } catch {
+    return UNKNOWN_CLAUDE_CODE_VERSION;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export const bunExec: VersionExec = async (cmd) => {
+  const proc = Bun.spawn(cmd, { stdout: "pipe", stderr: "ignore" });
+  const [out, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    proc.exited,
+  ]);
+  if (code !== 0) throw new Error(`${cmd[0]} exited with code ${code}`);
+  return out;
+};

package/claude-version.unit.test.ts

@@ -0,0 +1,73 @@
+/**
+ * Unit tests for agent/src/runtime/claude-version.ts — injected exec, no module mocks.
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+  detectClaudeCodeVersion,
+  parseClaudeVersion,
+  UNKNOWN_CLAUDE_CODE_VERSION,
+} from "./claude-version.ts";
+
+describe("parseClaudeVersion", () => {
+  it("parses the CLI's '<semver> (Claude Code)' output", () => {
+    expect(parseClaudeVersion("2.1.236 (Claude Code)\n")).toBe("2.1.236");
+  });
+
+  it("parses a bare semver", () => {
+    expect(parseClaudeVersion("2.1.236")).toBe("2.1.236");
+  });
+
+  it("keeps a prerelease suffix", () => {
+    expect(parseClaudeVersion("2.2.0-beta.1 (Claude Code)")).toBe(
+      "2.2.0-beta.1",
+    );
+  });
+
+  it("returns null when no semver is present", () => {
+    expect(parseClaudeVersion("")).toBeNull();
+    expect(parseClaudeVersion("command not found")).toBeNull();
+    expect(parseClaudeVersion("v2.1")).toBeNull();
+  });
+});
+
+describe("detectClaudeCodeVersion", () => {
+  it("runs `claude --version` and returns the parsed version", async () => {
+    const calls: string[][] = [];
+    const version = await detectClaudeCodeVersion(async (cmd) => {
+      calls.push(cmd);
+      return "2.1.236 (Claude Code)\n";
+    });
+    expect(version).toBe("2.1.236");
+    expect(calls).toEqual([["claude", "--version"]]);
+  });
+
+  it("returns 'unknown' when exec rejects", async () => {
+    const version = await detectClaudeCodeVersion(async () => {
+      throw new Error("ENOENT");
+    });
+    expect(version).toBe(UNKNOWN_CLAUDE_CODE_VERSION);
+  });
+
+  it("returns 'unknown' when exec throws synchronously", async () => {
+    const version = await detectClaudeCodeVersion(() => {
+      throw new Error("spawn failed");
+    });
+    expect(version).toBe(UNKNOWN_CLAUDE_CODE_VERSION);
+  });
+
+  it("returns 'unknown' when output has no semver", async () => {
+    const version = await detectClaudeCodeVersion(async () => "garbage");
+    expect(version).toBe(UNKNOWN_CLAUDE_CODE_VERSION);
+  });
+
+  it("returns 'unknown' within the timeout when exec hangs", async () => {
+    const start = Date.now();
+    const version = await detectClaudeCodeVersion(
+      () => new Promise<string>(() => {}),
+      50,
+    );
+    expect(version).toBe(UNKNOWN_CLAUDE_CODE_VERSION);
+    expect(Date.now() - start).toBeLessThan(1_000);
+  });
+});