qwenproxy-cli 1.0.0

package/bin/qwenproxy.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+
+/**
+ * QwenProxy - Unified CLI Entrypoint & Runner
+ *
+ * Commands:
+ *   qwenproxy (default) -> Launches the interactive TUI management dashboard and proxy
+ *   qwenproxy --server  -> Runs headless proxy server in background
+ *   qwenproxy sync      -> Synchronizes AI coding clients (Claude Code, Codex, OpenCode, OMP)
+ *   qwenproxy clean     -> Prunes transient caches
+ *   qwenproxy clean:all -> Reclaims unused Playwright browsers and caches
+ *   qwenproxy reset     -> Resets rate-limit and auth cooldowns
+ *   qwenproxy purge     -> Deletes remote chats across configured accounts
+ *   qwenproxy login     -> Authenticates accounts via visible browser
+ */
+
+import { spawn, spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createRequire } from "node:module";
+import fs from "node:fs";
+
+const require = createRequire(import.meta.url);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, "..");
+const packageJsonPath = path.join(packageRoot, "package.json");
+
+const rawArgs = process.argv.slice(2);
+const firstArg = rawArgs[0]?.toLowerCase();
+
+// 1. Version check
+if (rawArgs.includes("-v") || rawArgs.includes("--version") || firstArg === "version") {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+    console.log(`QwenProxy v${pkg.version || "1.0.0"}`);
+  } catch {
+    console.log("QwenProxy v1.0.0");
+  }
+  process.exit(0);
+}
+
+// 2. Help check
+if (rawArgs.includes("-h") || rawArgs.includes("--help") || firstArg === "help") {
+  console.log(`
+QwenProxy — High-performance AI Coding Gateway & Management TUI
+
+Usage:
+  qwenproxy [options] [command]
+  qpx [options] [command]
+
+Commands:
+  (default)     Launch interactive TUI management dashboard and proxy
+  start         Run headless HTTP/SSE proxy server
+  login         Authenticate new accounts via visible browser
+  sync          Synchronize AI clients (Claude Code, Codex, OpenCode, OMP)
+  clean         Prune transient profile caches
+  clean:all     Prune profile caches and clean unused Playwright browsers
+  reset         Reset rate-limit and auth cooldowns in database
+  purge         Delete remote chats across configured accounts
+
+Options:
+  --tui         Open interactive TUI dashboard (default)
+  --server      Run in headless server mode
+  --port <num>  Override server listening port (default: 7936)
+  -v, --version Show version number
+  -h, --help    Show this help message
+`);
+  process.exit(0);
+}
+
+// 3. Command dispatcher
+let scriptFile = "src/index.ts";
+let scriptArgs = [];
+
+if (firstArg === "start" || rawArgs.includes("--server")) {
+  scriptFile = "src/index.ts";
+  scriptArgs = rawArgs.filter((a) => a !== "start" && a !== "--server");
+} else if (firstArg === "tui" || rawArgs.includes("--tui") || rawArgs.length === 0) {
+  scriptFile = "src/index.ts";
+  scriptArgs = ["--tui", ...rawArgs.filter((a) => a !== "tui" && a !== "--tui")];
+} else if (firstArg === "sync") {
+  scriptFile = "src/sync-clients.ts";
+  scriptArgs = rawArgs.slice(1);
+} else if (firstArg === "clean") {
+  scriptFile = "src/clean-cache.ts";
+  scriptArgs = rawArgs.slice(1);
+} else if (firstArg === "clean:all") {
+  scriptFile = "src/clean-cache.ts";
+  scriptArgs = ["--all", ...rawArgs.slice(1)];
+} else if (firstArg === "reset") {
+  scriptFile = "src/reset-cooldowns.ts";
+  scriptArgs = rawArgs.slice(1);
+} else if (firstArg === "purge") {
+  scriptFile = "src/delete-chats.ts";
+  scriptArgs = rawArgs.slice(1);
+} else if (firstArg === "login") {
+  scriptFile = "src/login.ts";
+  scriptArgs = rawArgs.slice(1);
+} else {
+  // Pass through remaining options to index.ts with default TUI flag
+  scriptFile = "src/index.ts";
+  scriptArgs = ["--tui", ...rawArgs];
+}
+
+const targetPath = path.resolve(packageRoot, scriptFile);
+
+// Resolve tsx loader relative to the package installation rather than cwd
+let tsxLoaderArg = "tsx";
+try {
+  const tsxEntry = require.resolve("tsx");
+  tsxLoaderArg = pathToFileURL(tsxEntry).href;
+} catch {}
+
+// Ensure Playwright Chromium is installed for first-time global users
+try {
+  const { chromium } = await import("patchright");
+  const execPath = chromium.executablePath();
+  if (!fs.existsSync(execPath)) {
+    console.log("⏳ [QwenProxy] Instalando o navegador Chromium pela primeira vez...");
+    spawnSync("npx", ["patchright", "install", "chromium"], {
+      stdio: "inherit",
+      shell: true,
+    });
+    console.log("✓ [QwenProxy] Navegador instalado com sucesso!\n");
+  }
+} catch {}
+
+const child = spawn(process.execPath, ["--import", tsxLoaderArg, targetPath, ...scriptArgs], {
+  stdio: "inherit",
+  cwd: process.cwd(),
+  env: process.env,
+});
+
+child.on("exit", (code, signal) => {
+  process.exit(code ?? (signal ? 1 : 0));
+});
+
+child.on("error", (err) => {
+  console.error("❌ [QwenProxy] Failed to execute CLI script:", err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "qwenproxy-cli",
+  "version": "1.0.0",
+  "description": "API compatível com OpenAI que conecta clientes ao Qwen via Playwright, com suporte a múltiplas contas, tool calling e sessões persistentes.",
+  "main": "src/index.ts",
+  "bin": {
+    "qwenproxy": "bin/qwenproxy.js",
+    "qpx": "bin/qwenproxy.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "!src/tests",
+    "!src/benchmarks",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "postinstall": "patchright install chromium",
+    "start": "tsx src/index.ts",
+    "tui": "npx tsx src/tui/index.ts",
+    "login": "npx tsx src/login.ts",
+    "sync": "npx tsx src/sync-clients.ts",
+    "clean": "npx tsx src/clean-cache.ts",
+    "clean:all": "npx tsx src/clean-cache.ts --all",
+    "reset": "npx tsx src/reset-cooldowns.ts",
+    "purge": "npx tsx src/delete-chats.ts",
+    "test": "npm run test:mock && npm run test:live",
+    "test:mock": "tsx --test --test-concurrency=1 --env-file=.env.test src/tests/account-concurrency.test.ts src/tests/concurrency-latest-wins.test.ts src/tests/mutex.test.ts src/tests/context-truncation.test.ts src/tests/streaming-thinking-summary.test.ts src/tests/tool-call-guard.test.ts src/tests/utils-logger-full.test.ts src/tests/logger-toolcall-errors.test.ts src/tests/logger-toolcall-disabled.test.ts src/tests/utils-json-full.test.ts src/tests/utils-session-guard-full.test.ts src/tests/core-logic-full.test.ts src/tests/core-logic-accounts.test.ts src/tests/chat-validation-full.test.ts src/tests/chat-logic-full.test.ts src/tests/account-stickiness.test.ts src/tests/accounts-security.test.ts src/tests/advanced.test.ts src/tests/auth-playwright.test.ts src/tests/captcha-solver.test.ts src/tests/cache-scan-regex.test.ts src/tests/chat-cleanup.test.ts src/tests/chromium-args.test.ts src/tests/config-current.test.ts src/tests/context-meter.test.ts src/tests/concurrency.test.ts src/tests/delta.test.ts src/tests/fingerprint.test.ts src/tests/human-behavior.test.ts src/tests/index.test.ts src/tests/json-recovery.test.ts src/tests/jsonFix.test.ts src/tests/memory-cache.test.ts src/tests/model-alias.test.ts src/tests/model-registry-thinking.test.ts src/tests/models-endpoint.test.ts src/tests/multimodal.test.ts src/tests/oss-upload.test.ts src/tests/parser.test.ts src/tests/personalization-flow.test.ts src/tests/personalization-required.test.ts src/tests/retry-policy.test.ts src/tests/rotation.test.ts src/tests/server-lifecycle.test.ts src/tests/session-keeper.test.ts src/tests/session-state.test.ts src/tests/single-account-mode.test.ts src/tests/stream-retry.test.ts src/tests/tool-calls-endpoint.test.ts src/tests/tool-instructions-cache.test.ts src/tests/session-id.test.ts src/tests/watchdog-ram.test.ts src/tests/tool-recovery-t1t2.test.ts src/tests/abort-silent-t4.test.ts src/tests/t3-close-tag-escape.test.ts src/tests/t5-tool-cap.test.ts src/tests/logger-redaction.test.ts src/tests/stall-timeout-retryable.test.ts src/tests/t6-missing-quote-array-close.test.ts src/tests/watchdog-rss.test.ts src/tests/logical-thread-batch.test.ts src/tests/chat-pool-style.test.ts src/tests/queue-wait-cap.test.ts src/tests/context-eviction-order.test.ts src/tests/chat-in-progress-settle.test.ts src/tests/stream-lock-leak.test.ts src/tests/stream-semaphore.test.ts src/tests/waf-isolation.test.ts src/tests/legacy-completions.test.ts src/tests/response-format.test.ts src/tests/cors-headers.test.ts src/tests/stream-lock-terminal-cancel.test.ts src/tests/parser-truncated-tool-call.test.ts src/tests/metrics-prometheus.test.ts src/tests/context-death-cleanup.test.ts src/tests/personalization-direct-fetch.test.ts src/tests/completion-headers-parity.test.ts src/tests/parallel-escape-repro.test.ts src/tests/chat-in-progress-scale-cost.test.ts src/tests/temp-chat-mode.test.ts src/tests/profile-reset.test.ts src/tests/error-classification.test.ts src/tests/quota-cooldown.test.ts src/tests/account-ready-gate.test.ts src/tests/tool-cap-notice.test.ts src/tests/interaction-flows.test.ts src/tests/headers-gate-cooldown-fallback.test.ts src/tests/unwrapped-tool-calls.test.ts src/tests/anthropic.test.ts src/tests/sync-clients.test.ts src/tests/cli.test.ts src/tests/paths.test.ts src/tests/tool-manifest.test.ts src/tests/tui.test.ts",
+    "test:mock:fast": "tsx --test --test-concurrency=2 --env-file=.env.test src/tests/account-concurrency.test.ts src/tests/concurrency-latest-wins.test.ts src/tests/mutex.test.ts src/tests/context-truncation.test.ts src/tests/streaming-thinking-summary.test.ts src/tests/tool-call-guard.test.ts src/tests/utils-logger-full.test.ts src/tests/logger-toolcall-errors.test.ts src/tests/logger-toolcall-disabled.test.ts src/tests/utils-json-full.test.ts src/tests/utils-session-guard-full.test.ts src/tests/core-logic-full.test.ts src/tests/core-logic-accounts.test.ts src/tests/chat-validation-full.test.ts src/tests/chat-logic-full.test.ts src/tests/account-stickiness.test.ts src/tests/accounts-security.test.ts src/tests/advanced.test.ts src/tests/auth-playwright.test.ts src/tests/captcha-solver.test.ts src/tests/cache-scan-regex.test.ts src/tests/chat-cleanup.test.ts src/tests/chromium-args.test.ts src/tests/config-current.test.ts src/tests/context-meter.test.ts src/tests/concurrency.test.ts src/tests/delta.test.ts src/tests/fingerprint.test.ts src/tests/human-behavior.test.ts src/tests/index.test.ts src/tests/json-recovery.test.ts src/tests/jsonFix.test.ts src/tests/memory-cache.test.ts src/tests/model-alias.test.ts src/tests/model-registry-thinking.test.ts src/tests/models-endpoint.test.ts src/tests/multimodal.test.ts src/tests/oss-upload.test.ts src/tests/parser.test.ts src/tests/personalization-flow.test.ts src/tests/personalization-required.test.ts src/tests/retry-policy.test.ts src/tests/rotation.test.ts src/tests/server-lifecycle.test.ts src/tests/session-keeper.test.ts src/tests/session-state.test.ts src/tests/single-account-mode.test.ts src/tests/stream-retry.test.ts src/tests/tool-calls-endpoint.test.ts src/tests/tool-instructions-cache.test.ts src/tests/session-id.test.ts src/tests/watchdog-ram.test.ts src/tests/tool-recovery-t1t2.test.ts src/tests/abort-silent-t4.test.ts src/tests/t3-close-tag-escape.test.ts src/tests/t5-tool-cap.test.ts src/tests/logger-redaction.test.ts src/tests/stall-timeout-retryable.test.ts src/tests/t6-missing-quote-array-close.test.ts src/tests/watchdog-rss.test.ts src/tests/logical-thread-batch.test.ts src/tests/chat-pool-style.test.ts src/tests/queue-wait-cap.test.ts src/tests/context-eviction-order.test.ts src/tests/chat-in-progress-settle.test.ts src/tests/stream-lock-leak.test.ts src/tests/stream-semaphore.test.ts src/tests/waf-isolation.test.ts src/tests/legacy-completions.test.ts src/tests/response-format.test.ts src/tests/cors-headers.test.ts src/tests/stream-lock-terminal-cancel.test.ts src/tests/parser-truncated-tool-call.test.ts src/tests/metrics-prometheus.test.ts src/tests/context-death-cleanup.test.ts src/tests/personalization-direct-fetch.test.ts src/tests/completion-headers-parity.test.ts src/tests/parallel-escape-repro.test.ts src/tests/chat-in-progress-scale-cost.test.ts src/tests/temp-chat-mode.test.ts src/tests/profile-reset.test.ts src/tests/error-classification.test.ts src/tests/quota-cooldown.test.ts src/tests/account-ready-gate.test.ts src/tests/tool-cap-notice.test.ts src/tests/interaction-flows.test.ts src/tests/headers-gate-cooldown-fallback.test.ts src/tests/unwrapped-tool-calls.test.ts src/tests/anthropic.test.ts src/tests/sync-clients.test.ts src/tests/cli.test.ts src/tests/paths.test.ts src/tests/tool-manifest.test.ts src/tests/tui.test.ts",
+    "test:live": "tsx --test src/tests/concurrentChat.test.ts src/tests/agenticStress.test.ts",
+    "benchmark:proxy": "npx tsx src/benchmarks/proxy-baseline.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "qwen",
+    "proxy",
+    "openai",
+    "anthropic",
+    "claude-code",
+    "codex",
+    "opencode",
+    "tui",
+    "patchright",
+    "playwright",
+    "llm"
+  ],
+  "homepage": "https://github.com/johngbl/qwenproxy#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/johngbl/qwenproxy.git"
+  },
+  "bugs": {
+    "url": "https://github.com/johngbl/qwenproxy/issues"
+  },
+  "author": "johngbl <147551701+johngbl@users.noreply.github.com>",
+  "license": "ISC",
+  "dependencies": {
+    "@hono/node-server": "^2.1.1",
+    "ali-oss": "^6.23.0",
+    "better-sqlite3": "^13.0.3",
+    "dotenv": "^17.4.2",
+    "hono": "^4.13.7",
+    "patchright": "^1.62.3",
+    "tsx": "^4.23.13",
+    "uuid": "^14.0.2",
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^9.6.0",
+    "@types/node": "^26.4.1",
+    "typescript": "^7.0.2"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  }
+}

package/src/api/error-classifier.ts

@@ -0,0 +1,159 @@
+import { ZodError } from "zod";
+import { logger } from "../core/logger.js";
+import {
+  QwenProxyError,
+  InternalError,
+  ValidationError,
+  UpstreamRateLimit,
+  UpstreamError,
+  UpstreamTimeout,
+  ServiceUnavailable,
+  ClientAbortedError,
+} from "../core/errors.js";
+import {
+  QwenNetworkError,
+  QwenUpstreamUnavailableError,
+  RetryableQwenStreamError,
+  QwenUpstreamError,
+  QwenSessionExpiredError,
+  getQwenErrorCode,
+} from "../services/qwen.js";
+
+/**
+ * Classifies unknown errors into standard QwenProxyError hierarchy.
+ * Preserves specific error metadata when possible.
+ */
+export function classifyError(err: unknown): QwenProxyError {
+  // These errors are retryable upstream failures, not rate-limit responses.
+  // RetryableQwenStreamError inherits UpstreamRateLimit for legacy behavior,
+  // so classify the concrete network/upstream types before that base class.
+  if (
+    err instanceof QwenNetworkError ||
+    err instanceof QwenUpstreamUnavailableError
+  ) {
+    return new UpstreamError(err.message);
+  }
+
+  if (err instanceof RetryableQwenStreamError) {
+    const upstreamCode = getQwenErrorCode(err)?.toLowerCase() || "";
+    const message = err.message.toLowerCase();
+
+    // Content moderation rejections are client-side content policy violations,
+    // not upstream failures. Return 400 so the client can adjust its input.
+    if (
+      upstreamCode === "data_inspection_failed" ||
+      message.includes("content moderation") ||
+      message.includes("data_inspection_failed")
+    ) {
+      const moderationError = new ValidationError(
+        `Content rejected by Qwen safety filter: ${err.message.replace(/^Qwen content moderation: [^:]+: /, "")}`,
+      );
+      (moderationError as any).code = "content_policy_violation";
+      return moderationError;
+    }
+
+    const isActualRateLimit =
+      upstreamCode === "quota_limit" ||
+      upstreamCode === "ratelimited" ||
+      upstreamCode === "rate_limit" ||
+      upstreamCode === "rate_limit_exceeded" ||
+      message.includes("quota") ||
+      message.includes("upper limit for today");
+
+    return isActualRateLimit
+      ? new UpstreamRateLimit(err.message)
+      : new UpstreamError(err.message);
+  }
+
+  if (err instanceof QwenUpstreamError) {
+    return err;
+  }
+
+  if (err instanceof QwenSessionExpiredError) {
+    return err;
+  }
+
+  if (err instanceof QwenProxyError) {
+    return err;
+  }
+
+  // Client disconnected before the stream could be created. This is not a
+  // server fault: the request has no listener anymore. Classify it as a silent
+  // abort (499) so callers neither emit a 500 nor count it as an error.
+  if (err instanceof Error && err.message.includes("client aborted")) {
+    return new ClientAbortedError(err.message);
+  }
+
+  // Capacity saturation on the bridge's own account pool: this is a "try again
+  // later" condition, not a server fault. A hard 500 is misleading for the
+  // client (and for the retry classifier it hides a recoverable slot wait).
+  if (
+    err instanceof Error &&
+    (err as Error & { code?: string }).code === "account_busy"
+  ) {
+    return new UpstreamRateLimit(err.message);
+  }
+
+  // Some call sites attach an explicit hint on a plain Error (e.g.
+  // acquireUpstreamStream sets upstreamStatus=429 when the whole pool is in
+  // cooldown). Respect it instead of falling through to a misleading 500.
+  const rawError = err as Error | null | undefined;
+
+  // A mutex acquire timeout (chat lock / personalization lock / playwright
+  // page lock) means the resource is BUSY, not broken — the holder is a
+  // legitimate long generation or a stuck-but-recoverable page op. Mapping it
+  // to 500 made every concurrent request on a long chat turn fail hard with
+  // internal_server_error (2026-08-22 production log). Surface as retryable
+  // 503 so the client (or the retry policy) can wait and re-request.
+  if (
+    rawError instanceof Error &&
+    rawError.message.startsWith("Mutex[") &&
+    rawError.message.includes("acquire timeout")
+  ) {
+    return new ServiceUnavailable(
+      `Resource busy (${rawError.message.substring(0, 200)}). Retry shortly.`,
+    );
+  }
+
+  const statusHint = (err as Error & { upstreamStatus?: number })?.upstreamStatus;
+  if (typeof statusHint === "number") {
+    const message =
+      rawError instanceof Error
+        ? rawError.message
+        : typeof err === "string"
+          ? err
+          : "Unknown upstream error";
+    switch (statusHint) {
+      case 429:
+        return new UpstreamRateLimit(message);
+      case 502:
+        return new UpstreamError(message);
+      case 503:
+        return new ServiceUnavailable(message);
+      case 504:
+        return new UpstreamTimeout(message);
+      default:
+        break; // unknown hint: fall through to the normal mapping
+    }
+  }
+
+  if (err instanceof ZodError) {
+    return new ValidationError(err.message);
+  }
+
+  if (
+    err instanceof Error &&
+    (err.message.includes("Target page, context or browser has been closed") ||
+      err.message.includes("browserType.launchPersistentContext"))
+  ) {
+    return new ServiceUnavailable(
+      "Falha ao inicializar o navegador Playwright para a conta. O perfil pode estar travado por outro processo ou o navegador fechou inesperadamente. Execute 'npm run reset'.",
+    );
+  }
+
+  logger.warn("Unclassified error mapped to InternalError", {
+    error: err instanceof Error ? err.message : String(err),
+  });
+
+  return new InternalError(err instanceof Error ? err.message : String(err));
+}

package/src/api/error-helpers.ts

@@ -0,0 +1,118 @@
+import type { Context } from "hono";
+import type { QwenProxyStatusCode } from "../core/errors.js";
+import {
+  QwenProxyError,
+  ValidationError,
+  AuthError,
+  ForbiddenError,
+  NotFoundError,
+  UpstreamRateLimit,
+  UpstreamError,
+  UpstreamTimeout,
+  InternalError,
+  ClientAbortedError,
+  ServiceUnavailable,
+} from "../core/errors.js";
+import { classifyError } from "./error-classifier.js";
+
+const VALID_STATUSES: ReadonlySet<number> = new Set([
+  400, 401, 403, 404, 429, 499, 500, 502, 503, 504,
+]);
+
+function isValidStatus(code: number): code is QwenProxyStatusCode {
+  return VALID_STATUSES.has(code);
+}
+
+function errorForStatus(
+  status: QwenProxyStatusCode,
+  message: string,
+): QwenProxyError {
+  switch (status) {
+    case 400:
+      return new ValidationError(message);
+    case 401:
+      return new AuthError(message);
+    case 403:
+      return new ForbiddenError(message);
+    case 404:
+      return new NotFoundError(message);
+    case 429:
+      return new UpstreamRateLimit(message);
+    case 499:
+      return new ClientAbortedError(message);
+    case 500:
+      return new InternalError(message);
+    case 502:
+      return new UpstreamError(message);
+    case 503:
+      return new ServiceUnavailable(message);
+    case 504:
+      return new UpstreamTimeout(message);
+  }
+}
+
+/**
+ * Sends a standardized OpenAI-compatible error response.
+ * Handles QwenProxyError directly, checks upstreamStatus hints on plain errors,
+ * and falls back to the error classifier.
+ */
+export function sendOpenAIError(
+  c: Context,
+  err: unknown,
+  fallbackStatus?: QwenProxyStatusCode,
+): Response {
+  let qwenProxyErr: QwenProxyError;
+
+  if (err instanceof QwenProxyError) {
+    qwenProxyErr = err;
+  } else {
+    const hint = (err as Record<string, unknown>)?.upstreamStatus;
+    if (typeof hint === "number" && isValidStatus(hint)) {
+      qwenProxyErr = errorForStatus(
+        hint,
+        err instanceof Error ? err.message : String(err),
+      );
+    } else if (fallbackStatus) {
+      qwenProxyErr = errorForStatus(
+        fallbackStatus,
+        err instanceof Error ? err.message : String(err),
+      );
+    } else {
+      qwenProxyErr = classifyError(err);
+    }
+  }
+
+  const inner = qwenProxyErr.toOpenAI().error;
+  const body = {
+    error: {
+      message: inner.message,
+      type: inner.type,
+      code: inner.code,
+      param: inner.param ?? null,
+    },
+  };
+  // 499 (Client Closed Request) is not part of Hono's ContentfulStatusCode
+  // union. The abort is intercepted before sendOpenAIError in the chat route,
+  // but keep the fallback type-safe by building the Response directly.
+  if (qwenProxyErr.statusCode === 499) {
+    return new Response(JSON.stringify(body), {
+      status: 499,
+      headers: { "content-type": "application/json" },
+    });
+  }
+  return c.json(body, qwenProxyErr.statusCode);
+}
+
+/**
+ * Creates a QwenProxyError mapped to the given HTTP status code.
+ * Useful for inline error returns without throwing.
+ */
+export function createError(
+  status: QwenProxyStatusCode,
+  message: string,
+  param?: string,
+): QwenProxyError {
+  const err = errorForStatus(status, message);
+  if (param) err.param = param;
+  return err;
+}