@citeark/agent 0.3.20

package/src/provider/completion.mjs

@@ -0,0 +1,292 @@
+import { researchSignal } from "../workspace/control.mjs";
+import { AGENT_RUNTIMES } from "../runtime/config.mjs";
+import {
+  isOpenRouterBaseUrl,
+  providerEndpoint,
+  runtimeProviderConfiguration,
+} from "./runtime-auth.mjs";
+
+// Opaque provider continuation stays in memory, never in transcripts or CAP.
+const continuation = Symbol("providerContinuation");
+export function modelProtocol(agent = {}) {
+  // Hosted OpenRouter reviews use the gateway's common completion interface.
+  if (isOpenRouterBaseUrl(runtimeProviderConfiguration(agent).baseUrl))
+    return "openai-chat-completions";
+  return (
+    agent.api?.protocol ??
+    AGENT_RUNTIMES[agent.runtime]?.apiProtocol ??
+    "openai-chat-completions"
+  );
+}
+
+export function buildModelRequest({
+  agent,
+  apiKey,
+  messages,
+  tools = [],
+  format,
+  maxTokens = 12000,
+  reasoning,
+  signal,
+}) {
+  if (agent?.codexAccountId || agent?.billingMode === "subscription") throw new Error("Subscription model calls must use createModelClient, never an API request");
+  if (researchSignal())
+    signal = signal
+      ? AbortSignal.any([signal, researchSignal()])
+      : researchSignal();
+  const { baseUrl, model } = runtimeProviderConfiguration(agent);
+  const protocol = modelProtocol(agent);
+  let resource, body;
+  const headers = {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+  };
+  if (protocol === "anthropic-messages") {
+    resource = "messages";
+    if (apiKey) headers["x-api-key"] = apiKey;
+    headers["anthropic-version"] = "2023-06-01";
+    const converted = [];
+    for (const message of messages.filter((m) => m.role !== "system")) {
+      const role = message.role === "tool" ? "user" : message.role;
+      const blocks = message[continuation] ?? anthropicBlocks(message);
+      if (converted.at(-1)?.role === role)
+        converted.at(-1).content.push(...blocks);
+      else converted.push({ role, content: [...blocks] });
+    }
+    body = {
+      model,
+      max_tokens: maxTokens,
+      system: messages
+        .filter((m) => m.role === "system")
+        .map((m) => m.content)
+        .join("\n"),
+      messages: converted,
+      ...(tools.length
+        ? {
+            tools: tools.map(({ function: f }) => ({
+              name: f.name,
+              description: f.description,
+              input_schema: f.parameters,
+            })),
+          }
+        : {}),
+      ...(format?.type === "json_schema"
+        ? {
+            output_config: {
+              format: {
+                type: "json_schema",
+                schema: format.json_schema.schema,
+              },
+            },
+          }
+        : {}),
+    };
+  } else if (protocol === "openai-responses") {
+    resource = "responses";
+    if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
+    body = {
+      model,
+      store: false,
+      include: ["reasoning.encrypted_content"],
+      max_output_tokens: maxTokens,
+      input: messages.flatMap((message) => {
+        if (message[continuation]) return message[continuation];
+        if (message.role === "tool")
+          return [
+            {
+              type: "function_call_output",
+              call_id: message.tool_call_id,
+              output: message.content,
+            },
+          ];
+        const output = [];
+        if (message.content)
+          output.push({
+            role: message.role,
+            content: responseContent(message.content, message.role),
+          });
+        for (const call of message.tool_calls ?? [])
+          output.push({
+            type: "function_call",
+            call_id: call.id,
+            name: call.function.name,
+            arguments: call.function.arguments,
+          });
+        return output;
+      }),
+      ...(tools.length
+        ? {
+            tools: tools.map(({ function: f }) => ({
+              type: "function",
+              ...f,
+              strict: false,
+            })),
+            tool_choice: "auto",
+          }
+        : {}),
+      ...(format
+        ? {
+            text: {
+              format:
+                format.type === "json_schema"
+                  ? { type: "json_schema", ...format.json_schema }
+                  : format,
+            },
+          }
+        : {}),
+    };
+  } else if (protocol === "openai-chat-completions") {
+    resource = "chat/completions";
+    if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
+    body = {
+      model,
+      messages,
+      max_tokens: maxTokens,
+      ...(tools.length ? { tools, tool_choice: "auto" } : {}),
+      ...(format ? { response_format: format } : {}),
+      ...(isOpenRouterBaseUrl(baseUrl)
+        ? {
+            reasoning: reasoning ?? { effort: agent.effort ?? "low" },
+            provider: { require_parameters: true },
+          }
+        : {}),
+    };
+  } else throw Error(`Unsupported model protocol: ${protocol}`);
+  return {
+    protocol,
+    url: providerEndpoint(baseUrl, resource),
+    init: { method: "POST", headers, body: JSON.stringify(body), signal },
+  };
+}
+
+export function readModelResponse(payload, protocol) {
+  if (protocol === "openai-chat-completions") return payload;
+  const blocks =
+    protocol === "openai-responses"
+      ? (payload.output ?? [])
+      : (payload.content ?? []);
+  const refused = blocks.some(
+    (b) =>
+      b.type === "refusal" ||
+      b.content?.some?.((item) => item.type === "refusal"),
+  );
+  const calls =
+    protocol === "openai-responses"
+      ? blocks
+          .filter((b) => b.type === "function_call")
+          .map((b) => ({
+            id: b.call_id,
+            type: "function",
+            function: { name: b.name, arguments: b.arguments },
+          }))
+      : blocks
+          .filter((b) => b.type === "tool_use")
+          .map((b) => ({
+            id: b.id,
+            type: "function",
+            function: { name: b.name, arguments: JSON.stringify(b.input) },
+          }));
+  const content =
+    protocol === "openai-responses"
+      ? blocks
+          .filter((b) => b.type === "message")
+          .flatMap((b) => b.content ?? [])
+          .filter((b) => b.type === "output_text")
+          .map((b) => b.text)
+          .join("\n")
+      : blocks
+          .filter((b) => b.type === "text")
+          .map((b) => b.text)
+          .join("\n");
+  const message = {
+    role: "assistant",
+    content: content || null,
+    ...(calls.length ? { tool_calls: calls } : {}),
+  };
+  Object.defineProperty(message, continuation, {
+    value: blocks,
+    enumerable: true,
+  });
+  const usage = payload.usage;
+  const incomplete =
+    refused ||
+    payload.error ||
+    ["incomplete", "failed", "cancelled"].includes(payload.status) ||
+    ["max_tokens", "refusal"].includes(payload.stop_reason);
+  return {
+    id: payload.id,
+    model: payload.model,
+    usage: usage
+      ? {
+          ...usage,
+          prompt_tokens: usage.input_tokens,
+          completion_tokens: usage.output_tokens,
+          prompt_tokens_details: {
+            cached_tokens:
+              usage.input_tokens_details?.cached_tokens ??
+              usage.cache_read_input_tokens ??
+              0,
+          },
+        }
+      : undefined,
+    choices: [
+      {
+        message,
+        finish_reason: incomplete
+          ? "length"
+          : calls.length
+            ? "tool_calls"
+            : "stop",
+      },
+    ],
+  };
+}
+
+function responseContent(content, role) {
+  if (typeof content === "string") return content;
+  return content.map((block) =>
+    block.type === "image_url"
+      ? {
+          type: "input_image",
+          image_url: block.image_url.url,
+          detail: block.image_url.detail ?? "auto",
+        }
+      : {
+          type: role === "assistant" ? "output_text" : "input_text",
+          text: block.text,
+        },
+  );
+}
+
+function anthropicBlocks(message) {
+  if (message.role === "tool")
+    return [
+      {
+        type: "tool_result",
+        tool_use_id: message.tool_call_id,
+        content: message.content,
+      },
+    ];
+  const blocks =
+    typeof message.content === "string"
+      ? [{ type: "text", text: message.content }]
+      : (message.content ?? []).map((block) => {
+          if (block.type !== "image_url")
+            return { type: "text", text: block.text };
+          const data = /^data:([^;]+);base64,(.*)$/s.exec(block.image_url.url);
+          return {
+            type: "image",
+            source: data
+              ? { type: "base64", media_type: data[1], data: data[2] }
+              : { type: "url", url: block.image_url.url },
+          };
+        });
+  for (const call of message.tool_calls ?? [])
+    blocks.push({
+      type: "tool_use",
+      id: call.id,
+      name: call.function.name,
+      input: JSON.parse(call.function.arguments),
+    });
+  return blocks;
+}

package/src/provider/model-client.mjs

@@ -0,0 +1,44 @@
+import { buildModelRequest, readModelResponse } from './completion.mjs';
+import { resolveProviderApiKey } from './runtime-auth.mjs';
+import { modelRoute } from './model-route.mjs';
+import { completeWithCodex } from './codex-completion.mjs';
+import { executeObservedExternalRequest, emitStructuredObservation } from '../observability/event-contract.mjs';
+import { createBudgetedProviderFetch } from '../../docker/claude-code/codex-pro-relay.mjs';
+
+// All bounded research model calls select transport and credentials here.
+// Scientific callers own prompts, evidence tools and validation, never routing.
+export function createModelClient({ runtimeAgent, providerSecret, fetchImpl = fetch, secretManager,
+  paperBudget, observe, correlation, codex = {} } = {}) {
+  const route = modelRoute(runtimeAgent);
+  let credential;
+  const request = paperBudget ? createBudgetedProviderFetch({ budget: paperBudget, fetchImpl }) : fetchImpl;
+  return { route, async complete({ phase = 'model_completion', component = 'research_model', reader,
+    timeoutMs, maxToolCalls, ...input }) {
+    if (route.transport === 'codex_subscription') {
+      const startedAt = new Date().toISOString();
+      try {
+        const result = await completeWithCodex({ ...codex, ...input, runtimeAgent, reader, timeoutMs, maxToolCalls });
+        (observe ?? emitStructuredObservation)({ schemaVersion: '1.0', kind: 'model_call', component, operation: phase,
+          correlation, model: route.model, transport: route.transport, billingMode: route.billingMode,
+          outcome: { status: 'succeeded' }, sessionId: result.id, usage: result.usage,
+          timing: { startedAt, finishedAt: new Date().toISOString() } });
+        return result;
+      } catch (error) {
+        (observe ?? emitStructuredObservation)({ schemaVersion: '1.0', kind: 'model_call', component, operation: phase,
+          correlation, model: route.model, transport: route.transport, billingMode: route.billingMode,
+          outcome: { status: 'failed', code: error.failureCode }, timing: { startedAt, finishedAt: new Date().toISOString() } });
+        throw error;
+      }
+    }
+    if (runtimeAgent.paperBudgetEnforced && !paperBudget) throw Error('required paper budget is missing');
+    if (!route.baseUrl || !route.model) throw Error('Model API is not configured');
+    credential ??= await resolveProviderApiKey({ runtimeAgent, providerSecret, secretManager });
+    if (!credential && route.provider === 'openrouter.ai') throw Error('Model provider credential is missing');
+    const prepared = buildModelRequest({ ...input, agent: runtimeAgent, apiKey: credential, tools: reader?.definitions ?? input.tools });
+    const response = await executeObservedExternalRequest({ component, service: route.provider,
+      operation: phase, method: 'POST', url: prepared.url, correlation, observe, retryableStatus: () => false,
+      request: () => request(prepared.url, prepared.init) });
+    if (!response.ok) throw Object.assign(Error(`Model provider HTTP ${response.status}`), { httpStatus: response.status });
+    return { ...readModelResponse(await response.json(), prepared.protocol), transport: route.transport, billingMode: route.billingMode };
+  } };
+}

package/src/provider/model-route.mjs

@@ -0,0 +1,29 @@
+import { CiteArkError } from '../util.mjs';
+import { runtimeProviderConfiguration } from './runtime-auth.mjs';
+
+// A selected subscription is authoritative. No API endpoint, key, or fallback
+// may turn a failed subscription operation into a metered provider request.
+export function modelRoute(agent = {}) {
+  if (agent.codexAccountId || agent.billingMode === 'subscription') {
+    if (agent.runtime !== 'codex' || !/^[a-z0-9][a-z0-9-]{0,47}$/.test(agent.codexAccountId ?? '')
+      || !validNativeModel(agent.model)
+      || (agent.reasoningMode && agent.reasoningMode !== 'standard')) {
+      throw subscriptionUnavailable('Codex 订阅配置无效', 'codex.account_invalid_configuration');
+    }
+    return { transport: 'codex_subscription', billingMode: 'subscription', provider: 'OpenAI',
+      model: agent.model, nativeModel: agent.model.replace(/^openai\//, ''), accountId: agent.codexAccountId };
+  }
+  const { baseUrl, model } = runtimeProviderConfiguration(agent);
+  return { transport: 'api', billingMode: agent.billingMode ?? 'platform',
+    provider: baseUrl ? new URL(baseUrl).hostname : null, model, baseUrl };
+}
+
+export function subscriptionUnavailable(message, failureCode = 'codex.subscription_unavailable', details = {}) {
+  return new CiteArkError(message, { retryable: false, failureCode, failureCategory: 'provider',
+    retryDisposition: 'never', failureOwner: 'platform',
+    recoveryAction: '恢复同一 Codex 订阅账号后从已保存阶段继续；不会转用 API 或其他账号', ...details });
+}
+
+export function validNativeModel(model) {
+  return typeof model === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(model.replace(/^openai\//, ''));
+}

package/src/provider/openrouter-readiness.mjs

@@ -0,0 +1,189 @@
+import { modelRoute } from "./model-route.mjs";
+import { CiteArkError } from "../util.mjs";
+import {
+  isOpenRouterBaseUrl,
+  providerEndpoint,
+  resolveProviderApiKey,
+  runtimeProviderConfiguration,
+} from "./runtime-auth.mjs";
+
+const DEFAULT_MINIMUM_BALANCE_USD = 2;
+
+/**
+ * 在启动 Research Compiler、资产准备或 GPU 前检查 OpenRouter 账户是否可用。
+ * 普通 API Key 无权访问 /credits 时退回 /key；如果两者都无法给出余额，发送最多
+ * 1 个输出 token 的同模型探针，以便至少在余额为零或模型不可用时提前停止。
+ */
+export async function checkOpenRouterReadiness({
+  runtimeAgent,
+  providerSecret,
+  minimumBalanceUsd = DEFAULT_MINIMUM_BALANCE_USD,
+  fetchImpl = fetch,
+  secretManager,
+  timeoutMs = 15_000,
+} = {}) {
+  const route = modelRoute(runtimeAgent);
+  if (route.transport === "codex_subscription") return { status: "not_applicable", provider: "codex_subscription", billingMode: "subscription", checkedAt: new Date().toISOString() };
+  const configuration = runtimeProviderConfiguration(runtimeAgent);
+  if (!isOpenRouterBaseUrl(configuration.baseUrl)) {
+    return { status: "not_applicable", provider: "other", checkedAt: new Date().toISOString() };
+  }
+  const apiKey = await resolveProviderApiKey({ runtimeAgent, providerSecret, secretManager });
+  if (!apiKey) throw providerActionRequired("OpenRouter API 密钥不可用", "provider_credential_unavailable");
+
+  const headers = { Authorization: `Bearer ${apiKey}`, Accept: "application/json" };
+  const credits = await providerGet({
+    url: providerEndpoint(configuration.baseUrl, "credits"),
+    headers,
+    fetchImpl,
+    timeoutMs,
+  });
+  let source = "credits";
+  let remainingUsd = credits.ok ? creditsRemaining(credits.body) : null;
+  if (!credits.ok && credits.status !== 401) {
+    const key = await providerGet({
+      url: providerEndpoint(configuration.baseUrl, "key"),
+      headers,
+      fetchImpl,
+      timeoutMs,
+    });
+    source = "key";
+    if (!key.ok) throw providerHttpError(key.status);
+    remainingUsd = keyRemaining(key.body);
+  } else if (!credits.ok) {
+    throw providerHttpError(credits.status);
+  }
+
+  const threshold = finiteNonNegative(minimumBalanceUsd, DEFAULT_MINIMUM_BALANCE_USD);
+  if (remainingUsd !== null && remainingUsd < threshold) {
+    throw providerActionRequired(
+      `OpenRouter 可用余额 $${remainingUsd.toFixed(2)}，低于启动下一阶段所需的安全下限 $${threshold.toFixed(2)}`,
+      "provider_balance_insufficient",
+    );
+  }
+  let probe = null;
+  if (remainingUsd === null) {
+    probe = await providerProbe({
+      url: providerEndpoint(configuration.baseUrl, "chat/completions"),
+      headers,
+      model: configuration.model,
+      fetchImpl,
+      timeoutMs,
+    });
+  }
+  return {
+    status: remainingUsd === null ? "available_unquantified" : "available",
+    provider: "openrouter",
+    source,
+    remainingUsd,
+    minimumBalanceUsd: threshold,
+    ...(probe ? { probe } : {}),
+    checkedAt: new Date().toISOString(),
+  };
+}
+
+async function providerProbe({ url, headers, model, fetchImpl, timeoutMs }) {
+  if (!model) throw providerActionRequired("OpenRouter 预检缺少目标模型", "provider_model_unavailable");
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      method: "POST",
+      headers: { ...headers, "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model,
+        messages: [{ role: "user", content: "Reply OK." }],
+        max_tokens: 1,
+        temperature: 0,
+        reasoning: { effort: "low", exclude: true },
+      }),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (error) {
+    throw new CiteArkError("OpenRouter 同模型探针暂时无法连接供应商", {
+      cause: error,
+      retryable: true,
+      failureCode: "provider_readiness_unavailable",
+      failureCategory: "provider",
+      retryDisposition: "retry_same_inputs",
+    });
+  }
+  if (!response.ok) throw providerHttpError(response.status);
+  return { status: "passed", model, maximumOutputTokens: 1 };
+}
+
+async function providerGet({ url, headers, fetchImpl, timeoutMs }) {
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      method: "GET",
+      headers,
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (error) {
+    throw new CiteArkError("OpenRouter 余额预检暂时无法连接供应商", {
+      cause: error,
+      retryable: true,
+      failureCode: "provider_readiness_unavailable",
+      failureCategory: "provider",
+      retryDisposition: "retry_same_inputs",
+    });
+  }
+  let body = null;
+  try {
+    body = await response.json();
+  } catch {
+    // 状态码足以分类；不保留可能包含敏感内容的响应正文。
+  }
+  return { ok: response.ok, status: response.status, body };
+}
+
+function creditsRemaining(body) {
+  const data = body?.data ?? body;
+  const total = finite(data?.total_credits);
+  const used = finite(data?.total_usage);
+  return total === null || used === null ? null : Math.max(0, total - used);
+}
+
+function keyRemaining(body) {
+  const data = body?.data ?? body;
+  return finite(data?.limit_remaining);
+}
+
+function providerHttpError(status) {
+  if (status === 401 || status === 403) {
+    return providerActionRequired("OpenRouter 拒绝了当前 API 密钥", "provider_credential_rejected");
+  }
+  if (status === 402) {
+    return providerActionRequired("OpenRouter 账户余额不足", "provider_balance_insufficient");
+  }
+  return new CiteArkError(`OpenRouter 余额预检失败（HTTP ${status}）`, {
+    retryable: status === 408 || status === 429 || status >= 500,
+    failureCode: "provider_readiness_unavailable",
+    failureCategory: "provider",
+    retryDisposition: "retry_same_inputs",
+  });
+}
+
+function providerActionRequired(message, failureCode) {
+  return new CiteArkError(message, {
+    retryable: false,
+
+    failureCode,
+    failureCategory: "provider",
+    retryDisposition: "never",
+    recoveryAction: "充值或更换可用的 OpenRouter API 密钥后，从原任务现场继续",
+  });
+}
+
+function finite(value) {
+  if (value === null || value === undefined || value === "") return null;
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? number : null;
+}
+
+function finiteNonNegative(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? number : fallback;
+}
+
+export const checkModelReadiness = checkOpenRouterReadiness;

package/src/provider/reader-bridge.mjs

@@ -0,0 +1,35 @@
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+
+export async function startModelReaderBridge(reader, { maxToolCalls = Infinity, onLimitExceeded = () => {} } = {}) {
+  const token = randomBytes(24).toString("hex");
+  let calls = 0, exhausted = false;
+  const definitions = reader.definitions.map(({ function: tool }) => ({ name: tool.name, description: tool.description,
+    inputSchema: tool.parameters, annotations: { readOnlyHint: true, destructiveHint: false } }));
+  const server = createServer(async (request, response) => {
+    try {
+      if (request.method !== "POST" || request.headers.authorization !== `Bearer ${token}`) { response.writeHead(403).end(); return; }
+      const chunks = []; let size = 0;
+      for await (const chunk of request) { size += chunk.length; if (size > 1_000_000) throw new Error("Oversized tool request"); chunks.push(chunk); }
+      const message = JSON.parse(Buffer.concat(chunks));
+      let value;
+      if (message.method === "tools/list") value = { tools: definitions };
+      else if (message.method === "tools/call") {
+        if (++calls > maxToolCalls) {
+          exhausted = true; onLimitExceeded();
+          throw new Error("Source inspection exceeded its bounded tool allowance");
+        }
+        if (!definitions.some((tool) => tool.name === message.params?.name)) throw new Error("Source inspection tool is unavailable");
+        const output = await reader.execute(message.params.name, message.params.arguments ?? {});
+        value = { content: [{ type: "text", text: JSON.stringify(output.value) },
+          ...(output.images ?? []).flatMap((image) => [{ type: "text", text: `Original physical PDF page ${image.page}` },
+            { type: "image", data: image.data, mimeType: "image/jpeg" }])] };
+      } else throw new Error("Unsupported reader method");
+      response.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(value));
+    } catch (error) { response.writeHead(400).end(JSON.stringify({ error: error.message })); }
+  });
+  await new Promise((resolve, reject) => { server.once("error", reject); server.listen(0, "127.0.0.1", resolve); });
+  return { endpoint: `http://127.0.0.1:${server.address().port}`, token, get exhausted() { return exhausted; },
+    close: () => new Promise((resolve) => { server.close(resolve); server.closeAllConnections(); }) };
+}
+