@citeark/agent 0.3.20

package/dist/arkgraph/viewer.js.LEGAL.txt

@@ -0,0 +1,56 @@
+Bundled license information:
+
+react/cjs/react.production.js:
+  /**
+   * @license React
+   * react.production.js
+   *
+   * Copyright (c) Meta Platforms, Inc. and affiliates.
+   *
+   * This source code is licensed under the MIT license found in the
+   * LICENSE file in the root directory of this source tree.
+   */
+
+scheduler/cjs/scheduler.production.js:
+  /**
+   * @license React
+   * scheduler.production.js
+   *
+   * Copyright (c) Meta Platforms, Inc. and affiliates.
+   *
+   * This source code is licensed under the MIT license found in the
+   * LICENSE file in the root directory of this source tree.
+   */
+
+react-dom/cjs/react-dom.production.js:
+  /**
+   * @license React
+   * react-dom.production.js
+   *
+   * Copyright (c) Meta Platforms, Inc. and affiliates.
+   *
+   * This source code is licensed under the MIT license found in the
+   * LICENSE file in the root directory of this source tree.
+   */
+
+react-dom/cjs/react-dom-client.production.js:
+  /**
+   * @license React
+   * react-dom-client.production.js
+   *
+   * Copyright (c) Meta Platforms, Inc. and affiliates.
+   *
+   * This source code is licensed under the MIT license found in the
+   * LICENSE file in the root directory of this source tree.
+   */
+
+lodash-es/lodash.js:
+  /**
+   * @license
+   * Lodash (Custom Build) <https://lodash.com/>
+   * Build: `lodash modularize exports="es" --repo lodash/lodash#4.18.1 -o ./`
+   * Copyright OpenJS Foundation and other contributors <https://openjsf.org/>
+   * Released under MIT license <https://lodash.com/license>
+   * Based on Underscore.js 1.8.3 <http://underscorejs.org/LICENSE>
+   * Copyright Jeremy Ashkenas, DocumentCloud and Investigative Reporters & Editors
+   */

package/docker/claude-code/Dockerfile

@@ -0,0 +1,97 @@
+ARG BASE_IMAGE=node:22-bookworm
+ARG UV_VERSION=0.12.7
+FROM ghcr.io/astral-sh/uv:${UV_VERSION} AS uv-runtime
+FROM rust:1.85.1-bookworm AS rust-runtime
+FROM ${BASE_IMAGE}
+
+ARG CLAUDE_CODE_VERSION=2.1.227
+ARG CODEX_VERSION=0.159.1
+ARG OPENCODE_VERSION=1.18.14
+ARG INSTALL_SYSTEM_DEPENDENCIES=1
+ARG RUNTIME_DEVICE=cuda
+
+COPY --from=uv-runtime /uv /uvx /usr/local/bin/
+COPY --from=rust-runtime /usr/local/cargo /opt/citeark/cargo
+COPY --from=rust-runtime /usr/local/rustup /opt/citeark/rustup
+
+RUN if [ "${INSTALL_SYSTEM_DEPENDENCIES}" = "1" ]; then \
+        apt-get update \
+        && apt-get install -y --no-install-recommends \
+        build-essential \
+        ca-certificates \
+        cmake \
+        curl \
+        ffmpeg \
+        git \
+        git-lfs \
+        jq \
+        libgl1 \
+        libglib2.0-0 \
+        libgomp1 \
+        libsndfile1 \
+        ninja-build \
+        openssh-client \
+        pkg-config \
+        poppler-utils \
+        python3 \
+        python3-pip \
+        python3-venv \
+        rsync \
+        tar \
+        util-linux \
+        unzip \
+        wget \
+        && rm -rf /var/lib/apt/lists/*; \
+    fi \
+    && npm install --global \
+        "@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}" \
+        "@openai/codex@${CODEX_VERSION}" \
+        "opencode-ai@${OPENCODE_VERSION}" \
+    && claude --version \
+    && codex --version \
+    && opencode --version
+
+ENV DEBIAN_FRONTEND=noninteractive
+ENV PIP_DISABLE_PIP_VERSION_CHECK=1
+ENV PYTHONUNBUFFERED=1
+ENV UV_PYTHON_INSTALL_DIR=/opt/citeark/managed-python
+ENV UV_PYTHON_BIN_DIR=/usr/local/bin
+ENV CARGO_HOME=/opt/citeark/cargo
+ENV RUSTUP_HOME=/opt/citeark/rustup
+ENV PATH=/opt/citeark/venv/bin:/opt/citeark/cargo/bin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+ENV PIP_INDEX_URL=https://pypi.org/simple
+ENV HF_ENDPOINT=https://huggingface.co
+
+RUN uv python install 3.10 \
+    && uv python install 3.12 --default \
+    && uv --version \
+    && python --version \
+    && python3.10 --version \
+    && python3.12 --version \
+    && rustc --version \
+    && cargo --version
+
+COPY docker/claude-code/codex-pro-relay.mjs docker/claude-code/runtime-contract-check.mjs /opt/citeark/
+COPY runtime/requirements-baseline.txt /opt/citeark/requirements-baseline.txt
+COPY runtime/create-runtime-venv.sh /opt/citeark/create-runtime-venv.source.sh
+COPY runtime/install-scientific-runtime.sh /opt/citeark/install-scientific-runtime.sh
+COPY runtime/install-local-cpu-runtime.sh /opt/citeark/install-local-cpu-runtime.sh
+
+RUN chmod 0555 /opt/citeark/install-scientific-runtime.sh \
+    && if [ "$RUNTIME_DEVICE" = cpu ]; then \
+       bash /opt/citeark/install-local-cpu-runtime.sh; \
+       elif [ "$RUNTIME_DEVICE" = cuda ]; then \
+       CITEARK_BASELINE_REQUIREMENTS=/opt/citeark/requirements-baseline.txt \
+       CITEARK_RUNTIME_VENV_SOURCE=/opt/citeark/create-runtime-venv.source.sh \
+       CITEARK_RUNTIME_PROFILE=gcp-scientific-runtime \
+       CITEARK_PYTHON_PACKAGE_INDEX=https://pypi.org/simple \
+       CITEARK_HUGGINGFACE_ENDPOINT=https://huggingface.co \
+       /opt/citeark/install-scientific-runtime.sh; \
+       else echo "RUNTIME_DEVICE must be cpu or cuda" >&2; exit 1; fi \
+    && rm -f /opt/citeark/create-runtime-venv.source.sh
+
+RUN node /opt/citeark/runtime-contract-check.mjs
+
+WORKDIR /job/workspace/repository
+
+CMD ["sh", "-lc", "claude --version && codex --version && opencode --version"]

package/docker/claude-code/codex-pro-relay.mjs

@@ -0,0 +1,466 @@
+#!/usr/bin/env node
+
+import http from "node:http";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { pathToFileURL } from "node:url";
+import { randomUUID } from "node:crypto";
+import { writeFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+
+const DEFAULT_MAX_BODY_BYTES = 32 * 1024 * 1024;
+const DEFAULT_PROVIDER_REQUEST_TIMEOUT_MS = 10 * 60_000;
+
+export function createCodexProRelay({
+  upstreamBaseUrl = process.env.CITEARK_PROVIDER_UPSTREAM_BASE_URL
+    ?? process.env.CITEARK_CODEX_UPSTREAM_BASE_URL,
+  apiKey = process.env.OPENAI_API_KEY ?? process.env.CITEARK_API_KEY,
+  reasoningMode = process.env.CITEARK_CODEX_REASONING_MODE ?? "standard",
+  fetchImpl = fetch,
+  maxBodyBytes = DEFAULT_MAX_BODY_BYTES,
+  requestTimeoutMs = providerRequestTimeoutMs(),
+  paperBudget = budgetEnvironment(),
+} = {}) {
+  const upstream = normalizedUpstream(upstreamBaseUrl);
+  const providerTimeoutMs = positiveTimeoutMilliseconds(requestTimeoutMs);
+  if (!apiKey?.trim()) throw new Error("Codex Pro relay 缺少 OPENAI_API_KEY");
+  if (!new Set(["standard", "pro"]).has(reasoningMode)) {
+    throw new Error("Codex Pro relay 的推理模式无效");
+  }
+  const providerFetch = paperBudget
+    ? createBudgetedProviderFetch({ budget: paperBudget, fetchImpl }) : fetchImpl;
+
+  return http.createServer(async (request, response) => {
+    try {
+      const requestUrl = new URL(request.url ?? "/", "http://127.0.0.1");
+      if (request.method === "GET" && requestUrl.pathname === "/health") {
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end('{"ok":true}');
+        return;
+      }
+      if (!allowedRequest(request.method, requestUrl.pathname)) {
+        response.writeHead(404, { "content-type": "application/json" });
+        response.end('{"error":"unsupported relay route"}');
+        return;
+      }
+
+      const rawBody = request.method === "GET"
+        ? undefined
+        : await readRequestBody(request, maxBodyBytes);
+      let body = new Set(["/v1/responses", "/v1/chat/completions"]).has(requestUrl.pathname)
+        && reasoningMode === "pro"
+        ? rewriteCodexRequest(rawBody, reasoningMode)
+        : rawBody;
+      body = rewriteGeminiToolText(body, upstream, requestUrl.pathname);
+      const started = Date.now();
+      const headers = forwardedHeaders(request.headers, apiKey);
+      if (body) headers.set("content-length", String(body.byteLength));
+      const upstreamResponse = await providerFetch(`${upstream}${requestUrl.pathname}${requestUrl.search}`, {
+        method: request.method,
+        headers,
+        body,
+        redirect: "manual",
+        signal: AbortSignal.timeout(providerTimeoutMs),
+      });
+      console.log(JSON.stringify({
+        event: "codex_pro_relay.response",
+        path: requestUrl.pathname,
+        status: upstreamResponse.status,
+        durationMs: Date.now() - started,
+      }));
+      // OpenCode retries the generic "Provider returned error" even on HTTP 400.
+      // Keep a deterministic malformed tool reference terminal, without logging
+      // request/response bodies (which can contain private scientific inputs).
+      if (upstreamResponse.status === 400) {
+        const errorText = await upstreamResponse.text();
+        if (errorText.includes("function_response.response") && errorText.includes("display_name")) {
+          response.writeHead(400, { "content-type": "application/json" });
+          response.end(JSON.stringify({ error: {
+            code: 400,
+            message: "Gemini rejected an unresolved reference in tool output (invalid tool response).",
+          } }));
+          return;
+        }
+        response.writeHead(400, responseHeaders(upstreamResponse.headers));
+        response.end(errorText);
+        return;
+      }
+      response.writeHead(upstreamResponse.status, responseHeaders(upstreamResponse.headers));
+      if (!upstreamResponse.body) {
+        response.end();
+        return;
+      }
+      await pipeline(Readable.fromWeb(upstreamResponse.body), response);
+    } catch (error) {
+      if (error?.paperBudget === true && paperBudget) {
+        await writeFile("/job/execution/paper-budget-exhausted.json", JSON.stringify({
+          reason: error.message, at: new Date().toISOString(),
+        })).catch(() => {});
+      }
+      const timedOut = error?.name === "TimeoutError"
+        || error?.code === "ABORT_ERR";
+      console.error(JSON.stringify({
+        event: "codex_pro_relay.request_failed",
+        method: request.method,
+        path: request.url,
+        failureCategory: timedOut ? "timeout" : "provider",
+        message: timedOut
+          ? `Provider request exceeded ${Math.ceil(providerTimeoutMs / 1000)} seconds`
+          : error instanceof Error ? error.message : String(error),
+      }));
+      if (!response.headersSent) {
+        response.writeHead(error?.paperBudget ? 402 : timedOut ? 504 : 502, { "content-type": "application/json" });
+      }
+      if (!response.writableEnded) {
+        response.end(JSON.stringify({
+          error: error instanceof Error ? error.message : String(error),
+        }));
+      }
+    }
+  });
+}
+
+function budgetEnvironment() {
+  if (process.env.CITEARK_PAPER_BUDGET_REQUIRED === "1") {
+    return JSON.parse(readFileSync("/job/input/runner-paper-budget.json", "utf8"));
+  }
+  if (!process.env.CITEARK_PAPER_BUDGET_URL) return null;
+  return { url: process.env.CITEARK_PAPER_BUDGET_URL,
+    token: process.env.CITEARK_PAPER_BUDGET_TOKEN,
+    workerId: process.env.CITEARK_PAPER_BUDGET_WORKER };
+}
+
+// The trusted relay reserves before every paid request. The durable paper ledger
+// survives VM preemption, compiler repairs, process crashes and continuations.
+export function isOpenRouterAdmissionRefusal(value) {
+  const error = value?.error;
+  return error?.code === 402
+    && error.metadata?.reason === "in_flight_budget_exhausted"
+    && error.metadata?.limit_source === "openrouter_in_flight_budget"
+    && error.metadata?.provider_name === null
+    && value.choices === undefined && value.output === undefined && value.usage === undefined;
+}
+
+export function createBudgetedProviderFetch({ budget, fetchImpl = fetch, modelCatalog } = {}) {
+  let modelsPromise;
+  // Hold one admission slot through response consumption and settlement. A
+  // second request must not exhaust the paper on an in-flight ceiling that is
+  // about to be released by the first request's usage receipt.
+  let admission = Promise.resolve();
+  async function acquire(signal) {
+    const previous = admission;
+    let unlock;
+    admission = new Promise((resolve) => { unlock = resolve; });
+    await previous;
+    if (signal?.aborted) { unlock(); signal.throwIfAborted(); }
+    return unlock;
+  }
+  async function transact(body) {
+    const response = await fetchImpl(budget.url, {
+      method: "POST", headers: { "content-type": "application/json", "x-citeark-budget-token": budget.token },
+      body: JSON.stringify({ ...body, kind: "model", workerId: budget.workerId }),
+      signal: AbortSignal.timeout(20_000),
+    });
+    if (!response.ok) throw budgetFailure("无法确认论文剩余预算，停止新的模型支出");
+    const result = await response.json();
+    if (!result.budget?.authorized) throw budgetFailure("论文累计预算不足，停止新的模型支出");
+    return result;
+  }
+  return async (url, options = {}) => {
+    const endpoint = new URL(url);
+    if ((options.method ?? "GET") === "GET") return fetchImpl(url, options);
+    if (endpoint.hostname !== "openrouter.ai"
+      || !/\/(chat\/completions|responses)$/.test(endpoint.pathname)) {
+      throw budgetFailure("该模型接口尚无可执行的费用上限，禁止启动付费请求");
+    }
+    if (!modelsPromise) modelsPromise = modelCatalog ? Promise.resolve(modelCatalog)
+      : fetchImpl("https://openrouter.ai/api/v1/models", { signal: AbortSignal.timeout(15_000) })
+        .then(async (response) => { if (!response.ok) throw budgetFailure("模型价格不可用"); return (await response.json()).data; })
+        .catch((error) => { modelsPromise = null; throw budgetFailure(error.message); });
+    const payload = JSON.parse(Buffer.from(options.body).toString("utf8"));
+    const models = await modelsPromise;
+    const quote = quoteBudgetedModelRequest(payload, models);
+    const unlock = await acquire(options.signal);
+    let streaming = false;
+    try {
+      const key = `model:${randomUUID()}`;
+      await transact({ action: "reserve", key, maximumCny: quote.maximumCny,
+        details: { model: payload.model, maximumTokens: quote.maximumTokens, source: "openrouter-catalog-with-price-ceiling" } });
+      // If delivery/completion is uncertain, retain the full reservation.
+      const headers = new Headers(options.headers);
+      headers.delete("content-length");
+      const response = await fetchImpl(url, { ...options, headers, body: JSON.stringify(quote.payload) });
+      if (!response.ok) {
+        // Only the router's explicit admission refusal is known to precede
+        // inference. Generic 402s and missing receipts do not prove zero spend.
+        if (response.status === 402 && (response.headers.get("content-type") ?? "").includes("application/json")) {
+          let rejected;
+          try { rejected = await response.clone().json(); } catch { /* Keep unknown holds. */ }
+          const generationId = response.headers.get("x-generation-id");
+          if (isOpenRouterAdmissionRefusal(rejected) && /^gen-[a-zA-Z0-9_-]{1,240}$/.test(generationId ?? "")) {
+            await transact({ action: "settle", key, actualCny: 0, details: {
+              providerCostUsd: 0, source: "openrouter-admission-refusal", generationId,
+              status: 402, reason: rejected.error.metadata.reason,
+              limitSource: rejected.error.metadata.limit_source,
+            } });
+          }
+        }
+        return response;
+      }
+      let cost = null;
+      let generationId = null;
+      let costSource = "provider-response";
+      function observe(line) {
+        try {
+          const value = JSON.parse(line.replace(/^data:\s*/, ""));
+          const candidateId = value.id ?? value.response?.id;
+          if (typeof candidateId === "string" && /^gen-[a-zA-Z0-9_-]{1,240}$/.test(candidateId)) generationId = candidateId;
+          const usage = value.usage ?? value.response?.usage;
+          if (typeof usage?.cost === "number" && Number.isFinite(usage.cost) && usage.cost >= 0) cost = usage.cost;
+        } catch { /* SSE comments and protocol delimiters are not usage. */ }
+      }
+      async function settle() {
+        // A completed response can omit usage. Reconcile the exact provider
+        // receipt once; never estimate actual spend or release an unknown hold.
+        if (cost === null && generationId) {
+          try {
+            const receipt = await fetchImpl(`https://openrouter.ai/api/v1/generation?id=${encodeURIComponent(generationId)}`, {
+              headers: { Authorization: headers.get("Authorization") ?? "" },
+              signal: AbortSignal.timeout(5_000),
+            });
+            if (receipt.ok) {
+              const data = (await receipt.json()).data;
+              if (data?.id === generationId && typeof data.total_cost === "number"
+                && Number.isFinite(data.total_cost) && data.total_cost >= 0) {
+                cost = data.total_cost;
+                costSource = "provider-generation-receipt";
+              }
+            }
+          } catch { /* Unavailable receipts retain the original reservation. */ }
+        }
+        if (cost === null) return;
+        await transact({ action: "settle", key, actualCny: monetaryCny(cost),
+          details: { providerCostUsd: cost, source: costSource, ...(generationId ? { generationId } : {}) } });
+      }
+      if (!response.body) return response;
+      if (!(response.headers.get("content-type") ?? "").includes("text/event-stream")) {
+        const bytes = await response.arrayBuffer();
+        observe(Buffer.from(bytes).toString("utf8"));
+        await settle();
+        return new Response(bytes, { status: response.status, headers: response.headers });
+      }
+      let pending = "";
+      const decoder = new TextDecoder();
+      const stream = response.body.pipeThrough(new TransformStream({
+        transform(chunk, controller) {
+          pending += decoder.decode(chunk, { stream: true });
+          const lines = pending.split("\n"); pending = lines.pop();
+          for (const line of lines) observe(line);
+          if (pending.length > 32 * 1024 * 1024) throw budgetFailure("模型响应超过预算审计边界");
+          controller.enqueue(chunk);
+        },
+        async flush() { observe(pending + decoder.decode()); await settle(); },
+      }));
+      const reader = stream.getReader();
+      const body = new ReadableStream({
+        async pull(controller) {
+          try {
+            const chunk = await reader.read();
+            if (chunk.done) { unlock(); controller.close(); }
+            else controller.enqueue(chunk.value);
+          } catch (error) { unlock(); controller.error(error); }
+        },
+        async cancel(reason) {
+          try { await reader.cancel(reason); } finally { unlock(); }
+        },
+      });
+      streaming = true;
+      return new Response(body, { status: response.status, headers: response.headers });
+    } finally {
+      if (!streaming) unlock();
+    }
+  };
+}
+
+export function quoteBudgetedModelRequest(payload, models) {
+  const model = models?.find((item) => item.id === payload.model);
+  const tiers = [model?.pricing, ...(Array.isArray(model?.pricing?.overrides) ? model.pricing.overrides : [])];
+  const prompt = Math.max(...tiers.map((p) => Number(p?.prompt ?? model?.pricing?.prompt)));
+  const completion = Math.max(...tiers.map((p) => Number(p?.completion ?? model?.pricing?.completion)), Number(model?.pricing?.internal_reasoning ?? 0));
+  const context = Number(model?.context_length);
+  if (!model || !Number.isFinite(prompt) || prompt < 0 || !Number.isFinite(completion)
+    || completion < 0 || !Number.isInteger(context) || context < 1) throw budgetFailure("模型价格或上下文上限缺失");
+  if (payload.plugins?.length || payload.web_search_options || payload.audio
+    || payload.modalities?.some((kind) => kind !== "text") || (payload.n ?? 1) !== 1
+    || payload.models?.length) throw budgetFailure("附加模型服务缺少可验证的费用上限");
+  const nonTokenCharges = Object.entries(model.pricing ?? {}).filter(([name, value]) =>
+    !new Set(["prompt", "completion", "request", "input_cache_read", "input_cache_write", "discount", "overrides", "image", "audio", "input_audio_cache", "web_search", "internal_reasoning"]).has(name)
+      && Number(value) > 0);
+  if (Number(model.pricing?.image ?? 0) > prompt || Number(model.pricing?.audio ?? 0) > prompt
+    || Number(model.pricing?.input_cache_write ?? 0) > prompt || Number(model.pricing?.input_cache_read ?? 0) > prompt) {
+    throw budgetFailure("输入或缓存单价超出令牌费用上限");
+  }
+  if (payload.tools?.some((tool) => tool.type !== "function" && tool.type !== "custom")) throw budgetFailure("付费内置工具缺少费用上限");
+  if (nonTokenCharges.length) throw budgetFailure("模型包含尚未纳入上限的附加计费项目");
+  const requested = payload.max_output_tokens ?? payload.max_completion_tokens ?? payload.max_tokens ?? 8192;
+  const maximumTokens = Math.min(Number(requested), Number(model.top_provider?.max_completion_tokens) || context, context);
+  if (!Number.isInteger(maximumTokens) || maximumTokens < 1) throw budgetFailure("模型输出上限无效");
+  const perRequest = Number(model.pricing?.request ?? 0);
+  if (!Number.isFinite(perRequest) || perRequest < 0) throw budgetFailure("模型请求价格缺失");
+  // A full context is an upper bound even for images/tool framing, independent
+  // of tokenizer guesses. Routing is restricted to these per-token ceilings.
+  const maximumCny = monetaryCny(context * prompt + maximumTokens * completion + perRequest);
+  const bounded = { ...payload, provider: { ...payload.provider, require_parameters: true,
+    max_price: { prompt: prompt * 1e6, completion: completion * 1e6, request: perRequest } } };
+  // OpenCode 1.18.14 and Codex 0.144.1 add this presentation default to GPT requests,
+  // even when the routed model does not support it. Omit only that known
+  // optional default when the catalog explicitly excludes it; keep required
+  // reasoning, tools, output limits and strict provider matching intact.
+  if (/^openai\/gpt-/.test(payload.model)
+    && Array.isArray(model.supported_parameters) && !model.supported_parameters.includes("verbosity")) {
+    if (payload.verbosity === "low") delete bounded.verbosity;
+    if (payload.text?.verbosity === "low") {
+      bounded.text = { ...payload.text };
+      delete bounded.text.verbosity;
+      if (Object.keys(bounded.text).length === 0) delete bounded.text;
+    }
+  }
+  // Codex emits a boolean parallel-tool hint even when the routed API does
+  // not support that parameter. For Responses, use the provider default
+  // when its catalog explicitly excludes the hint; tools remain intact.
+  if (/^openai\/gpt-/.test(payload.model) && payload.input !== undefined
+    && typeof payload.parallel_tool_calls === "boolean"
+    && Array.isArray(model.supported_parameters) && !model.supported_parameters.includes("parallel_tool_calls")) {
+    delete bounded.parallel_tool_calls;
+  }
+  if (payload.input !== undefined) bounded.max_output_tokens = maximumTokens;
+  else { bounded.max_tokens = maximumTokens; if (bounded.max_completion_tokens !== undefined) bounded.max_completion_tokens = maximumTokens; }
+  if (payload.stream && payload.input === undefined) bounded.stream_options = { ...payload.stream_options, include_usage: true };
+  return { maximumCny, maximumTokens, payload: bounded };
+}
+
+function monetaryCny(usd) { return Math.ceil(usd * 7.2 * 1.15 * 1e6) / 1e6; }
+function budgetFailure(message) {
+  return Object.assign(new Error(message), { paperBudget: true,
+    failureCode: "paper.budget_exhausted", failureCategory: "budget", retryable: false });
+}
+
+export function rewriteGeminiToolText(rawBody, upstream, pathname) {
+  if (new URL(upstream).hostname !== "openrouter.ai" || pathname !== "/v1/chat/completions") return rawBody;
+  const payload = JSON.parse(Buffer.from(rawBody ?? []).toString("utf8"));
+  if (!/^google\/gemini-/i.test(payload.model ?? "") || !Array.isArray(payload.messages)) return rawBody;
+  let changed = false;
+  const messages = payload.messages.map((message) => {
+    if (message.role !== "tool" || typeof message.content !== "string") return message;
+    changed = true;
+    // Preserve the literal result inside a string: Gemini interprets a top-level
+    // parsed $ref as a multimodal part reference, including nested JSON Schemas.
+    return { ...message, content: JSON.stringify({ text: message.content }) };
+  });
+  return changed ? Buffer.from(JSON.stringify({ ...payload, messages })) : rawBody;
+}
+
+function providerRequestTimeoutMs() {
+  const seconds = process.env.CITEARK_PROVIDER_REQUEST_TIMEOUT_SECONDS;
+  if (seconds === undefined || seconds === "") return DEFAULT_PROVIDER_REQUEST_TIMEOUT_MS;
+  const numeric = Number(seconds);
+  if (!Number.isInteger(numeric) || numeric < 1 || numeric > 30 * 60) {
+    throw new Error("Provider 请求超时必须是 1–1800 秒的整数");
+  }
+  return numeric * 1000;
+}
+
+function positiveTimeoutMilliseconds(value) {
+  if (!Number.isInteger(value) || value < 1 || value > 30 * 60_000) {
+    throw new Error("Provider 请求超时必须是 1–1800000 毫秒的整数");
+  }
+  return value;
+}
+
+export function rewriteCodexRequest(rawBody, reasoningMode) {
+  let payload;
+  try {
+    payload = JSON.parse(Buffer.from(rawBody ?? []).toString("utf8"));
+  } catch {
+    throw new Error("Codex Responses 请求不是有效 JSON");
+  }
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new Error("Codex Responses 请求必须是对象");
+  }
+  const reasoning = payload.reasoning && typeof payload.reasoning === "object" && !Array.isArray(payload.reasoning)
+    ? payload.reasoning
+    : {};
+  return Buffer.from(JSON.stringify({
+    ...payload,
+    reasoning: { ...reasoning, mode: reasoningMode },
+  }));
+}
+
+function allowedRequest(method, pathname) {
+  if (method === "GET" && pathname === "/v1/models") return true;
+  return method === "POST" && new Set([
+    "/v1/responses",
+    "/v1/responses/compact",
+    "/v1/chat/completions",
+  ]).has(pathname);
+}
+
+function normalizedUpstream(value) {
+  if (!value?.trim()) throw new Error("Codex Pro relay 缺少上游 API 地址");
+  const url = new URL(value);
+  if (!new Set(["http:", "https:"]).has(url.protocol)) {
+    throw new Error("Codex Pro relay 上游只支持 HTTP(S)");
+  }
+  if (url.username || url.password || url.search || url.hash) {
+    throw new Error("Codex Pro relay 上游地址不能包含凭据、查询参数或片段");
+  }
+  return url.toString().replace(/\/$/, "").replace(/\/v1$/, "");
+}
+
+function forwardedHeaders(source, apiKey) {
+  const headers = new Headers();
+  for (const [name, rawValue] of Object.entries(source)) {
+    if (!rawValue) continue;
+    const lower = name.toLowerCase();
+    if (new Set(["host", "authorization", "connection", "content-length", "transfer-encoding"]).has(lower)) {
+      continue;
+    }
+    headers.set(name, Array.isArray(rawValue) ? rawValue.join(", ") : rawValue);
+  }
+  headers.set("authorization", `Bearer ${apiKey.trim()}`);
+  headers.set("content-type", "application/json");
+  return headers;
+}
+
+function responseHeaders(source) {
+  const headers = {};
+  for (const [name, value] of source.entries()) {
+    if (new Set(["connection", "content-length", "content-encoding", "transfer-encoding"]).has(name.toLowerCase())) {
+      continue;
+    }
+    headers[name] = value;
+  }
+  return headers;
+}
+
+async function readRequestBody(request, maxBodyBytes) {
+  const declared = Number(request.headers["content-length"] ?? 0);
+  if (declared > maxBodyBytes) throw new Error("Codex 请求体过大");
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of request) {
+    const buffer = Buffer.from(chunk);
+    total += buffer.byteLength;
+    if (total > maxBodyBytes) throw new Error("Codex 请求体过大");
+    chunks.push(buffer);
+  }
+  return Buffer.concat(chunks);
+}
+
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
+  const port = Number(process.env.CITEARK_CODEX_RELAY_PORT ?? 4317);
+  const server = createCodexProRelay();
+  server.listen(port, "127.0.0.1", () => {
+    console.log(JSON.stringify({ event: "codex_pro_relay.ready", port }));
+  });
+}