@app-vitals/agent-runtime 0.0.0-stage → 0.1.0

package/piper-voice.ts

@@ -0,0 +1,116 @@
+/**
+ * agent/src/runtime/piper-voice.ts
+ *
+ * Discovery-based validation for the PIPER_VOICE config value, plus a
+ * resolver that turns a validated voice name into the baked `.onnx` /
+ * `.onnx.json` pair path.
+ *
+ * Piper voices are baked into the image at VOICES_DIR — a hardcoded
+ * constant, not env-configurable. Voice selection must fail loudly at
+ * startup (log the requested value and everything actually discovered)
+ * rather than silently at speak time, so this module owns that check.
+ * Actual Piper synthesis is a future task (PPR-1.2); this module only
+ * validates + resolves paths.
+ *
+ * The directory scan mirrors the non-throwing, injectable-readdir pattern
+ * used by discoverBakedMarketplaces (agent/src/runtime/setup.ts) and scanReposDir
+ * (agent/src/coding/check-helpers.ts): readdirSync wrapped in try/catch, empty
+ * array on failure, and the readdir function itself is swappable so unit
+ * tests never touch the real filesystem.
+ */
+
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+
+/** Default voice used when PIPER_VOICE is unset. Must be present in every baked image. */
+export const DEFAULT_PIPER_VOICE = "en_US-hfc_female-medium";
+
+/**
+ * Baked voices directory. Hardcoded, not env-configurable — voice
+ * availability is an IMAGE property (mirrors BAKED_MARKETPLACES_ROOT in
+ * setup.ts).
+ */
+export const VOICES_DIR = "/app/agent/voices/";
+
+type ReaddirFn = (dir: string) => string[];
+
+const defaultReaddirFn: ReaddirFn = (dir: string): string[] => {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+};
+
+/**
+ * Scans `dir` for Piper voice files and returns the distinct base voice
+ * names found (each voice ships as a `<name>.onnx` + `<name>.onnx.json`
+ * pair — this collapses both into one name). Non-throwing.
+ */
+function discoverVoices(dir: string, readdirFn: ReaddirFn): string[] {
+  let entries: string[];
+  try {
+    entries = readdirFn(dir);
+  } catch {
+    return [];
+  }
+
+  const names = new Set<string>();
+  for (const entry of entries) {
+    if (entry.endsWith(".onnx.json")) {
+      names.add(entry.slice(0, -".onnx.json".length));
+    } else if (entry.endsWith(".onnx")) {
+      names.add(entry.slice(0, -".onnx".length));
+    }
+  }
+  return [...names];
+}
+
+/**
+ * Validates the requested PIPER_VOICE against the discovered baked voices
+ * directory and returns the voice name to use.
+ *
+ * - PIPER_VOICE unset -> returns DEFAULT_PIPER_VOICE.
+ * - PIPER_VOICE set and found in the directory listing -> returns it as-is.
+ * - PIPER_VOICE set but NOT found -> logs loudly (naming both the requested
+ *   voice and every voice actually discovered) and falls back to
+ *   DEFAULT_PIPER_VOICE. Never throws — a startup misconfiguration here
+ *   must not crash the agent.
+ */
+export function validatePiperVoice(
+  requestedVoice: string | undefined,
+  readdirFn: ReaddirFn = defaultReaddirFn,
+): string {
+  const discovered = discoverVoices(VOICES_DIR, readdirFn);
+
+  if (requestedVoice === undefined) {
+    return DEFAULT_PIPER_VOICE;
+  }
+
+  if (discovered.includes(requestedVoice)) {
+    return requestedVoice;
+  }
+
+  console.warn(
+    `[piper-voice] PIPER_VOICE "${requestedVoice}" was not found in ${VOICES_DIR}. ` +
+      `Discovered voices: ${discovered.length > 0 ? discovered.join(", ") : "(none)"}. ` +
+      `Falling back to default voice "${DEFAULT_PIPER_VOICE}".`,
+  );
+
+  return DEFAULT_PIPER_VOICE;
+}
+
+/**
+ * Resolves a validated voice name into its baked `.onnx` / `.onnx.json`
+ * pair path. Centralizes directory logic so a future synthesizePiper
+ * (PPR-1.2) doesn't duplicate it.
+ */
+export function resolvePiperVoicePaths(voiceName: string): {
+  onnxPath: string;
+  onnxJsonPath: string;
+} {
+  return {
+    onnxPath: join(VOICES_DIR, `${voiceName}.onnx`),
+    onnxJsonPath: join(VOICES_DIR, `${voiceName}.onnx.json`),
+  };
+}

package/piper-voice.unit.test.ts

@@ -0,0 +1,124 @@
+/**
+ * Tests for agent/src/runtime/piper-voice.ts
+ *
+ * Strategy: inject a fake readdirFn — no real filesystem I/O (agent/src test
+ * isolation rule). Spy on console.warn/console.error by swapping the bound
+ * method on the console object itself (not a global override) and restoring
+ * it after each assertion.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import {
+  DEFAULT_PIPER_VOICE,
+  resolvePiperVoicePaths,
+  VOICES_DIR,
+  validatePiperVoice,
+} from "./piper-voice.ts";
+
+let warnCalls: unknown[][] = [];
+let errorCalls: unknown[][] = [];
+let originalWarn: typeof console.warn;
+let originalError: typeof console.error;
+
+beforeEach(() => {
+  warnCalls = [];
+  errorCalls = [];
+  originalWarn = console.warn;
+  originalError = console.error;
+  console.warn = (...args: unknown[]) => {
+    warnCalls.push(args);
+  };
+  console.error = (...args: unknown[]) => {
+    errorCalls.push(args);
+  };
+});
+
+afterEach(() => {
+  console.warn = originalWarn;
+  console.error = originalError;
+});
+
+const makeReaddirFn = (files: string[]) => (_dir: string) => files;
+
+describe("validatePiperVoice", () => {
+  test("defaults to en_US-hfc_female-medium when PIPER_VOICE is unset", () => {
+    const readdirFn = makeReaddirFn([
+      "en_US-hfc_female-medium.onnx",
+      "en_US-hfc_female-medium.onnx.json",
+    ]);
+    const result = validatePiperVoice(undefined, readdirFn);
+    expect(result).toBe(DEFAULT_PIPER_VOICE);
+    expect(result).toBe("en_US-hfc_female-medium");
+  });
+
+  test("returns the requested voice when present in the discovered directory listing", () => {
+    const readdirFn = makeReaddirFn([
+      "en_US-hfc_female-medium.onnx",
+      "en_US-hfc_female-medium.onnx.json",
+      "en_GB-alan-medium.onnx",
+      "en_GB-alan-medium.onnx.json",
+    ]);
+    const result = validatePiperVoice("en_GB-alan-medium", readdirFn);
+    expect(result).toBe("en_GB-alan-medium");
+    // No warnings/errors on a hit.
+    expect(warnCalls.length).toBe(0);
+    expect(errorCalls.length).toBe(0);
+  });
+
+  test("falls back and logs loudly when the requested voice is not discovered", () => {
+    const readdirFn = makeReaddirFn([
+      "en_US-hfc_female-medium.onnx",
+      "en_US-hfc_female-medium.onnx.json",
+      "en_GB-alan-medium.onnx",
+      "en_GB-alan-medium.onnx.json",
+    ]);
+    const result = validatePiperVoice("nonexistent-voice", readdirFn);
+
+    // Process must not crash — a usable voice name is returned.
+    expect(typeof result).toBe("string");
+
+    const logged = [...warnCalls, ...errorCalls];
+    expect(logged.length).toBeGreaterThan(0);
+    const allLoggedText = logged.map((call) => call.join(" ")).join("\n");
+    expect(allLoggedText).toContain("nonexistent-voice");
+    expect(allLoggedText).toContain("en_US-hfc_female-medium");
+    expect(allLoggedText).toContain("en_GB-alan-medium");
+  });
+
+  test("does not throw when the directory scan fails (readdirFn throws)", () => {
+    const throwingReaddirFn = (_dir: string): string[] => {
+      throw new Error("ENOENT: no such directory");
+    };
+    expect(() =>
+      validatePiperVoice("en_US-hfc_female-medium", throwingReaddirFn),
+    ).not.toThrow();
+  });
+
+  test("uses the hardcoded VOICES_DIR constant, not an env-configurable path", () => {
+    let receivedDir: string | undefined;
+    const readdirFn = (dir: string) => {
+      receivedDir = dir;
+      return ["en_US-hfc_female-medium.onnx"];
+    };
+    validatePiperVoice(undefined, readdirFn);
+    expect(receivedDir).toBe(VOICES_DIR);
+    expect(VOICES_DIR).toBe("/app/agent/voices/");
+  });
+});
+
+describe("resolvePiperVoicePaths", () => {
+  test("returns the .onnx/.onnx.json pair path for a voice name", () => {
+    const { onnxPath, onnxJsonPath } = resolvePiperVoicePaths(
+      "en_US-hfc_female-medium",
+    );
+    expect(onnxPath).toBe(`${VOICES_DIR}en_US-hfc_female-medium.onnx`);
+    expect(onnxJsonPath).toBe(`${VOICES_DIR}en_US-hfc_female-medium.onnx.json`);
+  });
+
+  test("resolves paths for a different voice name", () => {
+    const { onnxPath, onnxJsonPath } =
+      resolvePiperVoicePaths("en_GB-alan-medium");
+    expect(onnxPath).toBe(`${VOICES_DIR}en_GB-alan-medium.onnx`);
+    expect(onnxJsonPath).toBe(`${VOICES_DIR}en_GB-alan-medium.onnx.json`);
+  });
+});

package/pricing.ts

@@ -0,0 +1,7 @@
+export type { TokenUsage } from "@app-vitals/agent-lib/pricing";
+export {
+  calculateCost,
+  normalizeModelToRateKey,
+  OPUS_MODEL,
+  RATES,
+} from "@app-vitals/agent-lib/pricing";

package/pricing.unit.test.ts

@@ -0,0 +1,149 @@
+/**
+ * Unit tests for agent/src/runtime/pricing.ts — calculateCost()
+ *
+ * Pure function — no side effects, no mocks needed.
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { TokenUsage } from "./claude.ts";
+import { calculateCost } from "./pricing.ts";
+
+const SAMPLE_USAGE: TokenUsage = {
+  input_tokens: 100,
+  output_tokens: 200,
+  cache_read_input_tokens: 50,
+  cache_creation_input_tokens: 10,
+};
+
+const ZERO_USAGE: TokenUsage = {
+  input_tokens: 0,
+  output_tokens: 0,
+  cache_read_input_tokens: 0,
+  cache_creation_input_tokens: 0,
+};
+
+// ─── unknown model ─────────────────────────────────────────────────────────────
+
+describe("unknown model", () => {
+  test("returns 0 for an unrecognised model ID", () => {
+    expect(calculateCost(SAMPLE_USAGE, "claude-sonnet-4-5")).toBe(0);
+  });
+
+  test("returns 0 for empty string model ID", () => {
+    expect(calculateCost(SAMPLE_USAGE, "")).toBe(0);
+  });
+
+  test("returns 0 for zero usage with unknown model", () => {
+    expect(calculateCost(ZERO_USAGE, "gpt-4")).toBe(0);
+  });
+});
+
+// ─── claude-sonnet-4-6 ($3.00 input, $15.00 output) ──────────────────────────
+
+describe("claude-sonnet-4-6", () => {
+  test("returns correct USD for SAMPLE_USAGE", () => {
+    // (100 * 3.00 + 200 * 15.00 + 10 * 3.00 * 1.25 + 50 * 3.00 * 0.1) / 1_000_000
+    // = (300 + 3000 + 37.5 + 15) / 1_000_000 = 0.0033525
+    expect(calculateCost(SAMPLE_USAGE, "claude-sonnet-4-6")).toBe(0.0033525);
+  });
+
+  test("returns 0 for zero usage", () => {
+    expect(calculateCost(ZERO_USAGE, "claude-sonnet-4-6")).toBe(0);
+  });
+});
+
+// ─── claude-haiku-4-5 ($1.00 input, $5.00 output) ────────────────────────────
+
+describe("claude-haiku-4-5", () => {
+  test("returns correct USD for SAMPLE_USAGE", () => {
+    // (100 * 1.00 + 200 * 5.00 + 10 * 1.00 * 1.25 + 50 * 1.00 * 0.1) / 1_000_000
+    // = (100 + 1000 + 12.5 + 5) / 1_000_000 = 0.0011175
+    expect(calculateCost(SAMPLE_USAGE, "claude-haiku-4-5")).toBe(0.0011175);
+  });
+});
+
+// ─── claude-opus-4-8 ($5.00 input, $25.00 output) ────────────────────────────
+
+describe("claude-opus-4-8", () => {
+  test("returns correct USD for SAMPLE_USAGE", () => {
+    // (100 * 5.00 + 200 * 25.00 + 10 * 5.00 * 1.25 + 50 * 5.00 * 0.1) / 1_000_000
+    // = (500 + 5000 + 62.5 + 25) / 1_000_000 = 0.0055875
+    expect(calculateCost(SAMPLE_USAGE, "claude-opus-4-8")).toBe(0.0055875);
+  });
+});
+
+// ─── claude-opus-4-7 ($5.00 input, $25.00 output) ────────────────────────────
+
+describe("claude-opus-4-7", () => {
+  test("returns correct USD for SAMPLE_USAGE (same rates as opus-4-8)", () => {
+    expect(calculateCost(SAMPLE_USAGE, "claude-opus-4-7")).toBe(0.0055875);
+  });
+});
+
+// ─── claude-opus-4-6 ($5.00 input, $25.00 output) ────────────────────────────
+
+describe("claude-opus-4-6", () => {
+  test("returns correct USD for SAMPLE_USAGE (same rates as opus-4-8)", () => {
+    expect(calculateCost(SAMPLE_USAGE, "claude-opus-4-6")).toBe(0.0055875);
+  });
+});
+
+// ─── claude-fable-5 ($10.00 input, $50.00 output) ────────────────────────────
+
+describe("claude-fable-5", () => {
+  test("returns correct USD for SAMPLE_USAGE", () => {
+    // (100 * 10.00 + 200 * 50.00 + 10 * 10.00 * 1.25 + 50 * 10.00 * 0.1) / 1_000_000
+    // = (1000 + 10000 + 125 + 50) / 1_000_000 = 0.011175
+    expect(calculateCost(SAMPLE_USAGE, "claude-fable-5")).toBe(0.011175);
+  });
+});
+
+// ─── cache multipliers ────────────────────────────────────────────────────────
+
+describe("cache multipliers", () => {
+  test("cache_creation_input_tokens uses 1.25x input rate", () => {
+    const usage: TokenUsage = {
+      input_tokens: 0,
+      output_tokens: 0,
+      cache_read_input_tokens: 0,
+      cache_creation_input_tokens: 1_000_000,
+    };
+    // claude-sonnet-4-6 input = $3.00/M, cache write = 3.00 * 1.25 = $3.75/M
+    // 1_000_000 * 3.75 / 1_000_000 = 3.75
+    expect(calculateCost(usage, "claude-sonnet-4-6")).toBe(3.75);
+  });
+
+  test("cache_read_input_tokens uses 0.1x input rate", () => {
+    const usage: TokenUsage = {
+      input_tokens: 0,
+      output_tokens: 0,
+      cache_read_input_tokens: 1_000_000,
+      cache_creation_input_tokens: 0,
+    };
+    // claude-sonnet-4-6 input = $3.00/M, cache read = 3.00 * 0.1 = $0.30/M
+    // 1_000_000 * 0.30 / 1_000_000 = 0.30
+    expect(calculateCost(usage, "claude-sonnet-4-6")).toBe(0.3);
+  });
+
+  test("input_tokens only (no cache) charges at base input rate", () => {
+    const usage: TokenUsage = {
+      input_tokens: 1_000_000,
+      output_tokens: 0,
+      cache_read_input_tokens: 0,
+      cache_creation_input_tokens: 0,
+    };
+    // claude-haiku-4-5: $1.00/M input
+    expect(calculateCost(usage, "claude-haiku-4-5")).toBe(1.0);
+  });
+
+  test("output_tokens only charges at output rate", () => {
+    const usage: TokenUsage = {
+      input_tokens: 0,
+      output_tokens: 1_000_000,
+      cache_read_input_tokens: 0,
+      cache_creation_input_tokens: 0,
+    };
+    // claude-haiku-4-5: $5.00/M output
+    expect(calculateCost(usage, "claude-haiku-4-5")).toBe(5.0);
+  });
+});

package/process-tree-kill.integration.test.ts

@@ -0,0 +1,133 @@
+/**
+ * Integration tests for agent/src/runtime/process-tree-kill.ts
+ *
+ * Real dependency under test: the Linux kernel's procfs
+ * (/proc/<pid>/task/<tid>/children) and real signal delivery. These spawn
+ * genuine short-lived subprocesses that fork their own children — the exact
+ * shape the timeout path has to clean up (a `claude` CLI that spawned an
+ * install/build). No DB, no network, no mock.module().
+ *
+ * Linux-only: procfs's `children` file has no portable equivalent, and the
+ * agent only ever runs on Linux (agent/Dockerfile). The suite self-skips
+ * elsewhere rather than failing.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { existsSync, readFileSync } from "node:fs";
+
+const { collectDescendantPids, killTree } = await import(
+  "./process-tree-kill.ts"
+);
+
+const onLinux = process.platform === "linux" && existsSync("/proc/self/task");
+
+/**
+ * True unless the pid is gone OR is an unreaped zombie. A SIGKILLed process
+ * whose parent died too lingers as a zombie until init reaps it — `kill(pid,
+ * 0)` still succeeds for a zombie, so it alone would be a false "alive".
+ */
+function isAlive(pid: number): boolean {
+  let stat: string;
+  try {
+    stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+  } catch {
+    return false;
+  }
+  // "<pid> (comm) <state> ..." — comm can contain spaces/parens, so slice
+  // from the LAST ')' to find the state field.
+  const state = stat.slice(
+    stat.lastIndexOf(")") + 2,
+    stat.lastIndexOf(")") + 3,
+  );
+  return state !== "Z";
+}
+
+async function waitUntilDead(pid: number, timeoutMs = 2000): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!isAlive(pid)) return true;
+    await Bun.sleep(10);
+  }
+  return !isAlive(pid);
+}
+
+/**
+ * Spawns `sh` which forks a long-lived grandchild and prints its pid, then
+ * waits. Returns the direct child proc plus the grandchild's pid.
+ */
+async function spawnWithGrandchild(): Promise<{
+  proc: Bun.Subprocess;
+  grandchildPid: number;
+}> {
+  const proc = Bun.spawn(["sh", "-c", 'sleep 300 & echo "$!"; wait'], {
+    stdout: "pipe",
+    stderr: "ignore",
+  });
+  const deadline = Date.now() + 5000;
+  let buffered = "";
+  const reader = (proc.stdout as ReadableStream<Uint8Array>).getReader();
+  const decoder = new TextDecoder();
+  try {
+    while (!buffered.includes("\n") && Date.now() < deadline) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      if (value) buffered += decoder.decode(value, { stream: true });
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const grandchildPid = Number.parseInt(buffered.trim(), 10);
+  return { proc, grandchildPid };
+}
+
+describe.if(onLinux)("collectDescendantPids (real processes)", () => {
+  test("finds a grandchild the direct child forked", async () => {
+    const { proc, grandchildPid } = await spawnWithGrandchild();
+    try {
+      expect(Number.isInteger(grandchildPid)).toBe(true);
+      const descendants = collectDescendantPids(proc.pid);
+      expect(descendants).toContain(grandchildPid);
+    } finally {
+      killTree(proc);
+      await waitUntilDead(grandchildPid);
+    }
+  });
+});
+
+describe.if(onLinux)("killTree (real processes, procfs fallback)", () => {
+  test("terminates the direct child AND its forked descendant", async () => {
+    const { proc, grandchildPid } = await spawnWithGrandchild();
+    expect(isAlive(grandchildPid)).toBe(true);
+
+    killTree(proc);
+
+    await proc.exited;
+    expect(await waitUntilDead(proc.pid)).toBe(true);
+    expect(await waitUntilDead(grandchildPid)).toBe(true);
+  });
+
+  test("a plain proc.kill() leaves the descendant alive — the regression this guards", async () => {
+    // Pins the *reason* killTree exists: signalling only the direct child is
+    // demonstrably insufficient. If this ever starts failing, the kernel/shell
+    // stopped reparenting orphans and killTree's whole premise changed.
+    const { proc, grandchildPid } = await spawnWithGrandchild();
+    try {
+      proc.kill();
+      await proc.exited;
+      await Bun.sleep(50);
+      expect(isAlive(grandchildPid)).toBe(true);
+    } finally {
+      try {
+        process.kill(grandchildPid, "SIGKILL");
+      } catch {
+        // already gone
+      }
+    }
+  });
+
+  test("is a no-op that does not throw when the process already exited", async () => {
+    const proc = Bun.spawn(["true"], { stdout: "ignore", stderr: "ignore" });
+    await proc.exited;
+    expect(() => killTree(proc)).not.toThrow();
+  });
+});