Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

14.5 KB
Raw Blame
/**
 * Tests for expanded HeadroomClient — chat.completions, messages, metrics, CCR, etc.
 * Uses mocked proxy (no real server needed).
 */
import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
import { HeadroomClient } from "../src/client.js";
import { HeadroomConnectionError } from "../src/types.js";

const mockFetch = vi.fn();
vi.stubGlobal("fetch", mockFetch);

function jsonResponse(data: any, ok = true) {
  return {
    ok,
    status: ok ? 200 : 500,
    json: async () => data,
    text: async () => JSON.stringify(data),
  };
}

describe("provider requests authenticate to the proxy separately", () => {
  beforeEach(() => {
    mockFetch.mockReset();
    mockFetch.mockResolvedValue(jsonResponse({}));
    for (const name of ["HEADROOM_API_KEY", "OPENAI_API_KEY", "ANTHROPIC_API_KEY"]) {
      vi.stubEnv(name, "");
    }
  });
  afterEach(() => vi.unstubAllEnvs());

  it.each([
    ["openai", "explicit"], ["anthropic", "explicit"],
    ["openai", "environment"], ["anthropic", "environment"],
    ["openai", "proxy-only"], ["anthropic", "proxy-only"],
    ["openai", "provider-only"], ["anthropic", "provider-only"],
  ])("sends the correct credentials for %s (%s)", async (provider, source) => {
    const hasProxy = source !== "provider-only";
    const hasProvider = source !== "proxy-only";
    const fromEnv = source === "environment";
    if (fromEnv) {
      vi.stubEnv("HEADROOM_API_KEY", "proxy-token");
      vi.stubEnv(provider === "openai" ? "OPENAI_API_KEY" : "ANTHROPIC_API_KEY", "provider-key");
    }
    const client = new HeadroomClient({
      baseUrl: "http://proxy:8787",
      apiKey: hasProxy && !fromEnv ? "proxy-token" : undefined,
      providerApiKey: hasProvider && !fromEnv ? "provider-key" : undefined,
    });
    const params = { model: "test-model", messages: [{ role: "user" as const, content: "hello" }] };
    await (provider === "openai" ? client.chat.completions.create(params) : client.messages.create(params));

    const headers = new Headers(mockFetch.mock.calls[0][1].headers);
    expect(headers.get("X-Headroom-Proxy-Token")).toBe(hasProxy ? "proxy-token" : null);
    expect(headers.get("Authorization")).toBe(
      hasProvider ? (provider === "openai" ? "Bearer provider-key" : null) : "Bearer proxy-token",
    );
    expect(headers.get("x-api-key")).toBe(hasProvider && provider === "anthropic" ? "provider-key" : null);
  });
});

describe("HeadroomClient constructor", () => {
  it("accepts extended options", () => {
    const client = new HeadroomClient({
      baseUrl: "http://proxy:8787",
      apiKey: "hdr-key",
      providerApiKey: "sk-openai-key",
      defaultMode: "optimize",
      config: { smartCrusher: { enabled: true } },
    });
    expect(client).toBeDefined();
    expect(client.providerApiKey).toBe("sk-openai-key");
  });

  it("has chat.completions sub-client", () => {
    const client = new HeadroomClient();
    expect(client.chat).toBeDefined();
    expect(client.chat.completions).toBeDefined();
  });

  it("has messages sub-client", () => {
    const client = new HeadroomClient();
    expect(client.messages).toBeDefined();
  });

  it("has telemetry namespace", () => {
    const client = new HeadroomClient();
    expect(client.telemetry).toBeDefined();
    expect(client.telemetry.getStats).toBeTypeOf("function");
  });

  it("has feedback namespace", () => {
    const client = new HeadroomClient();
    expect(client.feedback).toBeDefined();
    expect(client.feedback.getStats).toBeTypeOf("function");
  });

  it("has toin namespace", () => {
    const client = new HeadroomClient();
    expect(client.toin).toBeDefined();
    expect(client.toin.getStats).toBeTypeOf("function");
  });
});

describe("HeadroomClient.health()", () => {
  beforeEach(() => vi.clearAllMocks());

  it("returns health status", async () => {
    mockFetch.mockResolvedValue(
      jsonResponse({
        status: "healthy",
        version: "0.5.18",
        config: { optimize: true, cache: true, rate_limit: false },
      }),
    );

    const client = new HeadroomClient({ baseUrl: "http://test:8787" });
    const health = await client.health();

    expect(health.status).toBe("healthy");
    expect(health.version).toBe("0.5.18");
    expect(health.config.optimize).toBe(true);
  });
});

describe("HeadroomClient.proxyStats()", () => {
  beforeEach(() => vi.clearAllMocks());

  it("returns proxy stats with camelCase keys", async () => {
    mockFetch.mockResolvedValue(
      jsonResponse({
        requests: { total: 100, cached: 10, rate_limited: 0, failed: 2 },
        tokens: { input: 50000, output: 20000, saved: 30000 },
      }),
    );

    const client = new HeadroomClient({ baseUrl: "http://test:8787" });
    const stats = await client.proxyStats();

    expect(stats.requests.total).toBe(100);
    expect(stats.requests.rateLimited).toBe(0);
    expect(stats.tokens.saved).toBe(30000);
  });
});

describe("HeadroomClient.getMetrics()", () => {
  beforeEach(() => vi.clearAllMocks());

  it("returns request metrics from proxy", async () => {
    mockFetch.mockResolvedValue(
      jsonResponse({
        recent_requests: [
          { request_id: "r1", model: "gpt-4o", tokens_input_before: 1000, mode: "optimize" },
          { request_id: "r2", model: "claude", tokens_input_before: 2000, mode: "audit" },
        ],
      }),
    );

    const client = new HeadroomClient({ baseUrl: "http://test:8787" });
    const metrics = await client.getMetrics();

    expect(metrics).toHaveLength(2);
    expect(metrics[0].requestId).toBe("r1");
    expect(metrics[0].tokensInputBefore).toBe(1000);
  });

  it("filters by model", async () => {
    mockFetch.mockResolvedValue(
      jsonResponse({
        recent_requests: [
          { request_id: "r1", model: "gpt-4o", mode: "optimize" },
          { request_id: "r2", model: "claude", mode: "optimize" },
        ],
      }),
    );

    const client = new HeadroomClient({ baseUrl: "http://test:8787" });
    const metrics = await client.getMetrics({ model: "gpt-4o" });

    expect(metrics).toHaveLength(1);
    expect(metrics[0].requestId).toBe("r1");
  });

  it("applies limit", async () => {
    mockFetch.mockResolvedValue(
      jsonResponse({
        recent_requests: [
          { request_id: "r1" },
          { request_id: "r2" },
          { request_id: "r3" },
        ],
      }),
    );

    const client = new HeadroomClient({ baseUrl: "http://test:8787" });
    const metrics = await client.getMetrics({ limit: 2 });

    expect(metrics).toHaveLength(2);
  });
});

describe("HeadroomClient.getSummary()", () => {
  beforeEach(() => vi.clearAllMocks());

  it("returns aggregated summary", async () => {
    mockFetch.mockResolvedValue(
      jsonResponse({
        requests: { total: 50, by_model: { "gpt-4o": 30 }, failed: 1 },
        tokens: { total_before_compression: 100000, saved: 70000, savings_percent: 70 },
      }),
    );

    const client = new HeadroomClient({ baseUrl: "http://test:8787" });
    const summary = await client.getSummary();

    expect(summary.totalRequests).toBe(50);
    expect(summary.totalTokensSaved).toBe(70000);
    expect(summary.errorCount).toBe(1);
  });
});

describe("HeadroomClient.validateSetup()", () => {
  beforeEach(() => vi.clearAllMocks());

  it("returns valid when healthy", async () => {
    mockFetch.mockResolvedValue(
      jsonResponse({
        status: "healthy",
        config: { optimize: true },
      }),
    );

    const client = new HeadroomClient({ baseUrl: "http://test:8787" });
    const result = await client.validateSetup();

    expect(result.valid).toBe(true);
    expect(result.errors).toEqual([]);
  });

  it("returns invalid when unhealthy", async () => {
    mockFetch.mockResolvedValue(
      jsonResponse({
        status: "unhealthy",
        config: {},
      }),
    );

    const client = new HeadroomClient({ baseUrl: "http://test:8787" });
    const result = await client.validateSetup();

    expect(result.valid).toBe(false);
    expect(result.errors).toContain("Proxy unhealthy");
  });
});

describe("HeadroomClient.retrieve()", () => {
  beforeEach(() => vi.clearAllMocks());

  it("retrieves by hash", async () => {
    mockFetch.mockResolvedValue(
      jsonResponse({
        hash: "abc123",
        original_content: "full data here",
        original_tokens: 500,
        original_item_count: 20,
        compressed_item_count: 5,
        tool_name: "search",
        retrieval_count: 1,
      }),
    );

    const client = new HeadroomClient({ baseUrl: "http://test:8787" });
    const result = await client.retrieve("abc123") as any;

    expect(result.hash).toBe("abc123");
    expect(result.originalContent).toBe("full data here");
    expect(result.originalTokens).toBe(500);
  });

  it("retrieves with query", async () => {
    mockFetch.mockResolvedValue(
      jsonResponse({
        hash: "abc123",
        query: "error logs",
        results: [{ text: "ERROR: connection failed" }],
        count: 1,
      }),
    );

    const client = new HeadroomClient({ baseUrl: "http://test:8787" });
    const result = await client.retrieve("abc123", { query: "error logs" }) as any;

    expect(result.query).toBe("error logs");
    expect(result.count).toBe(1);
  });
});

describe("HeadroomClient.clearCache()", () => {
  beforeEach(() => vi.clearAllMocks());

  it("clears cache", async () => {
    mockFetch.mockResolvedValue(jsonResponse({ status: "cleared" }));

    const client = new HeadroomClient({ baseUrl: "http://test:8787" });
    const result = await client.clearCache();

    expect(result.status).toBe("cleared");
  });
});

describe("HeadroomClient.close()", () => {
  it("is a no-op (HTTP client is stateless)", () => {
    const client = new HeadroomClient();
    expect(() => client.close()).not.toThrow();
  });
});

describe("HeadroomClient.compressRaw()", () => {
  beforeEach(() => vi.clearAllMocks());

  it("sends raw body to /v1/compress", async () => {
    mockFetch.mockResolvedValue(
      jsonResponse({
        messages: [],
        tokens_before: 100,
        tokens_after: 50,
      }),
    );

    const client = new HeadroomClient({ baseUrl: "http://test:8787" });
    const result = await client.compressRaw({
      messages: [{ role: "user", content: "test" }],
      model: "gpt-4o",
      config: { default_mode: "simulate" },
    });

    expect(result.tokens_before).toBe(100);

    const [url] = mockFetch.mock.calls[0];
    expect(url).toBe("http://test:8787/v1/compress");
  });
});

describe("HeadroomClient config passthrough", () => {
  beforeEach(() => vi.clearAllMocks());

  it("sends config as snake_case in compress body", async () => {
    mockFetch.mockResolvedValue(
      jsonResponse({
        messages: [{ role: "user", content: "hi" }],
        tokens_before: 10,
        tokens_after: 10,
        tokens_saved: 0,
        compression_ratio: 1.0,
        transforms_applied: [],
        ccr_hashes: [],
      }),
    );

    const client = new HeadroomClient({
      baseUrl: "http://test:8787",
      config: {
        smartCrusher: { enabled: true, minTokensToCrush: 100 },
      },
    });

    await client.compress([{ role: "user", content: "hi" }]);

    const [, opts] = mockFetch.mock.calls[0];
    const body = JSON.parse(opts.body);
    expect(body.config).toBeDefined();
    expect(body.config.smart_crusher.enabled).toBe(true);
    expect(body.config.smart_crusher.min_tokens_to_crush).toBe(100);
  });
});

describe("shared HTTP transport", () => {
  beforeEach(() => {
    mockFetch.mockReset();
  });

  it("serializes structured bodies once and sends serialized bodies verbatim", async () => {
    mockFetch.mockResolvedValue(jsonResponse({ ok: true }));
    const client = new HeadroomClient({ baseUrl: "http://test:8787" });

    // Structured body (rawFetch) — serialized exactly once.
    await client.chat.completions.create({ model: "gpt-4o", messages: [{ role: "user", content: "hi" }] });
    expect(JSON.parse(mockFetch.mock.calls[0][1].body).messages[0].content).toBe("hi");

    // Already-serialized body (_fetch) — passed through, not re-stringified.
    await client.compressRaw({ messages: [{ role: "user", content: "hi" }] } as any);
    expect(JSON.parse(mockFetch.mock.calls[1][1].body).messages[0].content).toBe("hi");

    // No body — nothing sent.
    await client.telemetry.getStats();
    expect(mockFetch.mock.calls[2][1].body).toBeUndefined();
  });

  it("keeps proxy headers on requests without provider auth", async () => {
    mockFetch.mockResolvedValue(jsonResponse({ ok: true }));
    const client = new HeadroomClient({ baseUrl: "http://test:8787", apiKey: "hr_proxykey", stack: "cli" });
    await client.telemetry.getStats();
    const headers = mockFetch.mock.calls[0][1].headers;
    expect(headers["Content-Type"]).toBe("application/json");
    expect(headers["Authorization"]).toBe("Bearer hr_proxykey");
    expect(headers["X-Headroom-Stack"]).toBe("cli");
  });

  it("does not overwrite provider auth headers with the proxy apiKey", async () => {
    mockFetch.mockResolvedValue(jsonResponse({ choices: [] }));
    const client = new HeadroomClient({
      baseUrl: "http://test:8787",
      apiKey: "hr_proxykey",
      providerApiKey: "sk-provider",
    });
    await client.chat.completions.create({ model: "gpt-4o", messages: [] });
    expect(mockFetch.mock.calls[0][1].headers["Authorization"]).toBe("Bearer sk-provider");

    await client.messages.create({ model: "claude-3", messages: [] } as any);
    const anthropicHeaders = mockFetch.mock.calls[1][1].headers;
    expect(anthropicHeaders["x-api-key"]).toBe("sk-provider");
    expect(anthropicHeaders["Authorization"]).toBeUndefined();
  });

  it("does not overwrite an environment provider key either", async () => {
    mockFetch.mockResolvedValue(jsonResponse({ choices: [] }));
    vi.stubEnv("OPENAI_API_KEY", "sk-env-provider");
    const client = new HeadroomClient({ baseUrl: "http://test:8787", apiKey: "hr_proxykey" });
    await client.chat.completions.create({ model: "gpt-4o", messages: [] });
    expect(mockFetch.mock.calls[0][1].headers["Authorization"]).toBe("Bearer sk-env-provider");
    vi.unstubAllEnvs();
  });

  it("maps non-ok responses with non-JSON bodies", async () => {
    mockFetch.mockResolvedValue({
      ok: false,
      status: 502,
      json: async () => {
        throw new Error("not json");
      },
    });
    const client = new HeadroomClient({ baseUrl: "http://test:8787" });
    await expect(client.telemetry.getStats()).rejects.toThrow("HTTP 502");
  });

  it("wraps connection failures", async () => {
    mockFetch.mockRejectedValue(new TypeError("fetch failed"));
    const client = new HeadroomClient({ baseUrl: "http://test:8787" });
    await expect(client.telemetry.getStats()).rejects.toThrow(HeadroomConnectionError);
  });
});