aigetwey 1.0.1

package/src/headroom/compress.ts

@@ -0,0 +1,78 @@
+/**
+ * Request-time context compression via the external Headroom proxy.
+ *
+ * aigetwey's canonical request is OpenAI-shaped, and Headroom's /v1/compress only
+ * understands OpenAI shape — so we compress canonical.messages directly, no
+ * per-format translation dance (aigetwey has to translate Claude bodies first).
+ * Fail-open: any error returns null and the request proceeds uncompressed.
+ *
+ * aigetwey's own implementation.
+ */
+import type { CanonicalMessage } from "../core/canonical.js";
+
+const DEFAULT_TIMEOUT_MS = 3000;
+
+export interface HeadroomStats {
+  tokens_before?: number;
+  tokens_after?: number;
+  tokens_saved?: number;
+}
+
+export interface HeadroomCompressOpts {
+  url: string;
+  model: string;
+  compressUserMessages?: boolean;
+  timeoutMs?: number;
+}
+
+interface CompressReply extends HeadroomStats {
+  messages: CanonicalMessage[];
+}
+
+// POST messages to Headroom /v1/compress; returns compressed messages + stats or null.
+async function callCompress(
+  url: string,
+  messages: CanonicalMessage[],
+  model: string,
+  timeoutMs: number,
+  compressUserMessages?: boolean,
+): Promise<CompressReply | null> {
+  const endpoint = `${String(url).replace(/\/$/, "")}/v1/compress`;
+  const payload: Record<string, unknown> = { messages, model };
+  if (compressUserMessages) payload.config = { compress_user_messages: true };
+  const res = await fetch(endpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (!res.ok) return null;
+  const data = (await res.json()) as CompressReply;
+  if (!Array.isArray(data?.messages)) return null;
+  return data;
+}
+
+/**
+ * Compress messages via the Headroom proxy. Returns the compressed messages +
+ * stats, or null on any failure (caller keeps the original messages).
+ */
+export async function compressWithHeadroom(
+  messages: CanonicalMessage[],
+  { url, model, compressUserMessages, timeoutMs = DEFAULT_TIMEOUT_MS }: HeadroomCompressOpts,
+): Promise<CompressReply | null> {
+  if (!url || !Array.isArray(messages) || messages.length === 0) return null;
+  try {
+    return await callCompress(url, messages, model, timeoutMs, compressUserMessages);
+  } catch {
+    return null;
+  }
+}
+
+export function formatHeadroomLog(stats: HeadroomStats | null): string | null {
+  if (!stats) return null;
+  const before = stats.tokens_before || 0;
+  const after = stats.tokens_after || 0;
+  const saved = stats.tokens_saved || 0;
+  const pct = before > 0 ? ((saved / before) * 100).toFixed(1) : "0";
+  return `saved ${saved} tokens / ${before} (${pct}%) ${after ? `after=${after}` : ""}`.trim();
+}

package/src/headroom/detect.ts

@@ -0,0 +1,119 @@
+/**
+ * Headroom CLI detection. "Headroom" is an external context-compression proxy
+ * (a Python tool, `headroom proxy`, default http://localhost:8787) that aigetwey
+ * pipes request messages through. This module only DETECTS it — install, python
+ * interpreter, and whether a proxy is already reachable.
+ *
+ * aigetwey's own implementation.
+ */
+import { execSync } from "node:child_process";
+import { delimiter } from "node:path";
+
+const IS_WIN = process.platform === "win32";
+const WHICH_CMD = IS_WIN ? "where" : "which";
+
+// Extra bin dirs often missing from a packaged PATH (Python installs headroom here).
+const EXTRA_BINS = IS_WIN
+  ? [
+      `${process.env.LOCALAPPDATA || ""}\\Programs\\Python\\Python313\\Scripts`,
+      `${process.env.LOCALAPPDATA || ""}\\Programs\\Python\\Python312\\Scripts`,
+      `${process.env.LOCALAPPDATA || ""}\\Programs\\Python\\Python311\\Scripts`,
+      `${process.env.APPDATA || ""}\\Python\\Python313\\Scripts`,
+    ]
+  : [
+      "/usr/local/bin",
+      "/opt/homebrew/bin",
+      `${process.env.HOME || ""}/.local/bin`,
+      "/usr/bin",
+      "/bin",
+    ];
+
+const EXTENDED_PATH = [...EXTRA_BINS, process.env.PATH || ""].filter(Boolean).join(delimiter);
+const PYTHON_CANDIDATES = ["python3.13", "python3.12", "python3.11", "python3.10", "python3", "python"];
+const MIN_VERSION: [number, number] = [3, 10];
+const HEADROOM_HEALTH_TIMEOUT_MS = 1500;
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "[::1]", "0.0.0.0"]);
+
+export const DEFAULT_HEADROOM_URL = process.env.HEADROOM_URL || "http://localhost:8787";
+
+export interface HeadroomStatus {
+  installed: boolean;
+  path: string | null;
+  running: boolean;
+  python: string | null;
+  localUrl: boolean;
+  canStart: boolean;
+}
+
+/** Locate the `headroom` binary, or null if not installed. */
+export function findHeadroomBinary(): string | null {
+  try {
+    const out = execSync(`${WHICH_CMD} headroom`, {
+      stdio: ["ignore", "pipe", "ignore"],
+      windowsHide: true,
+      env: { ...process.env, PATH: EXTENDED_PATH },
+    })
+      .toString()
+      .trim();
+    // Windows `where` may return multiple lines — take the first.
+    return out ? (out.split(/\r?\n/)[0] ?? "").trim() || null : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Find a Python interpreter >= 3.10 (headroom-ai requires it), or null. */
+export function findPython310(): string | null {
+  for (const candidate of PYTHON_CANDIDATES) {
+    try {
+      const ver = execSync(`${candidate} --version`, {
+        stdio: ["ignore", "pipe", "ignore"],
+        windowsHide: true,
+        env: { ...process.env, PATH: EXTENDED_PATH },
+      })
+        .toString()
+        .trim();
+      const match = ver.match(/(\d+)\.(\d+)/);
+      if (!match) continue;
+      const major = parseInt(match[1]!, 10);
+      const minor = parseInt(match[2]!, 10);
+      if (major > MIN_VERSION[0] || (major === MIN_VERSION[0] && minor >= MIN_VERSION[1])) {
+        return candidate;
+      }
+    } catch {
+      // candidate not present, try next
+    }
+  }
+  return null;
+}
+
+/** Probe a Headroom proxy's /health. */
+export async function probeProxyRunning(url: string): Promise<boolean> {
+  if (!url) return false;
+  const base = String(url).replace(/\/$/, "");
+  try {
+    const res = await fetch(`${base}/health`, { signal: AbortSignal.timeout(HEADROOM_HEALTH_TIMEOUT_MS) });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+export function isLoopbackHeadroomUrl(url: string): boolean {
+  try {
+    const parsed = new URL(url);
+    return LOOPBACK_HOSTS.has(parsed.hostname);
+  } catch {
+    return false;
+  }
+}
+
+/** Aggregate status for the dashboard: installed, running, python interpreter. */
+export async function getHeadroomStatus(url: string): Promise<HeadroomStatus> {
+  const path = findHeadroomBinary();
+  const python = findPython310();
+  const installed = Boolean(path);
+  const running = await probeProxyRunning(url);
+  const localUrl = isLoopbackHeadroomUrl(url);
+  return { installed, path, running, python, localUrl, canStart: installed && localUrl };
+}

package/src/headroom/process.ts

@@ -0,0 +1,166 @@
+/**
+ * Headroom proxy lifecycle — start/stop the external `headroom proxy` as a
+ * detached child of the gateway, tracked by a PID file under the data dir.
+ *
+ * aigetwey's own implementation.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { findHeadroomBinary } from "./detect.js";
+
+const DATA_DIR = path.resolve(process.env.AIGETWEY_DATA_DIR ?? "data");
+const HEADROOM_DIR = path.join(DATA_DIR, "headroom");
+const PID_FILE = path.join(HEADROOM_DIR, "proxy.pid");
+const LOG_FILE = path.join(HEADROOM_DIR, "proxy.log");
+const DEFAULT_PORT = 8787;
+const STARTUP_TIMEOUT_MS = 8000;
+
+interface CodedError extends Error {
+  code?: string;
+}
+
+function ensureDir(): void {
+  if (!fs.existsSync(HEADROOM_DIR)) fs.mkdirSync(HEADROOM_DIR, { recursive: true });
+}
+
+function readPid(): number | null {
+  try {
+    if (fs.existsSync(PID_FILE)) return parseInt(fs.readFileSync(PID_FILE, "utf8"), 10);
+  } catch {
+    /* ignore */
+  }
+  return null;
+}
+
+function writePid(pid: number): void {
+  ensureDir();
+  fs.writeFileSync(PID_FILE, String(pid));
+}
+
+function clearPid(): void {
+  try {
+    if (fs.existsSync(PID_FILE)) fs.unlinkSync(PID_FILE);
+  } catch {
+    /* ignore */
+  }
+}
+
+/** process.kill(pid, 0) throws if the pid is dead — use it to probe liveness. */
+export function isPidAlive(pid: number | null): boolean {
+  if (!pid || typeof pid !== "number") return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function getManagedPid(): number | null {
+  const pid = readPid();
+  return pid && isPidAlive(pid) ? pid : null;
+}
+
+export async function startHeadroomProxy({ port = DEFAULT_PORT }: { port?: number } = {}): Promise<{
+  pid: number;
+  alreadyRunning: boolean;
+}> {
+  const safePort = Number(port) > 0 && Number(port) < 65536 ? Number(port) : DEFAULT_PORT;
+  const binary = findHeadroomBinary();
+  if (!binary) {
+    const err: CodedError = new Error("Headroom CLI not installed");
+    err.code = "NOT_INSTALLED";
+    throw err;
+  }
+
+  const existing = getManagedPid();
+  if (existing) return { pid: existing, alreadyRunning: true };
+
+  ensureDir();
+  // spawn stdio requires fd numbers, not WriteStream objects.
+  const outFd = fs.openSync(LOG_FILE, "a");
+
+  const child = spawn(binary, ["proxy", "--port", String(safePort)], {
+    stdio: ["ignore", outFd, outFd],
+    detached: true,
+    windowsHide: true,
+    env: { ...process.env },
+  });
+
+  if (!child.pid) {
+    fs.closeSync(outFd);
+    const err: CodedError = new Error("Failed to spawn headroom proxy");
+    err.code = "SPAWN_FAILED";
+    throw err;
+  }
+
+  child.unref();
+  writePid(child.pid);
+
+  // Wait until the process either stays alive briefly (success) or exits fast (failure).
+  await new Promise<void>((resolve, reject) => {
+    const startupTimer = setTimeout(() => {
+      if (isPidAlive(child.pid ?? null)) resolve();
+      else reject(new Error("headroom proxy exited during startup — see proxy.log"));
+    }, STARTUP_TIMEOUT_MS);
+
+    child.once("exit", (code) => {
+      clearTimeout(startupTimer);
+      clearPid();
+      try {
+        fs.closeSync(outFd);
+      } catch {
+        /* already closed */
+      }
+      const e: CodedError = new Error(`headroom proxy exited early (code=${code}) — see proxy.log`);
+      e.code = "EARLY_EXIT";
+      reject(e);
+    });
+  });
+
+  // Close parent's copy of the fd; child retains its own after unref.
+  try {
+    fs.closeSync(outFd);
+  } catch {
+    /* already closed */
+  }
+
+  return { pid: child.pid, alreadyRunning: false };
+}
+
+export function stopHeadroomProxy(): { stopped: boolean; reason?: string; pid?: number } {
+  const pid = getManagedPid();
+  if (!pid) return { stopped: false, reason: "not_running" };
+  try {
+    process.kill(pid, "SIGTERM");
+    // Give it a moment, then force if still alive.
+    setTimeout(() => {
+      if (isPidAlive(pid)) {
+        try {
+          process.kill(pid, "SIGKILL");
+        } catch {
+          /* already gone */
+        }
+      }
+    }, 2000);
+    clearPid();
+    return { stopped: true, pid };
+  } catch (e) {
+    clearPid();
+    const err: CodedError = new Error(`Failed to stop headroom proxy: ${(e as Error).message}`);
+    err.code = "STOP_FAILED";
+    throw err;
+  }
+}
+
+export function getHeadroomLogTail(maxLines = 200): string {
+  try {
+    if (!fs.existsSync(LOG_FILE)) return "";
+    const content = fs.readFileSync(LOG_FILE, "utf8");
+    const lines = content.split(/\r?\n/).filter(Boolean);
+    return lines.slice(-maxLines).join("\n");
+  } catch {
+    return "";
+  }
+}

package/src/inject/caveman.ts

@@ -0,0 +1,35 @@
+/**
+ * Caveman injection. Prepends a system instruction telling the model to answer
+ * in terse "caveman speak" — dropping articles, filler and pleasantries while
+ * keeping full technical substance — to cut OUTPUT tokens.
+ *
+ * Four intensities trade brevity against readability. Returns null for "off" so
+ * the handler can skip injection entirely.
+ */
+
+export type InjectLevel = "off" | "lite" | "full" | "ultra";
+
+const PROMPTS: Record<Exclude<InjectLevel, "off">, string> = {
+  lite:
+    "Trim filler. Drop pleasantries (sure/certainly/happy to), hedging, and " +
+    "restating the question. Keep all technical substance, code, and exact error " +
+    "text verbatim. Prefer short words.",
+  full:
+    "Answer like a terse expert. Drop articles (a/an/the), filler " +
+    "(just/really/basically/actually), pleasantries, and hedging. Fragments OK. " +
+    "Short synonyms (big not extensive, fix not implement-a-solution-for). " +
+    "Keep ALL technical substance, exact identifiers, and code blocks unchanged. " +
+    "Quote error messages exactly. Pattern: [thing] [action] [reason].",
+  ultra:
+    "Maximum compression. Telegraphic fragments only — no articles, no filler, no " +
+    "pleasantries, no transitions. One idea per line where possible. Keep every " +
+    "technical fact, identifier, number, and code block exact and complete; never " +
+    "drop substance to save words. Quote errors verbatim. Prose is the enemy; " +
+    "information is not.",
+};
+
+/** System-prompt text for a caveman level, or null when off. */
+export function cavemanPrompt(level: InjectLevel): string | null {
+  if (level === "off") return null;
+  return PROMPTS[level];
+}

package/src/inject/index.ts

@@ -0,0 +1,46 @@
+/**
+ * Inject orchestrator. Builds the combined caveman + ponytail system prompt and
+ * prepends it to a canonical request's messages, in place.
+ *
+ * Pipeline order (handler): RTK compresses tool_result in the input first, THEN
+ * inject prepends the output-style prompt — they touch different parts of the
+ * request and stack cleanly (RTK shrinks input, caveman shrinks output prose,
+ * ponytail shrinks output code).
+ *
+ * Fail-open: an injection error must never break a request — the caller wraps
+ * this in try/catch and proceeds without injection.
+ */
+import type { CanonicalMessage, CanonicalRequest } from "../core/canonical.js";
+import { cavemanPrompt, type InjectLevel } from "./caveman.js";
+import { ponytailPrompt } from "./ponytail.js";
+
+export type { InjectLevel } from "./caveman.js";
+
+export interface InjectSettings {
+  caveman: InjectLevel;
+  ponytail: InjectLevel;
+}
+
+/** Combined system-prompt text for the active toggles, or null if both off. */
+export function buildInjection(settings: InjectSettings): string | null {
+  const parts = [cavemanPrompt(settings.caveman), ponytailPrompt(settings.ponytail)].filter(
+    (p): p is string => p !== null,
+  );
+  return parts.length > 0 ? parts.join("\n\n") : null;
+}
+
+/**
+ * Prepend the injection as the FIRST system message. A dedicated leading system
+ * message (rather than merging into an existing one) keeps the gateway's
+ * instruction separate from the client's own system prompt, and works for every
+ * provider format since the adapter collapses system messages on egress.
+ *
+ * Returns true if anything was injected.
+ */
+export function injectInto(req: CanonicalRequest, settings: InjectSettings): boolean {
+  const text = buildInjection(settings);
+  if (!text) return false;
+  const sys: CanonicalMessage = { role: "system", content: text };
+  req.messages.unshift(sys);
+  return true;
+}

package/src/inject/ponytail.ts

@@ -0,0 +1,31 @@
+/**
+ * Ponytail injection. Prepends a system instruction nudging the model toward a
+ * "lazy senior dev" coding style — minimal, YAGNI, deletion over addition — to
+ * cut OUTPUT tokens AND reduce over-engineered code.
+ *
+ * Shares the InjectLevel scale with caveman; the two stack (caveman shapes prose
+ * style, ponytail shapes code style). Returns null for "off".
+ */
+import type { InjectLevel } from "./caveman.js";
+
+const PROMPTS: Record<Exclude<InjectLevel, "off">, string> = {
+  lite:
+    "Prefer the smallest change that solves the problem. Don't add features, " +
+    "abstractions, or error handling beyond what was asked.",
+  full:
+    "Code like a lazy senior dev: do the minimum that fully solves the task. " +
+    "YAGNI — no speculative abstractions, config, or future-proofing. Prefer " +
+    "deleting code over adding it. No defensive checks for cases that can't " +
+    "happen. Don't explain code that's self-evident. Don't refactor unrelated code.",
+  ultra:
+    "Ruthless minimalism. Smallest possible diff. No new abstractions, no " +
+    "helpers for single callers, no comments unless a non-obvious WHY. Delete " +
+    "before you add. Skip boilerplate, validation, and error handling unless " +
+    "explicitly required. Output only the code that changed plus a one-line note.",
+};
+
+/** System-prompt text for a ponytail level, or null when off. */
+export function ponytailPrompt(level: InjectLevel): string | null {
+  if (level === "off") return null;
+  return PROMPTS[level];
+}

package/src/middleware/auth.ts

@@ -0,0 +1,76 @@
+/**
+ * Gateway-level auth. Clients present one of `server.api_keys` — OUR keys (handed
+ * to your devices), distinct from the upstream provider keys in each provider.
+ *
+ * Accepted in either header so both client families work unchanged:
+ *   - Authorization: Bearer <key>   (OpenAI-style clients)
+ *   - x-api-key: <key>              (Anthropic-style clients)
+ *
+ * Empty `server.api_keys` disables auth (localhost dev mode).
+ */
+import { createHash, timingSafeEqual } from "node:crypto";
+import type { FastifyRequest } from "fastify";
+
+function digest(s: string): Buffer {
+  return createHash("sha256").update(s).digest();
+}
+
+/** Constant-time membership test over fixed-length digests. */
+export function isValidKey(presented: string, validKeys: string[]): boolean {
+  const p = digest(presented);
+  // compare against every key so timing can't reveal which one matched.
+  let ok = false;
+  for (const k of validKeys) {
+    if (timingSafeEqual(p, digest(k))) ok = true;
+  }
+  return ok;
+}
+
+export function extractKey(req: FastifyRequest): string | null {
+  const auth = req.headers["authorization"];
+  if (typeof auth === "string" && auth.startsWith("Bearer ")) {
+    return auth.slice("Bearer ".length).trim();
+  }
+  const xkey = req.headers["x-api-key"];
+  if (typeof xkey === "string" && xkey.length > 0) return xkey;
+  return null;
+}
+
+export interface AuthResult {
+  ok: boolean;
+  status?: number;
+  error?: string;
+}
+
+export function checkAuth(req: FastifyRequest, validKeys: string[]): AuthResult {
+  if (validKeys.length === 0) return { ok: true }; // auth disabled
+  const key = extractKey(req);
+  if (!key) return { ok: false, status: 401, error: "missing API key" };
+  if (!isValidKey(key, validKeys)) return { ok: false, status: 401, error: "invalid API key" };
+  return { ok: true };
+}
+
+/** Verifies a presented admin password (against the persisted hash store). */
+export interface AdminVerifier {
+  enabled: boolean;
+  verify(password: string): boolean;
+}
+
+/**
+ * Admin auth for /admin/* — the password is presented as a Bearer token (the
+ * dashboard proxies it server-side; never reaches the browser) and checked
+ * against the hash store (seeded from AIGETWEY_ADMIN_PASSWORD, changeable at
+ * runtime).
+ *
+ * If no password is set, admin routes LOCK (503) rather than open — admin
+ * surfaces provider keys, so failing open would leak secrets.
+ */
+export function checkAdminAuth(req: FastifyRequest, auth: AdminVerifier | undefined): AuthResult {
+  if (!auth || !auth.enabled) {
+    return { ok: false, status: 503, error: "admin disabled (set AIGETWEY_ADMIN_PASSWORD)" };
+  }
+  const key = extractKey(req);
+  if (!key) return { ok: false, status: 401, error: "missing admin password" };
+  if (!auth.verify(key)) return { ok: false, status: 401, error: "invalid admin password" };
+  return { ok: true };
+}