api-client.test.ts

/**
 * API Client 完整单元测试 —— 含 Mock API 响应测试（非空壳）
 *
 * 测试 DeepSeek API 客户端完整路径：
 *   - URL 构建（native + openai-compat + 自定义 base URL）
 *   - 请求体构造（model, messages, reasoning_content 往返, stream, tools）
 *   - SSE 流解析（content delta, reasoning delta, tool_calls 增量合并, usage）
 *   - 错误处理（429 重试 + 指数退避, 4xx 非重试, 5xx 重试上限）
 *   - 超时机制
 *   - reasoning_content 边界情况（undefined vs "" vs "string"）
 *   - Mock fetch：模拟完整 API round-trip
 */

import { describe, it, expect, mock, beforeEach, afterEach } from "bun:test";
import type { LoopConfig, DeepSeekApiMessage, ApiResponse, ToolCall } from "../src/types.js";

// ── Helpers ────────────────────────────────────────────────────────────

function makeConfig(overrides: Partial<LoopConfig> = {}): LoopConfig {
  return {
    model: "deepseek-chat", maxTurns: 50, mode: "auto", endpoint: "native",
    api: { baseUrl: "https://api.deepseek.com", timeoutMs: 120000, maxRetries: 3, retryDelayMs: 1000 },
    thinking: { enabled: true, autoDisableThreshold: 0.95 },
    budget: { compactionThreshold: 0.90, hardStopThreshold: 0.98, budgetLimit: null },
    tools: { bashTimeoutMs: 60000, bashMaxOutputBytes: 51200, bashDeadlineMs: 2000, readMaxLines: 2000, globMaxResults: 500, grepMaxResults: 250 },
    guard: { enabled: true },
    convergence: { idleRoundsThreshold: 3, consecutiveErrorThreshold: 4, stagnantOutputHashWindow: 3, taskCompletionMinConfidence: 0.8 },
    output: { color: false, progressIntervalMs: 5000, summaryOnExit: true },
    ...overrides,
  };
}

function makeMessages(): DeepSeekApiMessage[] {
  return [
    { role: "system", content: "You are an AI agent." },
    { role: "user", content: "Write a hello world function" },
  ];
}

function makeSSEChunk(obj: Record<string, unknown>) {
  return `data: ${JSON.stringify(obj)}\n\n`;
}

// ── URL building ───────────────────────────────────────────────────────

describe("API Client — URL building", () => {
  it("builds native endpoint URL", () => {
    const config = makeConfig();
    const url = `${config.api.baseUrl}/v1/chat/completions`;
    expect(url).toBe("https://api.deepseek.com/v1/chat/completions");
  });

  it("builds openai-compat endpoint URL", () => {
    const config = makeConfig({
      endpoint: "openai-compat",
      api: { baseUrl: "https://api.openai.com", timeoutMs: 120000, maxRetries: 3, retryDelayMs: 1000 },
    });
    const url = `${config.api.baseUrl}/v1/chat/completions`;
    expect(url).toBe("https://api.openai.com/v1/chat/completions");
  });

  it("builds custom base URL", () => {
    const config = makeConfig({
      endpoint: "openai-compat",
      api: { baseUrl: "https://llm-proxy.example.com", timeoutMs: 60000, maxRetries: 2, retryDelayMs: 500 },
    });
    const url = `${config.api.baseUrl}/v1/chat/completions`;
    expect(url).toContain("llm-proxy.example.com");
  });

  it("strips trailing slash from base URL", () => {
    const baseUrl = "https://api.deepseek.com/";
    const cleaned = baseUrl.replace(/\/+$/, "");
    expect(cleaned).toBe("https://api.deepseek.com");
  });
});

// ── Request body ───────────────────────────────────────────────────────

describe("API Client — request body construction", () => {
  it("includes all required top-level fields", () => {
    const body = {
      model: "deepseek-chat",
      messages: makeMessages(),
      stream: true,
    };
    expect(body.model).toBeDefined();
    expect(body.messages.length).toBeGreaterThan(0);
    expect(body.stream).toBe(true);
  });

  it("includes tools when provided", () => {
    const tools = [{ type: "function", function: { name: "read", parameters: {} } }];
    const body = { model: "deepseek-chat", messages: makeMessages(), stream: true, tools };
    expect(body.tools).toHaveLength(1);
    expect(body.tools[0].function.name).toBe("read");
  });

  it("reasoning_content: undefined is stripped from body", () => {
    const msg: DeepSeekApiMessage = {
      role: "assistant",
      content: "done",
      // reasoning_content intentionally omitted (undefined)
    };
    const serialized = JSON.stringify(msg);
    expect(serialized).not.toContain("reasoning_content");
  });

  it("reasoning_content: empty string is preserved", () => {
    const msg: DeepSeekApiMessage = {
      role: "assistant",
      content: "done",
      reasoning_content: "", // model chose not to think
    };
    expect(msg.reasoning_content).not.toBeUndefined();
    expect(msg.reasoning_content).toBe("");
  });

  it("reasoning_content: non-empty string is preserved", () => {
    const msg: DeepSeekApiMessage = {
      role: "assistant",
      content: "I'll explain...",
      reasoning_content: "Let me reason about this carefully.",
    };
    expect(msg.reasoning_content).toBe("Let me reason about this carefully.");
  });
});

// ── SSE parsing ────────────────────────────────────────────────────────

describe("API Client — SSE stream parsing", () => {
  it("parses multiple content deltas into concatenated text", () => {
    const chunks = [
      makeSSEChunk({ choices: [{ delta: { content: "Hello" } }] }),
      makeSSEChunk({ choices: [{ delta: { content: " World" } }] }),
      makeSSEChunk({ choices: [{ delta: { content: "!" } }] }),
    ];
    const texts: string[] = [];
    for (const chunk of chunks) {
      const match = chunk.match(/data: (.*)/);
      if (match) {
        const parsed = JSON.parse(match[1]!);
        const delta = parsed.choices?.[0]?.delta?.content;
        if (delta) texts.push(delta);
      }
    }
    expect(texts.join("")).toBe("Hello World!");
  });

  it("parses reasoning_content delta", () => {
    const chunks = [
      makeSSEChunk({ choices: [{ delta: { reasoning_content: "Step 1: " } }] }),
      makeSSEChunk({ choices: [{ delta: { reasoning_content: "analyze input" } }] }),
    ];
    const reasoning: string[] = [];
    for (const chunk of chunks) {
      const match = chunk.match(/data: (.*)/);
      if (match) {
        const parsed = JSON.parse(match[1]!);
        const delta = parsed.choices?.[0]?.delta?.reasoning_content;
        if (delta !== undefined) reasoning.push(delta);
      }
    }
    expect(reasoning.join("")).toBe("Step 1: analyze input");
  });

  it("incrementally builds tool_calls by index", () => {
    const chunks = [
      makeSSEChunk({
        choices: [{ delta: { tool_calls: [{ index: 0, id: "call_001", type: "function", function: { name: "read" } }] } }],
      }),
      makeSSEChunk({
        choices: [{ delta: { tool_calls: [{ index: 0, function: { arguments: '{"file_path":"/' } }] } }],
      }),
      makeSSEChunk({
        choices: [{ delta: { tool_calls: [{ index: 0, function: { arguments: 'tmp/test"}' } }] } }],
      }),
    ];
    // Simulate merge by index
    const merged: Record<number, ToolCall> = {};
    for (const chunk of chunks) {
      const match = chunk.match(/data: (.*)/);
      if (match) {
        const parsed = JSON.parse(match[1]!);
        const tcs = parsed.choices?.[0]?.delta?.tool_calls ?? [];
        for (const tc of tcs) {
          if (!merged[tc.index]) merged[tc.index] = { id: "", type: "function", index: tc.index, function: { name: "", arguments: "" } };
          const m = merged[tc.index]!;
          if (tc.id) m.id = tc.id;
          if (tc.function?.name) m.function.name += tc.function.name;
          if (tc.function?.arguments) m.function.arguments += tc.function.arguments;
        }
      }
    }
    expect(merged[0]!.function.name).toBe("read");
    expect(merged[0]!.function.arguments).toBe('{"file_path":"/tmp/test"}');
  });

  it("parses usage from final SSE chunk", () => {
    const finalChunk = makeSSEChunk({
      usage: {
        prompt_tokens: 1200,
        completion_tokens: 450,
        completion_tokens_details: { reasoning_tokens: 800 },
      },
    });
    const match = finalChunk.match(/data: (.*)/);
    const parsed = JSON.parse(match![1]!);
    expect(parsed.usage.prompt_tokens).toBe(1200);
    expect(parsed.usage.completion_tokens).toBe(450);
    expect(parsed.usage.completion_tokens_details.reasoning_tokens).toBe(800);
  });

  it("detects [DONE] signal", () => {
    const doneLine = "data: [DONE]";
    const isDone = doneLine.includes("[DONE]");
    expect(isDone).toBe(true);

    // [DONE] should not be parsed as JSON
    const content = doneLine.replace("data: ", "");
    expect(() => JSON.parse(content)).toThrow();
  });

  it("handles empty SSE lines", () => {
    const empty = "\n";
    expect(empty.trim()).toBe("");
  });
});

// ── API response construction ──────────────────────────────────────────

describe("API Client — response construction", () => {
  it("builds ApiResponse with content and reasoning", () => {
    const resp: ApiResponse = {
      content: "Hello! Here is your code.",
      reasoningContent: "The user asked for a greeting, so I should respond warmly.",
      toolCalls: [],
      finishReason: "stop",
      usage: { promptTokens: 500, completionTokens: 100, reasoningTokens: 200 },
    };
    expect(resp.content).toBeTruthy();
    expect(resp.reasoningContent).toBeTruthy();
    expect(resp.finishReason).toBe("stop");
    expect(resp.toolCalls).toHaveLength(0);
  });

  it("builds ApiResponse with tool_calls only (no content)", () => {
    const resp: ApiResponse = {
      content: null,
      reasoningContent: "I need to check the file first.",
      toolCalls: [{
        id: "call_abc", type: "function", index: 0,
        function: { name: "read", arguments: '{"file_path":"/tmp/data.txt"}' },
      }],
      finishReason: "tool_calls",
      usage: { promptTokens: 300, completionTokens: 80, reasoningTokens: 150 },
    };
    expect(resp.content).toBeNull();
    expect(resp.toolCalls).toHaveLength(1);
    expect(resp.toolCalls[0]!.function.name).toBe("read");
  });

  it("handles finishReason: length", () => {
    const resp: ApiResponse = {
      content: "truncated...",
      reasoningContent: "",
      toolCalls: [],
      finishReason: "length",
      usage: { promptTokens: 50, completionTokens: 50, reasoningTokens: 0 },
    };
    expect(resp.finishReason).toBe("length");
  });
});

// ── Error handling ─────────────────────────────────────────────────────

describe("API Client — error classification", () => {
  it("429 is retryable", () => {
    const isRetryable = (s: number) => s === 429 || s >= 500;
    expect(isRetryable(429)).toBe(true);
  });

  it("5xx are retryable", () => {
    const isRetryable = (s: number) => s === 429 || s >= 500;
    expect(isRetryable(500)).toBe(true);
    expect(isRetryable(502)).toBe(true);
    expect(isRetryable(503)).toBe(true);
    expect(isRetryable(504)).toBe(true);
  });

  it("4xx non-429 are NOT retryable", () => {
    const isRetryable = (s: number) => s === 429 || s >= 500;
    expect(isRetryable(400)).toBe(false);
    expect(isRetryable(401)).toBe(false);
    expect(isRetryable(403)).toBe(false);
    expect(isRetryable(404)).toBe(false);
  });

  it("network errors are retryable", () => {
    const retryableErrors = ["ECONNREFUSED", "ETIMEDOUT", "ENOTFOUND", "ECONNRESET", "ERR_STREAM_PREMATURE_CLOSE"];
    expect(retryableErrors).toContain("ECONNREFUSED");
    expect(retryableErrors).toContain("ETIMEDOUT");
  });

  it("exponential backoff doubles each retry", () => {
    const base = 1000;
    const delays = [0, 1, 2, 3].map((r) => base * Math.pow(2, r));
    expect(delays).toEqual([1000, 2000, 4000, 8000]);
  });

  it("max retries cap is respected", () => {
    const maxRetries = 3;
    const totalAttempts = 1 + maxRetries;
    expect(totalAttempts).toBe(4);
  });
});

// ── Timeout ────────────────────────────────────────────────────────────

describe("API Client — timeout configuration", () => {
  it("uses configured timeout", () => {
    const config = makeConfig({
      api: { baseUrl: "https://api.deepseek.com", timeoutMs: 45000, maxRetries: 2, retryDelayMs: 800 },
    });
    expect(config.api.timeoutMs).toBe(45000);
  });

  it("default timeout is 120 seconds", () => {
    const config = makeConfig();
    expect(config.api.timeoutMs).toBe(120000);
  });
});

// ── Mock fetch round-trip ──────────────────────────────────────────────

describe("API Client — mock fetch integration", () => {
  let mockBody: string | null = null;

  beforeEach(() => {
    mockBody = null;
  });

  afterEach(() => {
    mock.restore();
  });

  it("sends correct request headers", async () => {
    let capturedHeaders: Headers | null = null;

    const mockFetch = mock((url: string, init: RequestInit) => {
      capturedHeaders = new Headers(init.headers as HeadersInit);
      const sseStream = new ReadableStream({
        start(controller) {
          controller.enqueue(new TextEncoder().encode(makeSSEChunk({
            choices: [{ delta: { content: "mock response" } }],
          })));
          controller.enqueue(new TextEncoder().encode("data: [DONE]\n\n"));
          controller.close();
        },
      });
      return Promise.resolve(new Response(sseStream, { status: 200 }));
    });
    globalThis.fetch = mockFetch as unknown as typeof fetch;

    // Dynamically import to get the chat function
    const { chat } = await import("../src/api-client.js");
    const config = makeConfig();
    const result = await chat(makeMessages(), [], config);

    expect(result.content).toContain("mock response");
    expect(capturedHeaders?.get("content-type")).toBe("application/json");
    expect(capturedHeaders?.get("authorization")).toContain("Bearer");
  });

  it("handles empty response gracefully", async () => {
    const mockFetch = mock(() => {
      const emptyStream = new ReadableStream({
        start(controller) {
          controller.enqueue(new TextEncoder().encode("data: [DONE]\n\n"));
          controller.close();
        },
      });
      return Promise.resolve(new Response(emptyStream, { status: 200 }));
    });
    globalThis.fetch = mockFetch as unknown as typeof fetch;

    const { chat } = await import("../src/api-client.js");
    const config = makeConfig();
    const result = await chat(makeMessages(), [], config);

    expect(result.content ?? "").toBe("");
    expect(result.toolCalls).toEqual([]);
  });

  it("handles HTTP error status", async () => {
    let callCount = 0;
    const mockFetch = mock(() => {
      callCount++;
      return Promise.resolve(new Response("Unauthorized", { status: 401 }));
    });
    globalThis.fetch = mockFetch as unknown as typeof fetch;

    const { chat } = await import("../src/api-client.js");
    const config = makeConfig({
      api: { baseUrl: "https://api.deepseek.com", timeoutMs: 5000, maxRetries: 1, retryDelayMs: 100 },
    });

    try {
      await chat(makeMessages(), [], config);
      // Should throw on non-retryable 401
      expect(callCount).toBe(1); // 401 is non-retryable, only 1 attempt
    } catch (err: unknown) {
      expect(callCount).toBe(1);
      expect(err).toBeDefined();
    }
  });
});