@ryanfw/prompt-orchestration-pipeline 1.3.2 → 1.3.4

package/src/llm/__tests__/index.test.ts

@@ -1,5 +1,8 @@
 import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
 import { EventEmitter } from "node:events";
+import { existsSync, rmSync, statSync, writeFileSync, chmodSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 
 const mockSdkPrompt = vi.fn();
 const mockSdkCreate = vi.fn();
@@ -25,6 +28,8 @@ import {
   getAvailableProviders,
   estimateTokens,
   calculateCost,
+  findModelPrice,
+  resolveUsageAvailable,
 } from "../index.ts";
 import type {
   ChatOptions,
@@ -32,7 +37,9 @@ import type {
   NormalizedUsage,
   LLMRequestStartEvent,
   LLMRequestCompleteEvent,
+  LLMRequestErrorEvent,
 } from "../../providers/types.ts";
+import { ProviderJsonParseError } from "../../providers/types.ts";
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
@@ -149,6 +156,7 @@ describe("LLM Gateway", () => {
         promptTokens: 100,
         completionTokens: 200,
         totalTokens: 300,
+        source: "reported",
       });
     });
 
@@ -177,6 +185,44 @@ describe("LLM Gateway", () => {
 
       expect(provider.chat).not.toHaveBeenCalled();
     });
+
+    it("AC-8: throwing adapter emits llm:request:error with estimated input usage, cost, and costEstimated", async () => {
+      const provider: MockProvider = {
+        chat: vi.fn().mockRejectedValue(new Error("adapter boom")),
+      };
+      registerMockProvider(provider);
+
+      const errorEvents: LLMRequestErrorEvent[] = [];
+      getLLMEvents().on("llm:request:error", (e) => errorEvents.push(e));
+
+      const messages = [
+        { role: "system" as const, content: "you are helpful" },
+        { role: "user" as const, content: "Hello world from a failing prompt" },
+      ];
+
+      await expect(
+        chat({ provider: "mock", model: "ac8-error-model", messages }),
+      ).rejects.toThrow("adapter boom");
+
+      expect(errorEvents).toHaveLength(1);
+      const evt = errorEvents[0]!;
+      const expectedPrompt = estimateTokens(
+        messages.map((m) => m.content).join(" "),
+      );
+      expect(evt.promptTokens).toBe(expectedPrompt);
+      expect(evt.completionTokens).toBe(0);
+      expect(evt.totalTokens).toBe(expectedPrompt);
+      expect(evt.usageSource).toBe("estimated");
+      expect(evt.costEstimated).toBe(true);
+      expect(evt.cost).toBe(
+        calculateCost("mock", "ac8-error-model", {
+          promptTokens: expectedPrompt,
+          completionTokens: 0,
+          totalTokens: expectedPrompt,
+          source: "estimated",
+        }),
+      );
+    });
   });
 
   // ── Telemetry Events ───────────────────────────────────────────────────
@@ -248,6 +294,229 @@ describe("LLM Gateway", () => {
     });
   });
 
+  // ── normalizeUsage classification (AC-2, AC-3) ─────────────────────────
+
+  describe("normalizeUsage classification", () => {
+    async function runChatWithUsage(usage: unknown): Promise<NormalizedUsage> {
+      const provider: MockProvider = {
+        chat: vi.fn().mockResolvedValue({
+          content: "response-text",
+          usage,
+        }),
+      };
+      registerMockProvider(provider);
+      const result = await chat({
+        provider: "mock",
+        messages: [{ role: "user", content: "some input text" }],
+      });
+      return result.usage;
+    }
+
+    it("classifies full reported usage as reported", async () => {
+      const usage = await runChatWithUsage({
+        prompt_tokens: 100,
+        completion_tokens: 200,
+        total_tokens: 300,
+      });
+      expect(usage).toEqual({
+        promptTokens: 100,
+        completionTokens: 200,
+        totalTokens: 300,
+        source: "reported",
+      });
+    });
+
+    it("classifies all-zero usage as zero", async () => {
+      const usage = await runChatWithUsage({
+        prompt_tokens: 0,
+        completion_tokens: 0,
+        total_tokens: 0,
+      });
+      expect(usage).toEqual({
+        promptTokens: 0,
+        completionTokens: 0,
+        totalTokens: 0,
+        source: "zero",
+      });
+    });
+
+    it("classifies absent usage from a capable provider as estimated", async () => {
+      const usage = await runChatWithUsage(undefined);
+      expect(usage.source).toBe("estimated");
+      expect(usage.promptTokens).toBe(estimateTokens("some input text"));
+      expect(usage.completionTokens).toBe(estimateTokens("response-text"));
+      expect(usage.totalTokens).toBe(
+        estimateTokens("some input text") + estimateTokens("response-text"),
+      );
+    });
+
+    it("classifies absent usage from an incapable provider as unavailable", async () => {
+      vi.spyOn(Bun, "spawn").mockReturnValue(
+        createOpenCodeProc([
+          '{"type":"text","part":{"text":"hello from opencode"}}\n',
+        ]),
+      );
+      const result = await chat({
+        provider: "opencode",
+        model: "anthropic/claude-sonnet-4-5",
+        messages: [{ role: "user", content: "Hello" }],
+        responseFormat: "text",
+      });
+      expect(result.usage.source).toBe("unavailable");
+      expect(result.usage.promptTokens).toBe(estimateTokens("Hello"));
+      expect(result.usage.completionTokens).toBe(
+        estimateTokens("hello from opencode"),
+      );
+    });
+
+    it("classifies prompt-only usage as estimated and estimates the completion side", async () => {
+      const usage = await runChatWithUsage({ prompt_tokens: 50 });
+      expect(usage.source).toBe("estimated");
+      expect(usage.promptTokens).toBe(50);
+      expect(usage.completionTokens).toBe(estimateTokens("response-text"));
+      expect(usage.totalTokens).toBe(50 + estimateTokens("response-text"));
+    });
+
+    it("classifies prompt plus total usage as estimated while preserving the reported total", async () => {
+      const usage = await runChatWithUsage({ prompt_tokens: 10, total_tokens: 30 });
+      expect(usage).toEqual({
+        promptTokens: 10,
+        completionTokens: 20,
+        totalTokens: 30,
+        source: "estimated",
+      });
+    });
+
+    it("classifies completion-only usage as estimated and estimates the prompt side", async () => {
+      const usage = await runChatWithUsage({ completion_tokens: 60 });
+      expect(usage.source).toBe("estimated");
+      expect(usage.promptTokens).toBe(estimateTokens("some input text"));
+      expect(usage.completionTokens).toBe(60);
+      expect(usage.totalTokens).toBe(estimateTokens("some input text") + 60);
+    });
+
+    it("classifies completion plus total usage as estimated while preserving the reported total", async () => {
+      const usage = await runChatWithUsage({ completion_tokens: 12, total_tokens: 30 });
+      expect(usage).toEqual({
+        promptTokens: 18,
+        completionTokens: 12,
+        totalTokens: 30,
+        source: "estimated",
+      });
+    });
+
+    it("classifies total-only usage as estimated and splits prompt/completion by 4-char estimate, summing to total", async () => {
+      const total = 100;
+      const usage = await runChatWithUsage({ total_tokens: total });
+      expect(usage.source).toBe("estimated");
+      expect(usage.totalTokens).toBe(total);
+      expect(usage.promptTokens + usage.completionTokens).toBe(total);
+      const promptEst = estimateTokens("some input text");
+      const completionEst = estimateTokens("response-text");
+      const expectedPrompt = Math.round(
+        (promptEst / (promptEst + completionEst)) * total,
+      );
+      expect(usage.promptTokens).toBe(expectedPrompt);
+      expect(usage.completionTokens).toBe(total - expectedPrompt);
+    });
+  });
+
+  // ── resolveUsageAvailable (AC-4) ───────────────────────────────────────
+
+  describe("resolveUsageAvailable()", () => {
+    let originalEnv: Record<string, string | undefined>;
+
+    beforeEach(() => {
+      originalEnv = { ...process.env };
+      delete process.env.PO_OPENCODE_BASE_URL;
+      delete process.env.OPENCODE_BASE_URL;
+    });
+
+    afterEach(() => {
+      for (const key of ["PO_OPENCODE_BASE_URL", "OPENCODE_BASE_URL"]) {
+        if (!(key in originalEnv)) delete process.env[key];
+        else process.env[key] = originalEnv[key];
+      }
+    });
+
+    it("returns false for claudecode", () => {
+      expect(
+        resolveUsageAvailable("claudecode", {
+          provider: "claudecode",
+          messages: baseMessages,
+        }),
+      ).toBe(false);
+    });
+
+    it("returns false for opencode in cli mode", () => {
+      expect(
+        resolveUsageAvailable("opencode", {
+          provider: "opencode",
+          messages: baseMessages,
+          opencode: { mode: "cli" },
+        }),
+      ).toBe(false);
+    });
+
+    it("returns true for opencode in sdk mode", () => {
+      expect(
+        resolveUsageAvailable("opencode", {
+          provider: "opencode",
+          messages: baseMessages,
+          opencode: { mode: "sdk", baseUrl: "http://localhost:3000" },
+        }),
+      ).toBe(true);
+    });
+
+    it("returns true for opencode with mode omitted and PO_OPENCODE_BASE_URL set", () => {
+      process.env.PO_OPENCODE_BASE_URL = "http://localhost:3000";
+      expect(
+        resolveUsageAvailable("opencode", {
+          provider: "opencode",
+          messages: baseMessages,
+        }),
+      ).toBe(true);
+    });
+
+    it("returns false for opencode with mode omitted and no base URL", () => {
+      expect(
+        resolveUsageAvailable("opencode", {
+          provider: "opencode",
+          messages: baseMessages,
+        }),
+      ).toBe(false);
+    });
+
+    it("returns true for usage-capable providers (mock)", () => {
+      expect(
+        resolveUsageAvailable("mock", {
+          provider: "mock",
+          messages: baseMessages,
+        }),
+      ).toBe(true);
+    });
+  });
+
+  // ── usageAvailable source guard (AC-4, invariant I-1) ──────────────────
+
+  describe("usageAvailable single-source guard", () => {
+    it("src/providers/*.ts (adapter sources, not tests) does not reference usageAvailable (the gateway helper owns it)", async () => {
+      const { Glob } = await import("bun");
+      const files: string[] = [];
+      for await (const path of new Glob("src/providers/*.ts").scan()) {
+        files.push(path);
+      }
+      const offenders: string[] = [];
+      for (const path of files) {
+        const text = await Bun.file(path).text();
+        if (text.includes("usageAvailable")) offenders.push(path);
+      }
+      // types.ts declares the field on AdapterResponse; that is the contract,
+      // not an adapter setting it. It is the only allowed file.
+      expect(offenders).toEqual(["src/providers/types.ts"]);
+    });
+  });
+
   // ── calculateCost ──────────────────────────────────────────────────────
 
   describe("calculateCost()", () => {
@@ -257,6 +526,7 @@ describe("LLM Gateway", () => {
         promptTokens: 1_000_000,
         completionTokens: 1_000_000,
         totalTokens: 2_000_000,
+        source: "reported",
       };
       const cost = calculateCost("anthropic", "claude-sonnet-4-6", usage);
       // inCost: (1000000/1000000) * 3 = $3.00
@@ -269,6 +539,7 @@ describe("LLM Gateway", () => {
         promptTokens: 1000,
         completionTokens: 1000,
         totalTokens: 2000,
+        source: "reported",
       };
       const cost = calculateCost("unknown", "unknown-model", usage);
       expect(cost).toBe(0);
@@ -280,12 +551,187 @@ describe("LLM Gateway", () => {
         promptTokens: 1000,
         completionTokens: 1000,
         totalTokens: 2000,
+        source: "reported",
       };
       const cost = calculateCost("claudecode", "sonnet", usage);
       expect(cost).toBe(0);
     });
   });
 
+  // ── findModelPrice ─────────────────────────────────────────────────────
+
+  describe("findModelPrice()", () => {
+    it("returns the price for a known model looked up by alias", () => {
+      // anthropic:sonnet-4-6 → tokenCostInPerMillion: 3, tokenCostOutPerMillion: 15
+      const price = findModelPrice("anthropic", "claude-sonnet-4-6");
+      expect(price).toEqual({
+        tokenCostInPerMillion: 3,
+        tokenCostOutPerMillion: 15,
+      });
+    });
+
+    it("returns the zero-cost entry for claudecode provider mapping", () => {
+      // claude-code:sonnet — zero-cost subscription
+      const price = findModelPrice("claudecode", "sonnet");
+      expect(price).toEqual({
+        tokenCostInPerMillion: 0,
+        tokenCostOutPerMillion: 0,
+      });
+    });
+
+    it("returns the price for zhipu provider mapping", () => {
+      // zhipu maps to zai; zai:glm-5 → tokenCostInPerMillion: 1, tokenCostOutPerMillion: 3.2
+      const price = findModelPrice("zhipu", "glm-5");
+      expect(price).toEqual({
+        tokenCostInPerMillion: 1,
+        tokenCostOutPerMillion: 3.2,
+      });
+    });
+
+    it("returns null for an unknown provider+model", () => {
+      const price = findModelPrice("unknown", "nope");
+      expect(price).toBeNull();
+    });
+  });
+
+  // ── cost classification (AC-5, AC-6, AC-7) ─────────────────────────────
+
+  describe("cost classification", () => {
+    it("AC-5: known model with reported usage → costEstimated:false and a computed cost", async () => {
+      // Use opencode SDK mode with model "default" (alias opencode:default is in
+      // MODEL_CONFIG). Mock the SDK to report measured tokens.
+      process.env["PO_OPENCODE_BASE_URL"] = "http://localhost:3000";
+      mockCreateClient.mockReturnValue({
+        session: {
+          create: mockSdkCreate,
+          prompt: mockSdkPrompt,
+          delete: mockSdkDelete,
+        },
+      });
+      mockSdkCreate.mockResolvedValue({
+        data: { id: "sess-ac5" },
+        error: undefined,
+      });
+      mockSdkPrompt.mockResolvedValue({
+        data: {
+          info: {
+            id: "msg-ac5",
+            sessionID: "sess-ac5",
+            role: "assistant" as const,
+            modelID: "default",
+            providerID: "opencode",
+            agent: "build",
+            cost: 0,
+            tokens: {
+              input: 150,
+              output: 80,
+              total: 230,
+              reasoning: 0,
+              cache: { read: 0, write: 0 },
+            },
+          },
+          parts: [{ type: "text" as const, text: "sdk measured response" }],
+        },
+        error: undefined,
+      });
+      mockSdkDelete.mockResolvedValue({ data: undefined, error: undefined });
+
+      const completeEvents: LLMRequestCompleteEvent[] = [];
+      getLLMEvents().on("llm:request:complete", (e) =>
+        completeEvents.push(e),
+      );
+
+      try {
+        await chat({
+          provider: "opencode",
+          model: "default",
+          messages: baseMessages,
+          responseFormat: "text",
+          opencode: { mode: "sdk", baseUrl: "http://localhost:3000" },
+        });
+
+        expect(completeEvents).toHaveLength(1);
+        const evt = completeEvents[0]!;
+        expect(evt.usageSource).toBe("reported");
+        expect(evt.costEstimated).toBe(false);
+        // opencode:default is a zero-cost entry; computed cost is 0 from a known price.
+        expect(evt.cost).toBe(0);
+      } finally {
+        delete process.env["PO_OPENCODE_BASE_URL"];
+        mockCreateClient.mockClear();
+        mockSdkCreate.mockClear();
+        mockSdkPrompt.mockClear();
+        mockSdkDelete.mockClear();
+      }
+    });
+
+    it("AC-6: unknown model → non-negative cost, costEstimated:true, and exactly one warning per alias", async () => {
+      const provider = makeMockProvider({
+        content: "ok",
+        usage: { prompt_tokens: 10, completion_tokens: 20, total_tokens: 30 },
+      });
+      registerMockProvider(provider);
+
+      const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+      const completeEvents: LLMRequestCompleteEvent[] = [];
+      getLLMEvents().on("llm:request:complete", (e) =>
+        completeEvents.push(e),
+      );
+
+      try {
+        await chat({
+          provider: "mock",
+          model: "ac6-unknown-model",
+          messages: baseMessages,
+        });
+        await chat({
+          provider: "mock",
+          model: "ac6-unknown-model",
+          messages: baseMessages,
+        });
+
+        expect(completeEvents).toHaveLength(2);
+        for (const evt of completeEvents) {
+          expect(evt.costEstimated).toBe(true);
+          expect(evt.cost).toBeGreaterThanOrEqual(0);
+        }
+        const aliasWarnings = warnSpy.mock.calls.filter((args) =>
+          String(args[0]).includes("mock:ac6-unknown-model"),
+        );
+        expect(aliasWarnings).toHaveLength(1);
+      } finally {
+        warnSpy.mockRestore();
+      }
+    });
+
+    it("AC-7: known model with non-reported source → costEstimated:true", async () => {
+      // opencode CLI mode → usageAvailable:false → absent usage → source "unavailable".
+      // Model "default" has a known price; the non-reported source forces costEstimated:true.
+      vi.spyOn(Bun, "spawn").mockReturnValue(
+        createOpenCodeProc([
+          '{"type":"text","part":{"text":"hello from opencode"}}\n',
+        ]),
+      );
+
+      const completeEvents: LLMRequestCompleteEvent[] = [];
+      getLLMEvents().on("llm:request:complete", (e) =>
+        completeEvents.push(e),
+      );
+
+      await chat({
+        provider: "opencode",
+        model: "default",
+        messages: baseMessages,
+        responseFormat: "text",
+      });
+
+      expect(completeEvents).toHaveLength(1);
+      const evt = completeEvents[0]!;
+      expect(evt.usageSource).toBe("unavailable");
+      expect(evt.costEstimated).toBe(true);
+    });
+  });
+
   // ── createChain ────────────────────────────────────────────────────────
 
   describe("createChain()", () => {
@@ -565,64 +1011,210 @@ describe("LLM Gateway", () => {
     });
   });
 
-  // ── JSON Format Inference ──────────────────────────────────────────────
+  // ── JSON Format Inference (AC-13) ─────────────────────────────────────
 
   describe("JSON format inference", () => {
-    it("infers json_object when first message contains 'json' for supported providers", async () => {
+    it("AC-13: a json-bearing message with no responseFormat passes through without enabling JSON mode", async () => {
       const provider = makeMockProvider();
       registerMockProvider(provider);
 
       await chat({
         provider: "mock",
-        messages: [{ role: "user", content: "Return JSON response" }],
-        // no responseFormat set
+        messages: [{ role: "user", content: "Return a JSON object please" }],
       });
 
-      // Mock provider does not do JSON inference — verify with a supported provider by inspecting
-      // We verify the inference logic via OpenAI/DeepSeek/Gemini/Moonshot targets
+      const callArgs = (provider.chat as ReturnType<typeof vi.fn>).mock.calls[0]![0] as ChatOptions;
+      expect(callArgs.responseFormat).toBeUndefined();
     });
+  });
 
-    it("does not infer for providers not in the inference list (anthropic)", async () => {
-      // We can test that mock (not in inference set) doesn't infer
-      const provider = makeMockProvider();
+  // ── JSON Repair (AC-15) ───────────────────────────────────────────────
+
+  describe("JSON repair", () => {
+    it("AC-15: unparseable-then-valid triggers exactly one repair and emits counted repair usage", async () => {
+      const provider: MockProvider = {
+        chat: vi.fn()
+          .mockRejectedValueOnce(
+            new ProviderJsonParseError(
+              "mock",
+              "repair-valid",
+              "{bad",
+              undefined,
+              {
+                text: "{bad",
+                usage: { prompt_tokens: 3, completion_tokens: 4, total_tokens: 7 },
+              },
+            ),
+          )
+          .mockResolvedValueOnce({
+            content: { ok: true },
+            usage: { prompt_tokens: 5, completion_tokens: 7, total_tokens: 12 },
+          }),
+      };
+      registerMockProvider(provider);
+
+      const completeEvents: LLMRequestCompleteEvent[] = [];
+      getLLMEvents().on("llm:request:complete", (e) => completeEvents.push(e));
+
+      const result = await chat({
+        provider: "mock",
+        model: "repair-valid",
+        messages: baseMessages,
+        responseFormat: "json",
+      });
+
+      expect(result.content).toEqual({ ok: true });
+      expect(provider.chat).toHaveBeenCalledTimes(2);
+      expect(completeEvents).toHaveLength(1);
+      expect(completeEvents[0]!.promptTokens).toBe(8);
+      expect(completeEvents[0]!.completionTokens).toBe(11);
+      expect(completeEvents[0]!.totalTokens).toBe(19);
+      expect(completeEvents[0]!.usageSource).toBe("reported");
+      expect(result.usage).toEqual({
+        promptTokens: 8,
+        completionTokens: 11,
+        totalTokens: 19,
+        source: "reported",
+      });
+    });
+
+    it("AC-15: always unparseable triggers exactly one repair then throws ProviderJsonParseError", async () => {
+      const provider: MockProvider = {
+        chat: vi.fn()
+          .mockRejectedValueOnce(
+            new ProviderJsonParseError(
+              "mock",
+              "repair-fail",
+              "{bad",
+              undefined,
+              {
+                text: "{bad",
+                usage: { prompt_tokens: 2, completion_tokens: 3, total_tokens: 5 },
+              },
+            ),
+          )
+          .mockRejectedValueOnce(
+            new ProviderJsonParseError(
+              "mock",
+              "repair-fail",
+              "{still bad",
+              undefined,
+              {
+                text: "{still bad",
+                usage: { prompt_tokens: 7, completion_tokens: 11, total_tokens: 18 },
+              },
+            ),
+          ),
+      };
+      registerMockProvider(provider);
+
+      const errorEvents: LLMRequestErrorEvent[] = [];
+      getLLMEvents().on("llm:request:error", (e) => errorEvents.push(e));
+
+      await expect(
+        chat({
+          provider: "mock",
+          model: "repair-fail",
+          messages: baseMessages,
+          responseFormat: "json",
+        }),
+      ).rejects.toBeInstanceOf(ProviderJsonParseError);
+
+      expect(provider.chat).toHaveBeenCalledTimes(2);
+      expect(errorEvents).toHaveLength(1);
+      expect(errorEvents[0]!.promptTokens).toBe(9);
+      expect(errorEvents[0]!.completionTokens).toBe(14);
+      expect(errorEvents[0]!.totalTokens).toBe(23);
+      expect(errorEvents[0]!.usageSource).toBe("reported");
+    });
+
+    it("AC-15: fed-back sample is bounded to 2,000 characters", async () => {
+      const longSample = "a".repeat(5000);
+      const provider: MockProvider = {
+        chat: vi.fn()
+          .mockRejectedValueOnce(
+            new ProviderJsonParseError("mock", "repair-bound", longSample),
+          )
+          .mockResolvedValueOnce({ content: { ok: true } }),
+      };
       registerMockProvider(provider);
 
       await chat({
         provider: "mock",
-        messages: [{ role: "user", content: "Return JSON" }],
+        model: "repair-bound",
+        messages: baseMessages,
+        responseFormat: "json",
       });
 
-      // Check that the options passed to mock provider do NOT have responseFormat set
-      const callArgs = (provider.chat as ReturnType<typeof vi.fn>).mock.calls[0]![0] as ChatOptions;
-      expect(callArgs.responseFormat).toBeUndefined();
+      const secondCall = (provider.chat as ReturnType<typeof vi.fn>).mock.calls[1]![0] as ChatOptions;
+      const repairMessage = secondCall.messages.at(-1)!;
+      expect(repairMessage.role).toBe("user");
+      expect(repairMessage.content).toContain("a".repeat(2000));
+      expect(repairMessage.content).not.toContain("a".repeat(2001));
     });
 
-    it("infers json_object for openai when messages mention json", async () => {
-      // We can't easily test openai without mocking fetch, but we can verify
-      // inference logic indirectly by checking mock receives correct options
-      // when we use a test that goes through the inference path
+    it("AC-15: does not repair when responseFormat is absent (invariant I-3)", async () => {
       const provider: MockProvider = {
-        chat: vi.fn().mockImplementation((opts: ChatOptions) => {
-          // Capture the responseFormat that was inferred
-          expect(opts.responseFormat).toBe("json_object");
-          return Promise.resolve({
-            content: { ok: true },
-            usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 },
-          });
+        chat: vi.fn().mockRejectedValue(
+          new ProviderJsonParseError("mock", "no-repair", "{bad"),
+        ),
+      };
+      registerMockProvider(provider);
+
+      await expect(
+        chat({
+          provider: "mock",
+          model: "no-repair",
+          messages: baseMessages,
         }),
+      ).rejects.toBeInstanceOf(ProviderJsonParseError);
+
+      expect(provider.chat).toHaveBeenCalledTimes(1);
+    });
+
+    it("AC-15: does not repair when responseFormat is non-JSON (invariant I-3)", async () => {
+      const provider: MockProvider = {
+        chat: vi.fn().mockRejectedValue(
+          new ProviderJsonParseError("mock", "text-no-repair", "{bad"),
+        ),
+      };
+      registerMockProvider(provider);
+
+      await expect(
+        chat({
+          provider: "mock",
+          model: "text-no-repair",
+          messages: baseMessages,
+          responseFormat: "text",
+        }),
+      ).rejects.toBeInstanceOf(ProviderJsonParseError);
+
+      expect(provider.chat).toHaveBeenCalledTimes(1);
+    });
+
+    it("AC-15: repair re-ask reuses the parent requestTimeoutMs (invariant I-4)", async () => {
+      const provider: MockProvider = {
+        chat: vi.fn()
+          .mockRejectedValueOnce(
+            new ProviderJsonParseError("mock", "repair-timeout", "{bad"),
+          )
+          .mockResolvedValueOnce({ content: { ok: true } }),
       };
       registerMockProvider(provider);
 
-      // Simulate by calling with mock (which is NOT in inference set)
-      // Instead, test the inference logic by calling chat with openai —
-      // but that would require mocking fetch. Let's verify via a unit check.
-      // The actual inference happens in chat() before calling the adapter.
-      // We'll test by checking that for openai provider, responseFormat gets inferred.
-      // Since openai adapter will throw without a real API key, let's just verify the mock flow.
+      await chat({
+        provider: "mock",
+        model: "repair-timeout",
+        messages: baseMessages,
+        responseFormat: "json",
+        requestTimeoutMs: 42_000,
+      });
 
-      // Test: when provider is in JSON_INFER_PROVIDERS and messages contain "json"
-      // We can observe this because the options passed down should have responseFormat set.
-      // For now, we test this indirectly through the mock by patching it to intercept.
+      const calls = (provider.chat as ReturnType<typeof vi.fn>).mock.calls;
+      const firstTimeout = (calls[0]![0] as ChatOptions).requestTimeoutMs;
+      const secondTimeout = (calls[1]![0] as ChatOptions).requestTimeoutMs;
+      expect(firstTimeout).toBe(42_000);
+      expect(secondTimeout).toBe(42_000);
     });
   });
 
@@ -744,6 +1336,7 @@ describe("LLM Gateway", () => {
         completionTokens: estimateTokens("hello from opencode"),
         totalTokens:
           estimateTokens("Hello") + estimateTokens("hello from opencode"),
+        source: "unavailable",
       });
       expect(completeEvents).toHaveLength(1);
       expect(completeEvents[0]!.provider).toBe("opencode");
@@ -847,6 +1440,7 @@ describe("LLM Gateway", () => {
         promptTokens: 150,
         completionTokens: 80,
         totalTokens: 230,
+        source: "reported",
       });
       expect(completeEvents).toHaveLength(1);
       expect(completeEvents[0]!.promptTokens).toBe(150);
@@ -855,4 +1449,61 @@ describe("LLM Gateway", () => {
       expect(completeEvents[0]!.provider).toBe("opencode");
     });
   });
+
+  // ── LLM_DEBUG sink (AC-7, AC-8, AC-9) ────────────────────────────────
+
+  describe("LLM_DEBUG sink", () => {
+    const path = join(tmpdir(), `pop-llm-debug-${process.pid}.log`);
+    let originalLlmDebug: string | undefined;
+
+    beforeEach(() => {
+      originalLlmDebug = process.env["LLM_DEBUG"];
+      rmSync(path, { force: true });
+    });
+
+    afterEach(() => {
+      if (originalLlmDebug === undefined) {
+        delete process.env["LLM_DEBUG"];
+      } else {
+        process.env["LLM_DEBUG"] = originalLlmDebug;
+      }
+      rmSync(path, { force: true });
+      rmSync("/tmp/messages.log", { force: true });
+    });
+
+    it("writes debug entry to a per-process tmpdir file when LLM_DEBUG is set", async () => {
+      process.env["LLM_DEBUG"] = "1";
+      rmSync(path, { force: true });
+      rmSync("/tmp/messages.log", { force: true });
+      registerMockProvider(makeMockProvider());
+
+      await chat({ provider: "mock", model: "test-model", messages: baseMessages });
+
+      expect(existsSync(path)).toBe(true);
+      expect(existsSync("/tmp/messages.log")).toBe(false);
+    });
+
+    it("repairs an existing broader-permission debug file to 0600", async () => {
+      process.env["LLM_DEBUG"] = "1";
+      rmSync(path, { force: true });
+      writeFileSync(path, "stale\n", { mode: 0o644 });
+      chmodSync(path, 0o644);
+      registerMockProvider(makeMockProvider());
+
+      await chat({ provider: "mock", model: "test-model", messages: baseMessages });
+
+      const st = statSync(path);
+      expect(st.mode & 0o777).toBe(0o600);
+    });
+
+    it("does not write a debug file when LLM_DEBUG is unset", async () => {
+      delete process.env["LLM_DEBUG"];
+      rmSync(path, { force: true });
+      registerMockProvider(makeMockProvider());
+
+      await chat({ provider: "mock", model: "test-model", messages: baseMessages });
+
+      expect(existsSync(path)).toBe(false);
+    });
+  });
 });