@tyvm/knowhow 0.0.156 → 0.0.158

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

@@ -0,0 +1,55 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import {
+  getJwtFileName,
+  loadJwtFromDisk,
+  storeJwtForApi,
+} from "../../../src/auth/jwtStore";
+
+describe("environment-specific JWT storage", () => {
+  const originalCwd = process.cwd();
+  let workDir: string;
+
+  beforeEach(() => {
+    workDir = fs.mkdtempSync(path.join(os.tmpdir(), "knowhow-jwt-store-"));
+    process.chdir(workDir);
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+    fs.rmSync(workDir, { recursive: true, force: true });
+  });
+
+  it("uses readable names for production, development, and local APIs", () => {
+    expect(getJwtFileName("https://api.knowhow.tyvm.ai")).toBe(".jwt");
+    expect(getJwtFileName("https://api.dev.knowhow.tyvm.ai")).toBe(".jwt.dev");
+    expect(getJwtFileName("http://localhost:4000")).toBe(".jwt.local");
+  });
+
+  it("keeps tokens for each API environment independent", () => {
+    storeJwtForApi("prod-token", "https://api.knowhow.tyvm.ai");
+    storeJwtForApi("dev-token", "https://api.dev.knowhow.tyvm.ai");
+    storeJwtForApi("local-token", "http://localhost:4000");
+
+    expect(loadJwtFromDisk("https://api.knowhow.tyvm.ai")).toBe("prod-token");
+    expect(loadJwtFromDisk("https://api.dev.knowhow.tyvm.ai")).toBe("dev-token");
+    expect(loadJwtFromDisk("http://localhost:4000")).toBe("local-token");
+    expect(fs.statSync(path.join(workDir, ".knowhow", ".jwt.dev")).mode & 0o777).toBe(0o600);
+  });
+
+  it("does not send the legacy production token to another environment", () => {
+    const configDir = path.join(workDir, ".knowhow");
+    fs.mkdirSync(configDir, { recursive: true });
+    fs.writeFileSync(path.join(configDir, ".jwt"), "production-token");
+
+    expect(loadJwtFromDisk("https://api.dev.knowhow.tyvm.ai")).toBe("");
+    expect(loadJwtFromDisk("https://api.knowhow.tyvm.ai")).toBe("production-token");
+  });
+
+  it("uses a host-specific file for additional Knowhow instances", () => {
+    expect(getJwtFileName("https://api.staging.example.com:8443")).toBe(
+      ".jwt.api.staging.example.com-8443"
+    );
+  });
+});

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

@@ -31,6 +31,7 @@ describe("registerIdentity", () => {
     workDir = fs.mkdtempSync(path.join(os.tmpdir(), "knowhow-register-identity-"));
     fs.mkdirSync(path.join(workDir, ".knowhow"), { recursive: true });
     fs.writeFileSync(path.join(workDir, ".knowhow", ".jwt"), sourceJwt);
+    fs.writeFileSync(path.join(workDir, ".knowhow", ".jwt.api.example"), sourceJwt);
     process.chdir(workDir);
     getOrCreatePublicKey.mockReturnValue({
       publicKeyBase64,
@@ -53,11 +54,16 @@ describe("registerIdentity", () => {
     await registerIdentity({ apiUrl: "https://api.example" });
     expect(registerPublicKey).toHaveBeenCalledWith(sourceJwt, publicKeyBase64, "https://api.example");
     expect(exchangePublicKeyJwt).toHaveBeenCalledWith("org-test", "https://api.example", undefined);
-    expect(storeJwt).toHaveBeenCalledWith("identity.jwt.token");
+    expect(storeJwt).toHaveBeenCalledWith("identity.jwt.token", "https://api.example");
     expect(updateConfig).toHaveBeenCalledWith(expect.objectContaining({
-      orgId: "org-test",
       modelProviders: [{ provider: "knowhow" }],
       cliIdentityPath: expect.stringContaining("id_ed25519"),
+      remotes: {
+        origin: expect.objectContaining({
+          apiUrl: "https://api.example",
+          orgId: "org-test",
+        }),
+      },
     }));
   });
 

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);
+  });
+});