Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

20.5 KB
Raw Blame
import { afterEach, describe, expect, test } from "bun:test";
import type { Context } from "hono";
import type { ProviderTransport } from "../providers/transport/types.js";
import { ComposedHandler } from "./composed-handler.js";

/**
 * Integration tests for the error-surfacing WIRING in ComposedHandler.handle().
 *
 * The unit tests in shared/anthropic-error.test.ts prove the helper functions
 * (isTerminalError / buildSurfacedErrorMessage / extractProviderMessage) in
 * isolation. These tests prove the handler actually CALLS them on the upstream
 * error path: terminal errors must be remapped to a surfaced HTTP 400 (so Claude
 * Code stops its silent retry loop and shows the real reason), while transient
 * errors must keep their retryable status untouched (so legitimate retries still
 * happen). Without these, the user-visible behavior — the whole point of the
 * change — is unverified.
 */

const realFetch = globalThis.fetch;
afterEach(() => {
  globalThis.fetch = realFetch;
});

/** Fake transport that returns a fixed upstream Response from a stubbed fetch. */
function makeTransport(): ProviderTransport {
  return {
    name: "sakana",
    displayName: "Sakana Fugu",
    streamFormat: "openai-sse",
    getEndpoint: () => "http://localhost/v1/chat/completions",
    getHeaders: async () => ({}),
    // NOTE: deliberately NO forceRefreshAuth — keeps even a 401 on the generic
    // error branch (the path under test) instead of the OAuth-retry branch.
  } as unknown as ProviderTransport;
}

function makeTransportWithRefresh(
  onRefresh: () => void | Promise<void>,
  getHeaders: () => Promise<Record<string, string>> = async () => ({})
): ProviderTransport {
  return {
    ...makeTransport(),
    getHeaders,
    forceRefreshAuth: async () => {
      await onRefresh();
    },
  };
}

/** Stub global fetch to return one canned upstream error response. */
function stubUpstream(status: number, body: unknown) {
  const text = typeof body === "string" ? body : JSON.stringify(body);
  globalThis.fetch = (async () =>
    new Response(text, {
      status,
      headers: { "Content-Type": "application/json" },
    })) as unknown as typeof fetch;
}

interface StubbedUpstreamResponse {
  status: number;
  body: unknown;
  headers?: Record<string, string>;
}

interface SequencedFetchCall {
  input: string | URL | Request;
  init?: RequestInit;
}

/** Stub global fetch with one response per call and retain each request for assertions. */
function stubUpstreamSequence(...responses: StubbedUpstreamResponse[]): SequencedFetchCall[] {
  const calls: SequencedFetchCall[] = [];
  globalThis.fetch = (async (input: string | URL | Request, init?: RequestInit) => {
    const response = responses[calls.length];
    calls.push({ input, init });
    if (!response) {
      throw new Error(`Unexpected fetch call ${calls.length}`);
    }

    const text = typeof response.body === "string" ? response.body : JSON.stringify(response.body);
    return new Response(text, {
      status: response.status,
      headers: { "Content-Type": "application/json", ...response.headers },
    });
  }) as unknown as typeof fetch;
  return calls;
}

/** Stub global fetch to throw before any upstream response is received. */
function stubUpstreamThrow(error: unknown) {
  globalThis.fetch = (async () => {
    throw error;
  }) as unknown as typeof fetch;
}

interface CapturedErrorBody {
  type?: string;
  error?: {
    type?: string;
    message?: string;
    upstream_status?: number;
  };
}

interface CapturedResponse {
  body?: CapturedErrorBody;
  status?: number;
}

/** Minimal Hono Context capturing what c.json() was called with. */
function makeContext(): { c: Context; captured: CapturedResponse } {
  const captured: CapturedResponse = {};
  const c = {
    // Opt out of the Tier-1 retry ladder. These tests assert how an error is
    // SURFACED, not whether it is retried, so they take the same escape hatch
    // `probe-live.ts:157` uses — the header read at `composed-handler.ts:441`.
    // Without it a provoked connect failure retries for the full deadline and
    // the assertions time out rather than failing.
    req: {
      header: (name?: string) =>
        name === undefined ? {} : name === "x-claudish-no-recovery" ? "1" : undefined,
    },
    header: () => {},
    body: (body: BodyInit | null, init?: ResponseInit) => new Response(body, init),
    json: (body: unknown, status?: number) => {
      captured.body = body as CapturedErrorBody;
      captured.status = status;
      return new Response(JSON.stringify(body), { status: status ?? 200 });
    },
  } as unknown as Context;
  return { c, captured };
}

/** A minimal but valid Claude-format request payload. */
const PAYLOAD = {
  model: "fugu-ultra",
  max_tokens: 16,
  messages: [{ role: "user", content: "hi" }],
};

const REGION_OPT_IN_URL = "https://opencode.ai/workspace/0123456789abcdef0123456789abcdef/go";

function makeHandler(): ComposedHandler {
  return new ComposedHandler(makeTransport(), "fugu-ultra", "fugu-ultra", 8080, {});
}

describe("ComposedHandler.handle — error surfacing wiring", () => {
  test("terminal billing 429 is remapped to a surfaced HTTP 400 (stops silent retry)", async () => {
    stubUpstream(429, {
      error: {
        message: "You exceeded your current quota, check your plan & billing details.",
        type: "insufficient_quota",
        code: "insufficient_quota",
      },
    });
    const { c, captured } = makeContext();
    await makeHandler().handle(c, PAYLOAD);

    // Remapped away from the retryable 429 to a terminal 400.
    expect(captured.status).toBe(400);
    expect(captured.body?.type).toBe("error");
    expect(captured.body?.error?.type).toBe("invalid_request_error");
    // Rich, attributed, includes the real upstream message.
    expect(captured.body?.error?.message).toContain("Sakana Fugu error (HTTP 429)");
    expect(captured.body?.error?.message).toContain("exceeded your current quota");
  });

  test("a context overflow reaches the client LEADING with `prompt is too long`", async () => {
    // The whole point of item 8: providers state the overflow in their own
    // words, and no Anthropic client matches those words. Without the phrase the
    // client classifies this as a generic invalid request and never offers to
    // compact. Asserted through the handler, not the builder, because the
    // builder being right proves nothing if the wiring never asks for it.
    stubUpstream(400, {
      error: {
        message:
          "This model's maximum context length is 128000 tokens. However, your messages resulted in 200000 tokens.",
        type: "invalid_request_error",
        code: "context_length_exceeded",
      },
    });
    const { c, captured } = makeContext();
    await makeHandler().handle(c, PAYLOAD);

    expect(captured.status).toBe(400);
    expect(captured.body?.error?.type).toBe("invalid_request_error");
    expect(captured.body?.error?.message?.startsWith("prompt is too long")).toBe(true);
    // The 400-remap contract: the real upstream status still rides along, and
    // the provider's own sentence is still there for a human to read.
    expect(captured.body?.error?.upstream_status).toBe(400);
    expect(captured.body?.error?.message).toContain("maximum context length is 128000 tokens");
  });

  test("a 413 overflow is remapped to 400 and keeps its upstream status", async () => {
    stubUpstream(413, {
      error: { message: "Payload too large: the prompt exceeds this model's context window" },
    });
    const { c, captured } = makeContext();
    await makeHandler().handle(c, PAYLOAD);

    expect(captured.status).toBe(400);
    expect(captured.body?.error?.message?.startsWith("prompt is too long")).toBe(true);
    expect(captured.body?.error?.upstream_status).toBe(413);
  });

  test("a parameter rejection is NOT relabelled as an oversized prompt", async () => {
    // The ordering guard, end to end. `max_output_tokens` contains the word
    // "tokens"; adapters.md records the incident where that alone was enough to
    // report a 6.7 KB prompt against a 1.05M window as too large.
    stubUpstream(400, {
      error: {
        message: "Unknown parameter: 'max_output_tokens'.",
        type: "invalid_request_error",
        param: "max_output_tokens",
        code: "unknown_parameter",
      },
    });
    const { c, captured } = makeContext();
    await makeHandler().handle(c, PAYLOAD);

    expect(captured.body?.error?.message ?? "").not.toContain("prompt is too long");
    // Unchanged from before item 8: not terminal, so the status passes through.
    expect(captured.status).toBe(400);
  });

  test("terminal auth 401 is surfaced as 400 (not silently retried)", async () => {
    stubUpstream(401, { error: { message: "invalid api key" } });
    const { c, captured } = makeContext();
    await makeHandler().handle(c, PAYLOAD);

    expect(captured.status).toBe(400);
    expect(captured.body?.error?.type).toBe("invalid_request_error");
    expect(captured.body?.error?.message).toContain("Sakana Fugu error (HTTP 401)");
    expect(captured.body?.error?.message).toContain("invalid api key");
  });

  test("a model-unsupported 401 surfaces the model hint instead of an API-key hint", async () => {
    stubUpstream(401, {
      error: { message: "Model deepseek-v4-pro-0813 is not supported" },
    });
    const { c, captured } = makeContext();

    await makeHandler().handle(c, PAYLOAD);

    expect(captured.body?.error?.message).toContain("Model not supported by this provider");
    expect(captured.body?.error?.message).not.toContain("Check API key");
  });

  test("an invalid-key 401 surfaces the credential recovery hint", async () => {
    stubUpstream(401, { error: { message: "Invalid API key." } });
    const { c, captured } = makeContext();

    await makeHandler().handle(c, PAYLOAD);

    expect(captured.body?.error?.message).toContain("Check API key / OAuth credentials");
    expect(captured.body?.error?.message).not.toContain("Model not supported by this provider");
  });

  test("an actionable RegionError 403 surfaces its URL instead of an API-key hint", async () => {
    stubUpstream(403, {
      type: "error",
      error: {
        type: "RegionError",
        message: `The latest version of this model is only available hosted in China and requires explicit opt in: ${REGION_OPT_IN_URL}`,
      },
    });
    const { c, captured } = makeContext();

    await makeHandler().handle(c, PAYLOAD);

    expect(captured.body?.error?.message).not.toContain("Check API key");
    expect(captured.body?.error?.message).toContain(REGION_OPT_IN_URL);
  });

  test("transient 503 keeps its retryable status (Claude Code SHOULD retry)", async () => {
    stubUpstream(503, { error: { message: "temporary overload", type: "server_error" } });
    const { c, captured } = makeContext();
    await makeHandler().handle(c, PAYLOAD);

    // NOT remapped — must stay 503 so the host retries the transient failure.
    expect(captured.status).toBe(503);
    expect(captured.body?.type).toBe("error");
    expect(captured.body?.error?.message).toContain("temporary overload");
  });

  test("plain (non-terminal) 429 rate-limit keeps its retryable status", async () => {
    stubUpstream(429, { error: { message: "rate limit exceeded, slow down" } });
    const { c, captured } = makeContext();
    await makeHandler().handle(c, PAYLOAD);

    expect(captured.status).toBe(429);
    expect(captured.body?.error?.message).toContain("rate limit exceeded");
  });

  test("transient 500 whose prose contains 'not supported' is NOT mis-remapped to 400", async () => {
    // False-positive guard at the integration level: a transient 5xx body that
    // happens to contain a terminal-looking phrase must still retry.
    stubUpstream(503, {
      error: { message: "Retry-After header not supported by upstream gateway; overloaded" },
    });
    const { c, captured } = makeContext();
    await makeHandler().handle(c, PAYLOAD);

    expect(captured.status).toBe(503);
  });

  test("non-JSON upstream error body is still surfaced, not dropped", async () => {
    // 401 is terminal regardless of body shape → remapped to 400, raw text kept.
    stubUpstream(401, "Unauthorized");
    const { c, captured } = makeContext();
    await makeHandler().handle(c, PAYLOAD);

    expect(captured.status).toBe(400);
    expect(captured.body?.error?.message).toContain("Unauthorized");
  });

  // Keep connection failures at 400: both 400 and 503 stop claudish's fallback
  // chain, but Claude Code retries a 503 as overloaded_error and buries the real
  // reason behind "API error - Retrying - attempt N/10". A 400 is rendered
  // verbatim inline, while probe-live still classifies by the status-agnostic
  // connection_error type.
  test("a thrown DNS error is surfaced as a 400 connection_error", async () => {
    stubUpstreamThrow(
      Object.assign(new TypeError("fetch failed"), {
        cause: Object.assign(new Error("getaddrinfo ENOTFOUND host"), { code: "ENOTFOUND" }),
      })
    );
    const { c, captured } = makeContext();
    await makeHandler().handle(c, PAYLOAD);

    expect(captured.status).toBe(400);
    expect(captured.body?.type).toBe("error");
    expect(captured.body?.error?.type).toBe("connection_error");
    expect(captured.body?.error?.message).toContain("Cannot resolve");
    expect(captured.body?.error?.message).toContain("DNS");
    expect(captured.body?.error?.type).not.toBe("api_error");
  });

  test("a thrown ECONNREFUSED error is surfaced as a 400 connection_error", async () => {
    stubUpstreamThrow(Object.assign(new Error("connect ECONNREFUSED"), { code: "ECONNREFUSED" }));
    const { c, captured } = makeContext();
    await makeHandler().handle(c, PAYLOAD);

    expect(captured.status).toBe(400);
    expect(captured.body?.error?.type).toBe("connection_error");
    expect(captured.body?.error?.message).toContain("Make sure the server is running");
  });

  test("a thrown connection error is surfaced with a single-line terminal-safe message", async () => {
    stubUpstreamThrow(
      Object.assign(
        new Error(
          "Unable to connect. Is the computer able to access the url?\n\t\u001b[31mconnection failed\u001b[0m"
        ),
        { code: "ConnectionRefused" }
      )
    );
    const { c, captured } = makeContext();
    await makeHandler().handle(c, PAYLOAD);

    const message = captured.body?.error?.message;
    expect(typeof message).toBe("string");
    expect(message).not.toMatch(/[\r\n\t]/);
    expect(message).not.toContain("\u001b");
  });

  test("a non-connection throw propagates without calling c.json", async () => {
    const thrown = new TypeError("Cannot read properties of undefined");
    stubUpstreamThrow(thrown);
    const { c, captured } = makeContext();
    let didReject = false;

    try {
      await makeHandler().handle(c, PAYLOAD);
    } catch (error) {
      didReject = true;
      expect(error).toBe(thrown);
    }

    expect(didReject).toBe(true);
    expect(captured.status).toBeUndefined();
  });
});

type TerminalClassifier = NonNullable<ProviderTransport["classifyTerminalError"]>;

function makeHandlerWithClassifier(classifyTerminalError: TerminalClassifier): ComposedHandler {
  const transport: ProviderTransport = { ...makeTransport(), classifyTerminalError };
  return new ComposedHandler(transport, "fugu-ultra", "fugu-ultra", 8080, {});
}

describe("ComposedHandler.handle — transport terminality override", () => {
  test("transport-declared transient 429 overrides quota-wording heuristic", async () => {
    const message = "Resource has been exhausted (e.g. check quota).";
    stubUpstream(429, {
      error: { code: 429, message, status: "RESOURCE_EXHAUSTED" },
    });
    let calls = 0;
    const handler = makeHandlerWithClassifier((status, bodyText) => {
      calls += 1;
      expect(status).toBe(429);
      expect(bodyText).toContain(message);
      return false;
    });
    const { c, captured } = makeContext();

    await handler.handle(c, PAYLOAD);

    expect(calls).toBe(1);
    expect(captured.status).toBe(429);
    expect(captured.body?.error?.message).toContain(message);
  });

  test("transport-declared terminal 429 is surfaced as out of quota", async () => {
    stubUpstream(429, { error: { message: "rate limit exceeded, slow down" } });
    const { c, captured } = makeContext();

    await makeHandlerWithClassifier(() => true).handle(c, PAYLOAD);

    expect(captured.status).toBe(400);
    expect(captured.body?.error?.type).toBe("invalid_request_error");
    expect(captured.body?.error?.message).toContain("Out of quota");
  });

  test("an undefined transport verdict falls back to generic terminal-429 classification", async () => {
    stubUpstream(429, {
      error: {
        message: "insufficient_quota",
        type: "insufficient_quota",
        code: "insufficient_quota",
      },
    });
    const { c, captured } = makeContext();

    await makeHandlerWithClassifier(() => undefined).handle(c, PAYLOAD);

    expect(captured.status).toBe(400);
    expect(captured.body?.error?.message).toContain("Out of quota");
    expect(captured.body?.error?.message).toContain("insufficient_quota");
  });
});

const RETRIED_SUCCESS_SSE = [
  `data: ${JSON.stringify({
    id: "chatcmpl-after-refresh",
    object: "chat.completion.chunk",
    created: 1,
    model: "fugu-ultra",
    choices: [
      {
        index: 0,
        delta: { role: "assistant", content: "response from refreshed request" },
        finish_reason: "stop",
      },
    ],
  })}`,
  "data: [DONE]",
  "",
].join("\n\n");

describe("ComposedHandler.handle — 401 auth refresh retry", () => {
  test("calls forceRefreshAuth exactly once, retries once, and returns the retried 200 response", async () => {
    let refreshCalls = 0;
    const calls = stubUpstreamSequence(
      { status: 401, body: { error: { message: "stale token" } } },
      {
        status: 200,
        body: RETRIED_SUCCESS_SSE,
        headers: { "Content-Type": "text/event-stream" },
      }
    );
    const transport = makeTransportWithRefresh(() => {
      refreshCalls += 1;
    });
    const handler = new ComposedHandler(transport, "fugu-ultra", "fugu-ultra", 8080, {});
    const { c } = makeContext();

    const response = await handler.handle(c, PAYLOAD);
    const body = (await response.json()) as { content?: Array<{ text?: string }> };

    expect(refreshCalls).toBe(1);
    expect(calls).toHaveLength(2);
    expect(response.status).toBe(200);
    expect(body.content?.[0]?.text).toBe("response from refreshed request");
  });

  test("retries with headers minted after forceRefreshAuth", async () => {
    let refreshed = false;
    const calls = stubUpstreamSequence(
      { status: 401, body: { error: { message: "stale token" } } },
      {
        status: 200,
        body: RETRIED_SUCCESS_SSE,
        headers: { "Content-Type": "text/event-stream" },
      }
    );
    const transport = makeTransportWithRefresh(
      () => {
        refreshed = true;
      },
      async () => ({ Authorization: refreshed ? "Bearer fresh" : "Bearer stale" })
    );
    const handler = new ComposedHandler(transport, "fugu-ultra", "fugu-ultra", 8080, {});
    const { c } = makeContext();

    const response = await handler.handle(c, PAYLOAD);
    await response.arrayBuffer();

    expect(calls).toHaveLength(2);
    expect(new Headers(calls[0]?.init?.headers).get("Authorization")).toBe("Bearer stale");
    expect(new Headers(calls[1]?.init?.headers).get("Authorization")).toBe("Bearer fresh");
  });

  test("refreshes only once when the retried request also returns 401", async () => {
    let refreshCalls = 0;
    const calls = stubUpstreamSequence(
      { status: 401, body: { error: { message: "stale token" } } },
      { status: 401, body: { error: { message: "fresh token rejected too" } } }
    );
    const transport = makeTransportWithRefresh(() => {
      refreshCalls += 1;
    });
    const handler = new ComposedHandler(transport, "fugu-ultra", "fugu-ultra", 8080, {});
    const { c, captured } = makeContext();

    const response = await handler.handle(c, PAYLOAD);

    expect(refreshCalls).toBe(1);
    expect(calls).toHaveLength(2);
    expect(response.ok).toBe(false);
    expect(captured.status).toBe(401);
  });

  test("a transport without forceRefreshAuth surfaces a 401 through the generic error path", async () => {
    const calls = stubUpstreamSequence({
      status: 401,
      body: { error: { message: "invalid api key" } },
    });
    const handler = new ComposedHandler(makeTransport(), "fugu-ultra", "fugu-ultra", 8080, {});
    const { c, captured } = makeContext();

    const response = await handler.handle(c, PAYLOAD);

    expect(calls).toHaveLength(1);
    expect(response.ok).toBe(false);
    expect(captured.status).toBe(400);
    expect(captured.body?.error?.message).toContain("Sakana Fugu error (HTTP 401)");
  });
});