@tyvm/knowhow 0.0.155 → 0.0.157

package/tests/unit/auth/keyAuth.test.ts

@@ -24,12 +24,16 @@ jest.mock("../../../src/auth/browserLogin", () => ({
   getCliUserAgent: () => "test-agent",
 }));
 
+import fs from "fs";
+import os from "os";
+import path from "path";
 import {
   authenticateWithKey,
   exchangeAvailablePublicKeyJwt,
   exchangePublicKeyJwt,
   hasKeyPair,
   registerPublicKey,
+  storeJwt,
 } from "../../../src/auth/keyAuth";
 
 describe("keyAuth", () => {
@@ -109,6 +113,23 @@ describe("keyAuth", () => {
     expect(signMessage).not.toHaveBeenCalled();
   });
 
+  it("stores a refreshed JWT in the active isolated project", () => {
+    const originalCwd = process.cwd();
+    const temporaryProject = fs.mkdtempSync(path.join(os.tmpdir(), "knowhow-key-auth-"));
+    try {
+      process.chdir(temporaryProject);
+
+      storeJwt("fresh-project-jwt");
+
+      const jwtPath = path.join(temporaryProject, ".knowhow", ".jwt");
+      expect(fs.readFileSync(jwtPath, "utf8")).toBe("fresh-project-jwt");
+      expect(fs.statSync(jwtPath).mode & 0o777).toBe(0o600);
+    } finally {
+      process.chdir(originalCwd);
+      fs.rmSync(temporaryProject, { recursive: true, force: true });
+    }
+  });
+
   it("registers only server-owned Ed25519 key fields in the selected environment", async () => {
     post.mockResolvedValueOnce({ data: {}, status: 201 });
 

package/tests/unit/clients/anthropic.responseMetadata.test.ts

@@ -0,0 +1,81 @@
+import { GenericAnthropicClient } from "../../../src/clients/anthropic";
+
+const options = {
+  model: "claude-sonnet-4-5",
+  messages: [{ role: "user" as const, content: "hello" }],
+};
+
+describe("Anthropic response metadata", () => {
+  it("emits native message response metadata", async () => {
+    const client = new GenericAnthropicClient("test-key");
+    const observer = jest.fn();
+    (client as any).client = {
+      messages: {
+        create: jest.fn(() => ({
+          withResponse: async () => ({
+            data: {
+              content: [{ type: "text", text: "hi" }],
+              usage: { input_tokens: 3, output_tokens: 2 },
+            },
+            response: new Response(null, {
+              status: 200,
+              headers: {
+                "request-id": "anthropic-request",
+                "anthropic-ratelimit-requests-limit": "50",
+                "anthropic-ratelimit-requests-remaining": "49",
+                "anthropic-ratelimit-tokens-remaining": "900",
+              },
+            }),
+            request_id: "anthropic-request",
+          }),
+        })),
+      },
+    };
+
+    const result = await client.createChatCompletion({
+      ...options,
+      onResponseMetadata: observer,
+    });
+    expect(result.choices[0].message.content).toBe("hi");
+    expect(observer).toHaveBeenCalledWith({
+      statusCode: 200,
+      requestId: "anthropic-request",
+      rateLimit: { limit: 50, remaining: 49, tokenRemaining: 900 },
+      headers: {
+        "request-id": "anthropic-request",
+        "anthropic-ratelimit-requests-limit": "50",
+        "anthropic-ratelimit-requests-remaining": "49",
+        "anthropic-ratelimit-tokens-remaining": "900",
+      },
+    });
+  });
+
+  it("emits API error metadata and preserves error identity", async () => {
+    const client = new GenericAnthropicClient("test-key");
+    const observer = jest.fn();
+    const error = Object.assign(new Error("rate limited"), {
+      status: 429,
+      headers: { "retry-after": "1", cookie: "private" },
+      request_id: "anthropic-rate-request",
+    });
+    (client as any).client = {
+      messages: {
+        create: jest.fn(() => ({
+          withResponse: async () => {
+            throw error;
+          },
+        })),
+      },
+    };
+
+    await expect(
+      client.createChatCompletion({ ...options, onResponseMetadata: observer })
+    ).rejects.toBe(error);
+    expect(observer).toHaveBeenCalledWith({
+      statusCode: 429,
+      requestId: "anthropic-rate-request",
+      rateLimit: { retryAfterSeconds: 1 },
+      headers: { "retry-after": "1" },
+    });
+  });
+});

package/tests/unit/clients/attribution.test.ts

@@ -0,0 +1,185 @@
+const post = jest.fn();
+
+jest.mock("../../../src/utils/http", () => ({
+  __esModule: true,
+  default: { post },
+  HTTP_UNAUTHORIZED_HANDLER: Symbol("refresh"),
+  HttpError: class HttpError extends Error {
+    constructor(
+      public status: number,
+      public response: Response,
+      message: string
+    ) {
+      super(message);
+    }
+  },
+}));
+
+import packageJson from "../../../package.json";
+import { HttpClient } from "../../../src/clients/http";
+import { GenericOpenRouterClient } from "../../../src/clients/openrouter";
+import {
+  KNOWHOW_ATTRIBUTION_HEADERS,
+  withKnowhowAttribution,
+} from "../../../src/clients/attribution";
+
+describe("OpenRouter attribution", () => {
+  beforeEach(() => post.mockReset());
+  afterEach(() => jest.restoreAllMocks());
+
+  it("uses the Knowhow application identity and current package version", () => {
+    expect(KNOWHOW_ATTRIBUTION_HEADERS).toEqual({
+      "HTTP-Referer": "https://knowhow.tyvm.ai",
+      "X-Title": "Knowhow",
+      "X-OpenRouter-Title": "Knowhow",
+      "User-Agent": `knowhow/${packageJson.version}`,
+    });
+  });
+
+  it("applies caller overrides case-insensitively without duplicates", () => {
+    const headers = withKnowhowAttribution({
+      "user-agent": "custom-agent",
+      "HTTP-referer": "https://caller.example",
+      "x-title": "Caller",
+      "x-openrouter-title": "Caller",
+      "X-Custom": "preserved",
+    });
+
+    expect(headers).toEqual({
+      "User-Agent": "custom-agent",
+      "HTTP-Referer": "https://caller.example",
+      "X-Title": "Caller",
+      "X-OpenRouter-Title": "Caller",
+      "X-Custom": "preserved",
+    });
+    for (const name of ["user-agent", "http-referer", "x-title", "x-openrouter-title"]) {
+      expect(
+        Object.keys(headers).filter((key) => key.toLowerCase() === name)
+      ).toHaveLength(1);
+    }
+  });
+
+  it("sends attribution only as OpenRouter request headers", async () => {
+    post.mockResolvedValueOnce({
+      status: 200,
+      headers: new Headers(),
+      data: {
+        choices: [{ message: { role: "assistant", content: "ok" } }],
+        model: "test",
+      },
+    });
+    const client = new GenericOpenRouterClient("test-key");
+    client.setOptions({
+      headers: {
+        "user-agent": "caller-agent",
+        "http-referer": "https://caller.example",
+      },
+    });
+
+    await client.createChatCompletion({
+      model: "test",
+      messages: [{ role: "user", content: "hello" }],
+    });
+
+    const body = post.mock.calls[0][1];
+    const headers = post.mock.calls[0][2].headers;
+    expect(headers).toMatchObject({
+      "HTTP-Referer": "https://caller.example",
+      "X-Title": "Knowhow",
+      "X-OpenRouter-Title": "Knowhow",
+      "User-Agent": "caller-agent",
+      Authorization: "Bearer test-key",
+    });
+    expect(
+      Object.keys(headers).filter(
+        (name) => name.toLowerCase() === "http-referer"
+      )
+    ).toHaveLength(1);
+    expect(
+      Object.keys(headers).filter((name) => name.toLowerCase() === "x-title")
+    ).toHaveLength(1);
+    const serializedBody = JSON.stringify(body);
+    expect(serializedBody).not.toContain("HTTP-Referer");
+    expect(serializedBody).not.toContain("X-OpenRouter-Title");
+    expect(serializedBody).not.toContain("caller-agent");
+  });
+
+  it("does not add OpenRouter attribution to generic provider traffic", async () => {
+    post.mockResolvedValueOnce({
+      status: 200,
+      headers: new Headers(),
+      data: {
+        choices: [{ message: { role: "assistant", content: "ok" } }],
+        model: "test",
+      },
+    });
+    const client = new HttpClient("https://provider.example");
+
+    await client.createChatCompletion({
+      model: "test",
+      messages: [{ role: "user", content: "hello" }],
+    });
+
+    expect(post.mock.calls[0][2].headers).toEqual({});
+  });
+
+  it("sends attribution on OpenRouter embedding requests", async () => {
+    post.mockResolvedValueOnce({
+      status: 200,
+      headers: new Headers(),
+      data: { data: [{ embedding: [1] }], usage: {} },
+    });
+    const client = new GenericOpenRouterClient("initial-key", {
+      headers: { "x-openrouter-title": "Embedding caller" },
+    });
+    client.setKey("replacement-key");
+
+    await client.createEmbedding({ model: "embedding-test", input: "hello" });
+
+    expect(post.mock.calls[0][2].headers).toMatchObject({
+      "HTTP-Referer": "https://knowhow.tyvm.ai",
+      "X-OpenRouter-Title": "Embedding caller",
+      // X-Title was not overridden, so it keeps the default "Knowhow"
+      "X-Title": "Knowhow",
+      "User-Agent": `knowhow/${packageJson.version}`,
+      Authorization: "Bearer replacement-key",
+    });
+  });
+
+  it("sends attribution on OpenRouter streaming requests", async () => {
+    const fetchMock = jest.spyOn(global, "fetch").mockResolvedValueOnce(
+      new Response(
+        'data: {"choices":[{"delta":{"content":"ok"}}]}\n\n' +
+          "data: [DONE]\n\n",
+        {
+          status: 200,
+          headers: { "Content-Type": "text/event-stream" },
+        }
+      )
+    );
+    const client = new GenericOpenRouterClient("test-key", {
+      headers: { "HTTP-referer": "https://stream.example" },
+    });
+
+    const chunks = [];
+    for await (const chunk of client.createChatCompletionStream({
+      model: "test",
+      messages: [{ role: "user", content: "hello" }],
+    })) {
+      chunks.push(chunk);
+    }
+
+    const headers = fetchMock.mock.calls[0][1]?.headers as Record<
+      string,
+      string
+    >;
+    expect(headers).toMatchObject({
+      "HTTP-Referer": "https://stream.example",
+      "X-OpenRouter-Title": "Knowhow",
+      "X-Title": "Knowhow",
+      "User-Agent": `knowhow/${packageJson.version}`,
+      Authorization: "Bearer test-key",
+    });
+    expect(chunks.length).toBeGreaterThan(0);
+  });
+});

package/tests/unit/clients/http.responseMetadata.test.ts

@@ -0,0 +1,86 @@
+const post = jest.fn();
+
+jest.mock("../../../src/utils/http", () => ({
+  __esModule: true,
+  default: { post },
+  HTTP_UNAUTHORIZED_HANDLER: Symbol("refresh"),
+  HttpError: class HttpError extends Error {
+    constructor(
+      public status: number,
+      public response: Response,
+      message: string
+    ) {
+      super(message);
+    }
+  },
+}));
+
+import { HttpClient } from "../../../src/clients/http";
+
+describe("HttpClient response metadata", () => {
+  beforeEach(() => post.mockReset());
+
+  it("emits chat metadata and excludes transport-only options from its body", async () => {
+    post.mockResolvedValue({
+      status: 200,
+      headers: new Headers({
+        "x-request-id": "http-request",
+        "x-ratelimit-limit-requests": "20",
+        "x-ratelimit-remaining-requests": "19",
+      }),
+      data: {
+        choices: [{ message: { role: "assistant", content: "hi" } }],
+        model: "test",
+      },
+    });
+    const observer = jest.fn();
+    const client = new HttpClient("https://provider.example");
+    const controller = new AbortController();
+    await client.createChatCompletion({
+      model: "test",
+      messages: [{ role: "user", content: "hello" }],
+      signal: controller.signal,
+      timeout: 1,
+      maxRetries: 0,
+      backoffMs: 1,
+      onResponseMetadata: observer,
+    });
+
+    expect(post.mock.calls[0][1]).not.toHaveProperty("onResponseMetadata");
+    expect(post.mock.calls[0][1]).not.toHaveProperty("signal");
+    expect(post.mock.calls[0][1]).not.toHaveProperty("timeout");
+    expect(observer).toHaveBeenCalledWith({
+      statusCode: 200,
+      requestId: "http-request",
+      rateLimit: { limit: 20, remaining: 19 },
+      headers: {
+        "x-request-id": "http-request",
+        "x-ratelimit-limit-requests": "20",
+        "x-ratelimit-remaining-requests": "19",
+      },
+    });
+  });
+
+  it("emits embedding error metadata and preserves the original HttpError", async () => {
+    const { HttpError } = require("../../../src/utils/http");
+    const error = new HttpError(
+      429,
+      new Response(null, { headers: { "retry-after": "3" } }),
+      "rate limited"
+    );
+    post.mockRejectedValue(error);
+    const observer = jest.fn();
+    await expect(
+      new HttpClient("https://provider.example").createEmbedding({
+        model: "test",
+        input: "hello",
+        onResponseMetadata: observer,
+      })
+    ).rejects.toBe(error);
+    expect(observer).toHaveBeenCalledWith({
+      statusCode: 429,
+      rateLimit: { retryAfterSeconds: 3 },
+      headers: { "retry-after": "3" },
+    });
+  });
+});

package/tests/unit/clients/openai.responseMetadata.test.ts

@@ -0,0 +1,90 @@
+import { GenericOpenAiClient } from "../../../src/clients/openai";
+
+const completionOptions = {
+  model: "gpt-4o-mini",
+  messages: [{ role: "user" as const, content: "hello" }],
+};
+
+describe("OpenAI response metadata", () => {
+  it("emits native chat response metadata before mapping", async () => {
+    const client = new GenericOpenAiClient("test-key");
+    const observer = jest.fn();
+    (client as any).client = {
+      chat: {
+        completions: {
+          create: jest.fn(() => ({
+            withResponse: async () => ({
+              data: {
+                choices: [{ message: { role: "assistant", content: "hi" } }],
+                usage: undefined,
+              },
+              response: new Response(null, {
+                status: 200,
+                headers: {
+                  "x-request-id": "chat-request",
+                  "x-ratelimit-limit-requests": "100",
+                  "x-ratelimit-remaining-requests": "99",
+                  "x-ratelimit-limit-tokens": "1000",
+                },
+              }),
+              request_id: "chat-request",
+            }),
+          })),
+        },
+      },
+    };
+
+    const result = await client.createChatCompletion({
+      ...completionOptions,
+      onResponseMetadata: observer,
+    });
+    expect(result.choices[0].message.content).toBe("hi");
+    expect(observer).toHaveBeenCalledWith({
+      statusCode: 200,
+      requestId: "chat-request",
+      rateLimit: { limit: 100, remaining: 99, tokenLimit: 1000 },
+      headers: {
+        "x-request-id": "chat-request",
+        "x-ratelimit-limit-requests": "100",
+        "x-ratelimit-remaining-requests": "99",
+        "x-ratelimit-limit-tokens": "1000",
+      },
+    });
+  });
+
+  it("emits API error metadata and preserves the original error", async () => {
+    const client = new GenericOpenAiClient("test-key");
+    const observer = jest.fn(() => {
+      throw new Error("observer");
+    });
+    const error = Object.assign(new Error("rate limited"), {
+      status: 429,
+      headers: { "retry-after": "2", authorization: "secret" },
+      request_id: "rate-request",
+    });
+    (client as any).client = {
+      chat: {
+        completions: {
+          create: jest.fn(() => ({
+            withResponse: async () => {
+              throw error;
+            },
+          })),
+        },
+      },
+    };
+
+    await expect(
+      client.createChatCompletion({
+        ...completionOptions,
+        onResponseMetadata: observer,
+      })
+    ).rejects.toBe(error);
+    expect(observer).toHaveBeenCalledWith({
+      statusCode: 429,
+      requestId: "rate-request",
+      rateLimit: { retryAfterSeconds: 2 },
+      headers: { "retry-after": "2" },
+    });
+  });
+});

package/tests/unit/clients/responseMetadata.test.ts

@@ -0,0 +1,123 @@
+import {
+  emitResponseMetadata,
+  normalizeRateLimitMetadata,
+  normalizeResponseMetadata,
+} from "../../../src/clients/responseMetadata";
+
+describe("response metadata", () => {
+  it("normalizes and allowlists safe headers and derives a request id", () => {
+    const metadata = normalizeResponseMetadata({
+      statusCode: 429,
+      headers: {
+        "X-RateLimit-Remaining": "0",
+        "X-Request-Id": "request-123",
+        Authorization: "Bearer secret",
+        Cookie: "session=secret",
+        "X-Private-Value": "never expose",
+      },
+    });
+
+    expect(metadata).toEqual({
+      statusCode: 429,
+      requestId: "request-123",
+      rateLimit: { remaining: 0 },
+      headers: {
+        "x-ratelimit-remaining": "0",
+        "x-request-id": "request-123",
+      },
+    });
+  });
+
+  it("uses an explicit request id and retains only the first duplicate header", () => {
+    const metadata = normalizeResponseMetadata({
+      requestId: "explicit-id",
+      headers: [
+        ["Retry-After", "1"],
+        ["retry-after", "2"],
+        ["CF-Ray", "ray-id"],
+      ],
+    });
+
+    expect(metadata.requestId).toBe("explicit-id");
+    expect(metadata.headers).toEqual({
+      "retry-after": "1",
+      "cf-ray": "ray-id",
+    });
+  });
+
+  it("normalizes standard and OpenAI-compatible limits into JSON-safe values", () => {
+    const now = new Date("2026-08-23T00:00:00.000Z");
+    expect(
+      normalizeRateLimitMetadata(
+        {
+          "ratelimit-limit": "100",
+          "ratelimit-remaining": "9",
+          "ratelimit-reset": "60",
+          "retry-after": "2",
+          "x-ratelimit-limit-tokens": "2000",
+          "x-ratelimit-remaining-tokens": "100",
+          "x-ratelimit-reset-tokens": "1m30s",
+        },
+        now
+      )
+    ).toEqual({
+      limit: 100,
+      remaining: 9,
+      resetAt: "2026-08-23T00:01:00.000Z",
+      retryAfterSeconds: 2,
+      tokenLimit: 2000,
+      tokenRemaining: 100,
+      tokenResetAt: "2026-08-23T00:01:30.000Z",
+    });
+  });
+
+  it("normalizes Anthropic request and token windows", () => {
+    expect(
+      normalizeRateLimitMetadata(
+        {
+          "anthropic-ratelimit-requests-limit": "50",
+          "anthropic-ratelimit-requests-remaining": "10",
+          "anthropic-ratelimit-requests-reset": "2026-08-23T00:01:00Z",
+          "anthropic-ratelimit-tokens-limit": "40000",
+          "anthropic-ratelimit-tokens-remaining": "5000",
+          "anthropic-ratelimit-tokens-reset": "2026-08-23T00:02:00Z",
+        },
+        new Date("2026-08-23T00:00:00Z")
+      )
+    ).toEqual({
+      limit: 50,
+      remaining: 10,
+      resetAt: "2026-08-23T00:01:00.000Z",
+      tokenLimit: 40000,
+      tokenRemaining: 5000,
+      tokenResetAt: "2026-08-23T00:02:00.000Z",
+    });
+  });
+
+  it("bounds retained values and isolates observer failures", () => {
+    const value = "x".repeat(300);
+    const observer = jest.fn(() => {
+      throw new Error("telemetry failure");
+    });
+
+    expect(() =>
+      emitResponseMetadata(
+        { onResponseMetadata: observer },
+        { headers: { "x-ratelimit-reset": value } }
+      )
+    ).not.toThrow();
+    expect(observer).toHaveBeenCalledWith({
+      rateLimit: {},
+      headers: { "x-ratelimit-reset": "x".repeat(256) },
+    });
+  });
+
+  it("limits retained header count and aggregate data", () => {
+    const headers: Record<string, string> = {};
+    for (let index = 0; index < 30; index++)
+      headers[`x-ratelimit-test-${index}`] = String(index);
+    expect(
+      Object.keys(normalizeResponseMetadata({ headers }).headers)
+    ).toHaveLength(24);
+  });
+});

package/tests/unit/login.test.ts

@@ -26,7 +26,10 @@ jest.mock("../../src/auth/keyAuth", () => ({
   registerPublicKey,
 }));
 
-jest.mock("../../src/auth/keyManager", () => ({ getOrCreatePublicKey }));
+jest.mock("../../src/auth/keyManager", () => ({
+  getDefaultPrivateKeyPath: () => "/keys/default",
+  getOrCreatePublicKey,
+}));
 jest.mock("../../src/config", () => ({ getConfig, updateConfig }));
 jest.mock("../../src/utils", () => ({ ask: jest.fn() }));
 
@@ -88,6 +91,41 @@ describe("login public-key bootstrap", () => {
     );
   });
 
+  it("does not persist a temporary identity path into project configuration", async () => {
+    const temporaryIdentity = path.join(os.tmpdir(), "knowhow-login-test-key");
+    getConfig.mockResolvedValue({
+      orgId: "org-1",
+      cliIdentityPath: "/tmp/knowhow-csrf-e2e-key",
+      modelProviders: [],
+    });
+    registerPublicKey.mockResolvedValueOnce(undefined);
+
+    await expect(login(false, temporaryIdentity)).resolves.toBeUndefined();
+
+    expect(getOrCreatePublicKey).toHaveBeenCalledWith(temporaryIdentity);
+    expect(updateConfig).toHaveBeenCalledTimes(1);
+    expect(updateConfig.mock.calls[0][0]).toEqual(
+      expect.not.objectContaining({
+        cliIdentityPath: expect.any(String),
+      })
+    );
+  });
+
+  it("persists the default identity selected during browser bootstrap", async () => {
+    registerPublicKey.mockResolvedValueOnce(undefined);
+
+    await expect(login(false)).resolves.toBeUndefined();
+
+    expect(getOrCreatePublicKey).toHaveBeenCalledWith("/keys/default");
+    expect(updateConfig).toHaveBeenCalledWith(
+      expect.objectContaining({
+        orgId: "org-1",
+        cliIdentityPath: "/keys/default",
+        modelProviders: [{ provider: "knowhow" }],
+      })
+    );
+  });
+
   it("safely falls back to browser PKCE when the selected key cannot authenticate", async () => {
     hasKeyPair.mockReturnValue(true);
     getConfig.mockResolvedValue({ orgId: "org-1", modelProviders: [] });